Collect Card Details

Overview

The collectPAN() method securely collects credit card details from users through an isolated iframe. The card data is tokenized via PCI Data Vault and provisioned with card network, ensuring PCI compliance without card data ever touching your servers.

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 via POST /v1/sessions

container

string

required

CSS selector for the iframe container element (e.g., #card-form)

onReady

() => void

Callback fired when the iframe is loaded and ready for input

onChange

(state: CardValidationState) => void

Callback fired when card input validation state changes

onSuccess

(result: CollectPANResult) => void

Callback fired when card collection completes successfully

onError

(error: PravaError) => void

Callback fired when an error occurs

styles

object

Custom CSS styles for the iframe form fields

Return Value

result

CollectPANResult

Show properties

enrollment_id

string

Unique identifier for this card enrollment

card_last4

string

Last 4 digits of the card number

card_brand

string

Card brand (visa, mastercard, amex, discover)

card_exp_month

number

Card expiration month (1-12)

card_exp_year

number

Card expiration year (4 digits)

vProvisionedTokenID

string

Card network provisioned token identifier

Example

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

function CardEnrollment() {
  const [loading, setLoading] = useState(false);
  const [sessionToken, setSessionToken] = useState<string | null>(null);

  const prava = new PravaSDK({
    publishableKey: 'pk_sandbox_your_key',
    environment: 'sandbox'
  });

  // Get session token from your backend
  useEffect(() => {
    fetch('/api/create-session', { method: 'POST' })
      .then(r => r.json())
      .then(data => setSessionToken(data.session_token));
  }, []);

  const handleCollect = async () => {
    if (!sessionToken) return;

    setLoading(true);
    
    try {
      const result = await prava.collectPAN({
        sessionToken,
        container: '#card-form',
        onReady: () => {
          console.log('Form ready');
        },
        onChange: (state) => {
          console.log('Validation:', state);
        },
        onSuccess: (data) => {
          console.log('Card enrolled:', data.card_last4);
          // Navigate to success page or next step
        },
        onError: (error) => {
          console.error('Error:', error);
          setLoading(false);
        }
      });
    } catch (error) {
      console.error('Collection failed:', error);
      setLoading(false);
    }
  };

  return (
    <div>
      <div id="card-form"></div>
      <button onClick={handleCollect} disabled={loading || !sessionToken}>
        {loading ? 'Processing...' : 'Add Card'}
      </button>
    </div>
  );
}

Flow Diagram

Under the Hood

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

Iframe Injection

The SDK injects a secure, isolated iframe into your specified container. The iframe is served from Prava’s domain to ensure zero PCI scope.

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, name) in the iframe form with real-time validation.

PCI Data Vault Vaulting

When the user submits, the iframe sends the card data directly to PCI Data Vault for tokenization. Your servers never see the raw PAN.

Card Network Provisioning

Prava’s backend retrieves the encrypted payment instrument from PCI Data Vault and provisions a token with card network, binding it to the user’s device via FIDO.

Result

The enrollment result (with last4, brand, vProvisionedTokenID) is returned to your app.

Validation States

The onChange callback receives a CardValidationState object:

interface CardValidationState {
  valid: boolean;
  errors: {
    cardNumber?: string;
    expiry?: string;
    cvv?: string;
    name?: string;
  };
}

Error Handling

error

PravaError

Show properties

code

string

Error code (e.g., SESSION_EXPIRED, INVALID_CARD, NETWORK_ERROR)

message

string

Human-readable error message

details

object

Additional error context

Common Errors

Code	Cause	Resolution
`SESSION_EXPIRED`	Session token expired (15 min)	Create new session
`SESSION_INVALID`	Invalid or tampered session token	Verify backend logic
`INVALID_CARD`	Card failed Luhn check or format	User re-enters card
`CARD_DECLINED`	Issuer declined enrollment	User tries different card
`NETWORK_ERROR`	Connection issue	Retry after delay

Security Notes

Never attempt to bypass the iframe or collect card data directly. This breaks PCI compliance and exposes your infrastructure to liability.

The iframe uses Content Security Policy (CSP), Subresource Integrity (SRI), and strict origin validation to prevent XSS and data exfiltration.

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