Collect Card Details

Overview

The collectPAN() method securely collects credit card details from users through an isolated iframe. The card data is tokenized via Prava’s PCI DSS vault and returns only safe metadata — your servers never see the raw PAN.

Method Signature

prava.collectPAN(options: CollectPANOptions): Promise<CollectPANResult>

Parameters

options

CollectPANOptions

required

Configuration options for card collection

Show properties

sessionToken

string

required

Session token obtained from your backend

iframeUrl

string

required

Iframe URL from your backend session response

container

string | HTMLElement

required

CSS selector or DOM element to mount the card form (e.g., #card-form)

onReady

() => void

Called when the iframe is loaded and ready for input

onChange

(state: CardValidationState) => void

Real-time validation state on every keystroke

onSuccess

(result: CollectPANResult) => void

Called on successful card enrollment

onError

(error: PravaError) => void

Called on error

styles

CardFormStyles

Custom styles for the card form

Return Value

result

CollectPANResult

Show properties

enrollmentId

string

Unique card identifier (use this for intents)

last4

string

Last 4 digits of the card number

brand

string

Card brand (visa, etc.)

expMonth

number

Card expiration month (1-12)

expYear

number

Card expiration year (4 digits)

Example

import { useEffect, useRef, useState } from 'react';
import { PravaSDK } from '@prava-sdk/core';
import type { CollectPANResult } from '@prava-sdk/core';

function CardEnrollment({ session }: { session: { session_token: string; iframe_url: string } }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const sdkRef = useRef<PravaSDK | null>(null);
  const [enrolled, setEnrolled] = useState<CollectPANResult | null>(null);

  useEffect(() => {
    const sdk = new PravaSDK({ publishableKey: 'pk_live_xxx' });
    sdkRef.current = sdk;
    return () => sdk.destroy();
  }, []);

  const handleEnroll = async () => {
    if (!sdkRef.current || !containerRef.current) return;

    const result = await sdkRef.current.collectPAN({
      sessionToken: session.session_token,
      iframeUrl: session.iframe_url,
      container: containerRef.current,
      onReady: () => console.log('Form loaded'),
      onChange: (state) => {
        console.log('Complete:', state.isComplete);
      },
      onSuccess: (data) => {
        console.log(`Enrolled: •••• ${data.last4}`);
        setEnrolled(data);
      },
      onError: (err) => console.error(err.code, err.message),
    });
  };

  return (
    <div>
      <div ref={containerRef} />
      <button onClick={handleEnroll}>Enroll Card</button>
      {enrolled && <p>Card enrolled: {enrolled.brand} •••• {enrolled.last4}</p>}
    </div>
  );
}

<div id="card-form"></div>
<button id="submit-btn" disabled>Enroll Card</button>

Flow Diagram

Under the Hood

When you call collectPAN(), here’s what happens:

Iframe Injection

The SDK injects a secure, sandboxed iframe into your specified container. The iframe is served from Prava’s domain — card data never touches your DOM or servers.

Session Validation

The iframe validates the session token with Prava’s backend to ensure the request is legitimate and not expired.

User Input

The user enters their card details (number, expiry, CVV) in the iframe form with real-time validation.

PCI DSS Vaulting

When the user submits, the iframe tokenizes the PAN via Prava’s PCI DSS vault. Your servers never see the raw card number.

Result

The enrollment result (with enrollmentId, last4, brand, expMonth, expYear) is returned to your app.

Validation States

The onChange callback receives a CardValidationState object on every keystroke:

interface CardValidationState {
  cardNumber: FieldState;
  expiry: FieldState;
  cvv: FieldState;
  isComplete: boolean; // true when all fields are valid
}

interface FieldState {
  isEmpty: boolean;
  isValid: boolean;
  isFocused: boolean;
  error?: string;
}

Use isComplete to enable/disable your submit button:

onChange: (state) => {
  submitButton.disabled = !state.isComplete;
}

Error Handling

Common Errors

Code	Cause	Resolution
`SDK_ALREADY_ACTIVE`	`collectPAN` called while another session is active	Call `destroy()` first
`INVALID_CONFIG`	Missing `iframeUrl` or `publishableKey`	Check your config
`IFRAME_LOAD_ERROR`	Iframe failed to load	Check network, verify `iframeUrl`
`CARD_NOT_FOUND`	Card ID doesn’t exist or was removed	Re-enroll or use a different card

Security Notes

Never attempt to bypass the iframe or collect card data directly. The iframe is sandboxed with allow-scripts allow-same-origin allow-forms allow-popups — minimal permissions. Card data never touches your DOM, JS, or servers.

PostMessage communication is origin-locked. The iframe resolves its backend from its own hostname — merchants cannot inject a fake backend URL.

Getting Started

SDK Reference

Card Management

Intent Management

Payment Execution

Overview

Method Signature

Parameters

Return Value

Example

Flow Diagram

Under the Hood

Validation States

Error Handling

Common Errors

Security Notes

Next Steps

List Cards

Register Intent

Getting Started

SDK Reference

Card Management

Intent Management

Payment Execution

​Overview

​Method Signature

​Parameters

​Return Value

​Example

​Flow Diagram

​Under the Hood

​Validation States

​Error Handling

​Common Errors

​Security Notes

​Next Steps

List Cards

Register Intent

Overview

Method Signature

Parameters

Return Value

Example

Flow Diagram

Under the Hood

Validation States

Error Handling

Common Errors

Security Notes

Next Steps