Priority Vault is an enterprise tokenization solution that allows you to capture and manage 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.

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: Initialize the Widget

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

   Parameter	Required	Description
   clientSecret	✓	The unique key generated by your backend for this specific transaction.
   containerId	✓	The CSS selector (e.g., tokenize-container) where the widget will render.
   businessId	✓	Your assigned Priority business identifier.
   consentMode	✓	Source of the transaction: ECOM, MOTO
   environment (required or not, please confirm)		Environment to safely test or integrate: SANDBOX or LIVE (Default: LIVE).
   debug		Enable debug logging (Default: false).
   security(required or not in config section, please confirm)		Example: { allowedOrigin: 'https://yourdomain.com' }.
   onSuccess	Recommended	Called with full transaction result on success.
   onComplete	Recommended	Called after success with minimal completion payload.
   onError	Recommended	Called with error payload on failure.

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

   Parameter	Required	Description
   customer.id		Existing customer ID (e.g., cust_abc123) for returning users.
   address		Prefill billing details: line1, line2, city, state, postalCode, country (ISO 3166-1 alpha-2).
   billing		Control address collection. Please note that a merchant-level configuration is currently enabled on the widget to determine whether ZIP/AVS address details are mandatory for a specific merchant. If the AVS setting is enabled, the address fields will be displayed on the vaulting page, even if collectAddress is set to false.
   billing.collectAddress		Controls the ability to show the address or not ( true, false )
   billing.infoType		Controls the details of the billing information ( minimal, full ) Incase of minimal information you can add the country, Zip Code where as incase of full you can pass the country, Street Address, address2, city, state, zip code.

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

   Parameter	Required	Description
   payementMethod.showSavedCards		Display previously saved payment methods ( true, false) Please note: customerId is mandatory for incase you wish to display a saved card.

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

   Parameter	Required	Description
   security		To restrict embedding to your specific domain.
   metadata		Custom key/value pairs (e.g., { orderId: 'ord_123' }) attached to the session for backend reconciliation.

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

   Parameter	Required	Description
   theme		Customises the appearance of the Tokenized Widget. Please refer to the Customization & Branding for more reference.

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: Initialize the Widget when initializing the widget at Client side.

Handling Success/Failure

1. Vault Action Completion "onSuccess": This event triggers immediately when a vaulting action (Create, Update, or Delete) is successfully processed.

   • For Creation: The CARD_CREATE action returns a new secure token and masked card details.
   • For Updation: The CARD_UPDATE action returns a new secure token along with the updated masked card details.
   • For Card Deletion The CARD_DELETEaction returns the masked card details and the unique id of the vaulted card that was successfully removed from the Priority Vault.

   These are the following fields returned as payload nodes:

   Parameter	Description
   id	The internal Priority identifier for this specific vaulted card account.
   token	The non-reversible string used to trigger future payments.
   brand	The card network identified (e.g., VISA, MASTERCARD, AMEX).
   last4	The last four digits of the card, used for display and customer recognition.
   expiryMonth / Year	The expiration date of the card; essential for tracking card health.
   isDefault	A boolean (true/false) indicating if this is the customer's primary payment method.
   billingAddress	The address object associated with the card for AVS (Address Verification) checks.

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.

   Parameter	Description
   code	A machine-readable numeric code (e.g., 1001) for error logging.
   type	Categorizes the failure: VALIDATION_ERROR, PAYMENT_ERROR, or SYSTEM_ERROR.
   message	A human-readable description of the failure (e.g., "Validation error happened").

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.

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.