Integration Steps

Priority Vault is an enterprise tokenization solution that allows you to capture and manage customer payment identities without the risk of handling raw financial data. By utilizing a secure, hosted environment, it removes your application from PCI-DSS scope while providing a seamless "Digital Wallet" experience. Priority Vault handles the lifecycle of the payment method, including verification, storage, and expiry management of cards all under your own brand.

How it Works

The integration consists of two synchronized parts:

1. Server-Side: Generates a secure, short-lived "Client Secret" for each transaction.
2. Client-Side: Uses the secret token to mount the widget and handle user interactions.

This integration utilizes a secure, synchronized workflow to authorize, render, and finalize a protected payment session .

• Initiation: Your frontend requests a vaulting session from your backend.
• Authentication: Your backend authenticates with Priority API and requests a clientSecret.
• Handoff: Your backend passes the clientSecret to your frontend.
• Rendering: The frontend initializes the WidgetSDK using the secret.
• Completion: The user completes payment; the widget notifies your frontend via callbacks (onSuccess, onError).

The widget supports credit/debit cards vaulting as of today.

Server Side

The server-side implementation is the foundation of your security, acting as a protected bridge between your private credentials and the Priority Commerce Engine.

Step 1: Create a Vaulting Session

For every new vaulting attempt, your server must generate a unique, short-lived clientSecret using the POST/v1/client-secrets This token authenticates the widget without exposing your private API keys. You can refer to the below code for request, response and example to create client secret.

{
    "widgetType": "PAYMENT_METHOD_CAPTURE",
    "businessId": "{{businessId}}"
}

{
    "clientSecret": "cs_test_...",
    "expiresAt": "2026-02-28T12:00:00Z" "widgetType": "PAYMENT_METHOD_CAPTURE",
    "businessId": "{{businessId}}"
}

const response = await fetch(
  'https://sandbox-api.prioritycommerce.com/client-secrets',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SECRET_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      widgetType: 'PAYMENT_METHOD_CAPTURE',
      "businessId": "{{businessId}}"
    })
  }
);

const { clientSecret, expiresAt } = await response.json();

// Return clientSecret (and optionally expiresAt) to your frontend

Idempotency & Duplicate Prevention:

To prevent double-charging (e.g., if a user refreshes the page), ensure your backend logic checks if a successful transaction already exists for the current order Id before requesting a new secret.

Please ensure Client secrets expire (e.g. after 30 minutes); your frontend should request a new one if the user returns to widget page after expiry.

Client Side

The client-side phase focuses on the user experience, where the SDK takes over to render the secure interface and manage the payment lifecycle. By following these three steps, you will mount the widget into your UI and configure the real-time callbacks that guide your customers through a successful tokenization.

Step 1: Load the Widget

Include the widget library on the specific page where the tokenized card will appear. This exposes the global WidgetSDK object for you to use.

Loading the script directly from our secure Content Delivery Network ensures you are always using the latest, PCI-compliant version of the payment form without needing to manually update code.

<script src="https://sandbox-widgets.prioritycommerce.com/widgets-sdk/widget-sdk.js">
</script>

Step 2: Define the payment form

Reserve a DOM element (usually a div with an id) on your page where the widget will be rendered. You must ensure this element exists in your HTML before you attempt to initialize the WidgetSDK.create() .

The div id is variable. This container acts as a specific "placeholder" in your site's layout. It allows you to control exactly where the payment form appears (e.g., inside a dedicated "Payment Details" section), preserving your site’s design and user experience.

<div id="tokenize-container"></div> 

Step 3: Initialize the Widget

Call the WidgetSDK.create() method using the clientSecret you generated on your server (Server side - Step 1). This is where you pass configuration options like the transaction amount and user details.

This step allows you to pre-fill customer information (like email and billing address). Reducing the number of fields a customer has to type manually significantly increases conversion rates.

const widget = WidgetSDK.create('PAYMENT_METHOD_CAPTURE', {
  clientSecret: clientSecret, // From your backend
  containerId: 'tokenize-container',  // From your div ID
  businessId: 'biz_123', // Your assigned business ID
  consentMode: 'MOTO',
  onSuccess: (result) => {
    console.log('Payment successful:', result.transactionId);
    window.location.href = '/order/success';
  },
  onComplete: (result) => {
    // Optional: cleanup or analytics
  },
  onError: (error) => {
    console.error('Payment error:', error.message);
  }
});

const widget = WidgetSDK.create('PAYMENT_METHOD_CAPTURE', {
  clientSecret: clientSecret,
  containerId: '#tokenize-container',
  businessId: 'biz_123',
  consentMode: 'MOTO',
  environment: 'SANDBOX', // or 'LIVE'
  debug: false,
  customer: {
    id: 'cust_abc123'
  }, // returning customer
  address: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US'
  },
  billing: {
    collectAddress: true,
    infoType: 'full'
  },
  paymentMethods: {
    showSavedCards: true
  },
  security: {
    allowedOrigin: 'https://yourdomain.com'
  },
  metadata: {
    orderId: 'ord_xyz',
    source: 'web'
    },
theme: { /* WidgetTheme */ },
  onSuccess: (result) => {
    /* ... */
  },
  onError: (error) => {
    /* ... */
  },
  onCancel: () => {
    /* ... */
  }
});

Configuration Reference

This section provides a definitive guide to customising the widget's behavior, appearance, and data handling. It details every property you can pass into WidgetSDK.create(). i.e. Step 3

1. Base Configuration: These are the mandatory settings required to initialize the widget and link it to your specific transaction session

2. Customer & Address Configuration: Optional settings to pre-populate fields, reducing friction for the user.

4. Payment and Layout Method Configuration: These fields reflect which payment method will be shown and how on the widget it will look.

5. Security and MetaData: Advanced settings for security and data tracking.

6. Customize Vaulting: Customize vaulting, including branding such as color, radius, text etc

Event Handling

This event-driven feature ensures secure, real-time communication between your application and Priority’s hosted PCI environment, enabling seamless tokenization, operational visibility, and controlled user experience without exposing sensitive financial data.

📘

Please note: To configure the event callbacks refer to Step 3 when initializing the widget at Client side.

1. Vault Action Completion "onSuccess": This event triggers immediately when a vaulting action (Create, Update, or Delete) is successfully processed. It serves as the definitive signal to update your system with new tokens or remove old payment references.
   • For Creation or Updation: Use the CARD_CREATE | CARD_UPDATE fields to synchronize your local database with the new secure token and masked card details. These are the following fields returned as payload nodes:

• For Card Deletion Use this CARD_DELETE when a card is removed, the payload is minimized to provide just the identifier needed to update your UI.

2. Exception Handling "onError": This event is triggered if a vaulting action fails, whether due to an invalid card, a failed verification check, or a network interruption.

Operational Note: Always log the code and type for internal troubleshooting, but ensure your frontend displays a simplified, user-friendly message to guide the customer.

3. Interaction Tracking "onChange": This event fires in real-time as the user interacts with the Vault. It is vital for dynamic UI updates before the final submission.

Troubleshooting

To ensure system uptime and a seamless user experience, use the following to diagnose and resolve integration or transaction-level issues. The table below identifies common technical hurdles, the specific steps required to verify their root cause.

If these steps do not resolve the issue, capture the browser version, operating system, and the full onError payload to share with your integration support contact for an expedited resolution.

Support and Next Steps

To finalize your integration and move toward a production launch, follow these defined paths for testing and deployment.

Execution & Support Pathways

• Sandbox Testing: Utilize the sandbox environment with test credentials to validate your integration and simulate various transaction outcomes.
• Production Go-Live: Upon successful validation, your account team will provide live production endpoints, unique credentials, and a final go-live checklist.
• Technical Assistance: If you encounter unresolved issues, prepare your diagnostic logs, including the onError payload and browser environment details and share them with your integration or support contact.