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

onDismiss

(payload: { reason: string }) => void

Called when the user dismisses the payment flow

styles

CardFormStyles

Custom styles for the card form. Supports base, invalid, and focus states as CSS property maps.

Return Value

result

CollectPANResult

Show properties

enrollmentId

string

Unique identifier for the collected card

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)

The enrollmentId identifies the collected card on the server side. Use your backend and the API Reference to read payment results and report status for that card.

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>
  );
}

import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({ publishableKey: 'pk_live_xxx' });

// Get session from your backend
const session = await fetch('/api/session').then(r => r.json());

// Collect card via secure iframe
const card = await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onReady: () => console.log('Form loaded'),
  onChange: (state) => {
    document.getElementById('submit-btn').disabled = !state.isComplete;
  },
  onSuccess: (data) => {
    console.log(data.enrollmentId, data.last4, data.brand);
  },
  onError: (err) => console.error(err.code, err.message),
});

<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 collection is in progress	Call `destroy()` first
`INVALID_CONFIG`	Missing `iframeUrl` (or a bad `publishableKey`)	Pass the `iframe_url` from your backend session response
`IFRAME_LOAD_ERROR`	Iframe failed to load	Check network, verify `iframeUrl`
`SDK_INIT_ERROR`	SDK initialization failed	Verify browser compatibility and config

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 allow-popups-to-escape-sandbox and a permissions policy of payment; publickey-credentials-get; publickey-credentials-create. 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

Guides

Prava SDK

Prava MCP

Prava CLI

Resources

Overview

Method Signature

Parameters

Return Value

Example

Flow Diagram

Under the Hood

Validation States

Error Handling

Common Errors

Security Notes

Next Steps

List Cards (API)

Get Payment Result

​Overview

​Method Signature

​Parameters

​Return Value

​Example

​Flow Diagram

​Under the Hood

​Validation States

​Error Handling

​Common Errors

​Security Notes

​Next Steps

List Cards (API)

Get Payment Result

Overview

Method Signature

Parameters

Return Value

Example

Flow Diagram

Under the Hood

Validation States

Error Handling

Common Errors

Security Notes

Next Steps