Skip to main content

vdsdk - JavaScript Payment SDK

Overview​

The vdsdk is a client-side JavaScript SDK that enables secure payment collection in your customer portal. It provides a PCI-DSS compliant modal dialog for collecting card details and completing Visa Direct pull transactions.

Payment Flow​

1. Transaction Initiation (Backend)​

Your backend server initiates a payment session by calling the initiate-pull endpoint. See Initiate Pull Payment Documentation for details on authentication and request format.

The initiate call returns:

{
  "sessionId": "session-abc123",
  "endToEndId": "unique-transaction-id",
  "expiresAt": "2025-11-29T12:00:00Z"
}

2. Payment Collection (Customer Portal)​

Pass the ‘sessionId’ and ‘endToEndId’ to your customer portal and use the vdsdk to display a secure payment dialog where customers enter their card details.

The SDK handles:

  • Secure card data collection
  • Client-side validation
  • Client-side encryption (AES-256-GCM + RSA-OAEP)
  • Submission to the payment gateway
  • Transaction result

Integration​

Step 1: Include SDK Files​

Add the SDK to your customer portal page:

<link rel="stylesheet" href="BASE_URL/sdk/vd-sdk.css">
<script src="BASE_URL/sdk/vd-sdk.js"></script>

Step 2: Initialize SDK​

VDConnector.init({
  baseURL: 'BASE_URL'
});

Environment URLs:

  • Sandbox: ‘BASE_URL_SANDBOX’ (provided separately)
  • Production: ‘BASE_URL_PRODUCTION’ (provided separately)

Step 3: Display Payment Dialog​

After obtaining the ‘sessionId’ from the initiate-pull call, open the payment dialog:

VDConnector.openDialog(sessionId, endToEndId)
  .then(result => {
    // Payment successful
    console.log(‘Payment completed:’, result);
    // Redirect to confirmation page or show success message
  })
  .catch(error => {
    // Payment failed or cancelled
    if (error.message === ‘Transaction cancelled by user’) {
      console.log(‘User cancelled payment’);
    } else {
      console.error(‘Payment error:’, error.message);
    }
  });

API Reference​

VDConnector.init(options)​

Initialize the SDK with configuration.

Request Parameters
ParameterDescription
baseURL
Mandatory		String
Session ID returned from the initiate-pull API response.

Example:

VDConnector.init({
  baseURL: 'https://payments.example.com'
});

VDConnector.openDialog(sessionId, endToEndId, options)​

Opens a modal dialog for secure card data collection.

Request Parameters
ParameterDescription
sessionId
Mandatory		String
Session ID returned from the initiate-pull API response.
endToEndId
Mandatory		String
Unique transaction identifier generated from your system for tracking.
options
Optional		Object
Additional settings to customize the checkout dialog.
options.amount
Optional		Number
Display amount to be shown in the checkout dialog.

Returns: ‘Promise <Object> ’ - Resolves with transaction result or rejects on error/cancellation

Example:

const result = await VDConnector.openDialog(sessionId, endToEndId, {
  amount: 99.99
});

Success Response:

{
  "success": true,
  "transactionId": "txn-xyz789",
  "endToEndId": "order-12345",
  "amount": 99.99,
  "timestamp": "2025-11-29T10:30:00Z"
}

Dialog Features:

  • Modal overlay with backdrop
  • Close button and ESC key support
  • Click outside backdrop to cancel
  • Responsive design for mobile and desktop

VDConnector.isActive()​

Check if a payment dialog is currently open.

Returns: ‘boolean’

if (VDConnector.isActive()) {
  console.log('Payment dialog is already open');
}

VDConnector.close()​

Programmatically close the active payment dialog.

VDConnector.close();

Complete Example​

<!DOCTYPE html>
<html>
<head>
  <title>Complete Payment</title>
  <link rel="stylesheet" href="BASE_URL/sdk/vd-sdk.css">
</head>
<body>
  <button id="payButton">Pay Now</button>

  <script src="BASE_URL/sdk/vd-sdk.js"></script>
  <script>
    // Initialize SDK
    VDConnector.init({
      baseURL: 'BASE_URL'
    });

    // Session data from your backend (after initiate-pull call)
    const sessionId = '{{sessionId}}';
    const endToEndId = '{{orderId}}';
    const amount = {{amount}};

    // Handle payment button click
    document.getElementById('payButton').addEventListener(‘click’, async () => {
      try {
        const result = await VDConnector.openDialog(sessionId, endToEndId, {
          amount: amount
        });

        // Success - redirect to confirmation
        window.location.href = ‘/confirmation?txn=’ + result.transactionId;

      } catch (error) {
        if (error.message === ‘Transaction cancelled by user’) {
          alert(‘Payment cancelled’);
        } else {
          alert(‘Payment failed:’ + error.message);
        }
      }
    });
  </script>
</body>
</html>

Security​

Client-Side Encryption​

All card data is encrypted in the browser before transmission:

  1. AES-256-GCM encryption for card data with a randomly generated key
  2. RSA-OAEP encryption for the AES key using the gateway's public key
  3. Only encrypted data is transmitted over the network

PCI Compliance​

  • Card data is collected in an isolated iframe
  • Card data never touches your servers
  • Client-side encryption before transmission
  • Reduces your PCI compliance scope

Error Handling​

Error Message
ErrorDescription
‘Transaction cancelled by user’User closed the dialog or clicked cancel
‘A checkout session is already active’Another payment dialog is open
‘Invalid checkout session’Missing or invalid sessionId/endToEndId
‘Payment processing failed’Backend error during transaction processing

Example:

try {
  const result = await VDConnector.openDialog(sessionId, endToEndId);
  // Handle success
} catch (error) {
  if (error.message === ‘Transaction cancelled by user’) {
    // User cancelled - this is normal, not an error
  } else {
    // Actual error - show error message to user
    console.error(‘Payment error:’, error);
  }
}