Integration consists of server-side and client-side components that work together to securely capture and manage payment methods.

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

This integration utilizes a secure, synchronized workflow to authorize, render, and finalize a protected vaulting 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 submits payment method details; the widget notifies your frontend via callbacks (onSuccess, onError).

Before you begin

In addition to pre-requisites mentioned in Getting started section, you would need

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/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

Best Practices:

• Generate a new clientSecret for each session, do not reuse expired or consumed secrets.
• To prevent double-charging (e.g., if a user refreshes the page), ensure your backend logic checks if successful card details already exist for the current orderId before requesting a new secret.
• Ensure secrets expire after every session(e.g. within 30 minutes); your frontend should request a new one if the user returns to the 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. 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 tokenization form without needing to manually update code.

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

Step 2: Create a Container Element

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 tokenization form appears, 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.

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

  customer: {
    id: 'cust_abc123' // returning customer
  },

  consentMode: 'ECOM',

  onSuccess: (result) => {
    console.log('Vault successful:', result.data.card.id);
    window.location.href = '/order/success';
  },

  onError: (error) => {
    console.error('Vault error:', error.message);
  }
});

const widget = WidgetSDK.create('PAYMENT_METHOD_CAPTURE', {
  clientSecret: clientSecret,
  containerId: '#tokenize-container',
  businessId: 'biz_123',
  consentMode: 'ECOM',
  debug: false,

  address: {
    line1: '123 Main St',
    line2: 'Apt 4B',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US'
  },

  billing: {
    collectAddress: true,
    infoType: 'full'
  },

  paymentMethods: {
    showSavedCards: true
  },

  theme: {
    /* WidgetTheme */
  },

  onSuccess: (result) => {
    /* ... */
  },

  onError: (error) => {
    /* ... */
  }
});

Customization Reference

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

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

   Parameter	Required	Description
   clientSecret	✓	The unique key generated by your server for this specific session.
   containerId	✓	DOM element selector (e.g., tokenize-container) for widget placement.
   businessId	✓	Your assigned Priority business ID.
   consentMode	✓	Transaction type: ECOM, MOTO
   debug	Optional	Enable debug logging (Default: false).
   onSuccess	Recommended	Callback on token creation
   onError	Recommended	Callback on error.

2. Customer & Address Configuration: These optional settings allow you to pre-populate customer and billing related fields and the level of information required from the customer, reducing friction for the user.

   Parameter	Required	Description
   customer.id	Recommended	Passing this value associates the vaulting with a specific customer profile. This allows the widget to securely store payment methods for that customer and retrieve previously saved cards when enabled (when paymentMethods.showSavedCards is set to true).
   address	Optional	Defines billing address fields that may be collected during checkout, including address.line1, address.line2, address.city, address.state, address.postalCode, address.country (ISO 3166-1 alpha-2). This configuration allows you to pre-fill customer information. Reducing the number of fields a customer has to type manually, significantly increases conversion rates.
   billing.collectAddress	Optional	Determines whether address fields should be displayed on the form. true: Displays the address details on checkout form false : Hides the address details from the checkout form. Note: Address requirements may also depend on merchant-level AVS configuration. If AVS is enabled for the merchant, certain address fields (such as ZIP/Postal code) may be required and displayed on the form, even if billing.collectAddress is set to false. Please reach out to the PCE Account Management team to confirm the AVS and address configuration enabled for your account.
   billing.infoType	Optional	Specifies the level of billing information to be collected. minimal : Collects limited details such as address.country and address.postalCode. full : Collects complete billing address including address.line1, address.line2, address.city, address.state, address.country and address.postalCode. Note: Address requirements may also depend on merchant-level AVS configuration. If AVS is enabled for the merchant, certain address fields (such as ZIP/Postal code) may be required and displayed on the form, even if billing.collectAddress is set to false. Please reach out to the PCE Account Management team to confirm the AVS and address configuration enabled for your account.

3. Payment Method Configuration: These fields reflect which payment method will be shown and how on the widget it will look. Please note customer.id is required to display previously saved cards.

   Parameter	Required	Description
   payementMethod.showSavedCards	Optional	Displays previously saved cards associated with the customer. If true, saved cards are shown on the checkout form. If false, saved cards are not displayed.

4. Customize Vaulting: Configure the Vaulting experience to align with your brand, including visual elements such as colors, border radius, and text styling.

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.

onSuccess events for Create, Update and Delete actions

This event is triggered when the Create, Update and Delete vault actions complete successfully.

• Create Card: The CARD_CREATE action returns a new secure token and masked card details, as shown in the example below.
• Update Card: The CARD_UPDATE action returns a new secure token and updated masked card details, as shown in the example below.
• Delete Card The CARD_DELETEaction returns the masked card details and the unique id of the vaulted card that was successfully removed from the Priority Vault, as shown in the example below.

{
  "widgetType": "PAYMENT_METHOD_CAPTURE",
  "timestamp": 1772781431204,
  "status": "SUCCESS",
  "actions": [
    "CARD_CREATE"
  ],
  "data": {
    "card": {
      "id": "10000000598983",
      "token": "TOTVCQDTBH0QSXIQ6ZNG2FXDWF0EDV0N",
      "brand": "VISA",
      "last4": "0265",
      "name": "John",
      "type": "DEBIT",
      "expiryMonth": "01",
      "expiryYear": "2035",
      "isDefault": false,
      "billingAddress": {
        "address1": "dddjj",
        "address2": "kkkss",
        "city": "ddbbb",
        "state": "CO",
        "zip": "67898",
        "country": "US"
      }
    }
  },
  "customer": {
    "id": "10000000888479"
  }
}

{
  "widgetType": "PAYMENT_METHOD_CAPTURE",
  "timestamp": 1772781450263,
  "status": "SUCCESS",
  "actions": [
    "CARD_UPDATE"
  ],
  "data": {
    "card": {
      "id": "10000000598983",
      "token": "TOTVCQDTBH0QSXIQ6ZNG2FXDWF0EDV0N",
      "brand": "VISA",
      "last4": "0265",
      "name": "tripta jindalww",
      "type": "DEBIT",
      "expiryMonth": "01",
      "expiryYear": "2035",
      "isDefault": false,
      "billingAddress": {
        "address1": "dddjj",
        "address2": "kkkss",
        "city": "ddbbb",
        "state": "CO",
        "zip": "67898",
        "country": "US"
      }
    }
  },
  "customer": {
    "id": "10000000888479"
  }
}

{
    "widgetType": "PAYMENT_METHOD_CAPTURE",
    "timestamp": 1772781462660,
    "status": "SUCCESS",
    "actions": [
        "CARD_DELETE"
    ],
    "data": {
        "card": {
            "id": "10000000598983"
        }
    },
    "customer": {
        "id": "10000000888479"
    }
}

onError event

This event is triggered if a vaulting action fails due to validation, or system error. For example, the user submits invalid card details.

Best Practice: Log code and type internally; show a simplified message to the user. Avoid exposing internal error details.

{
    "widgetType": "PAYMENT_METHOD_CAPTURE",
    "status": "ERROR",
    "timestamp": 1772791413459,
    "data": {
        "code": "ValidationError",
        "type": "PAYMENT_METHOD_CAPTURE_ERROR",
        "message": "Card number is invalid"
    }
}

Troubleshooting

To ensure system uptime and a seamless user experience, use the following to diagnose and resolve integration or vaulting-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.

You can use the Card Test Data to simulate common card payment scenarios.

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 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.