Integrating the Checkout Widget is a streamlined process designed to get you from sandbox to your first successful transaction in minutes. By following this sequential workflow, you can securely initialize the SDK, mount the payment interface, and handle real-time event callbacks with minimal backend overhead .

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 checkout 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 as payment methods 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 Checkout Session

For every new checkout 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": "CHECKOUT",
    "businessId": "{{businessId}}"
}

{
    "clientSecret": "cs_test_...",
    "expiresAt": "2026-02-28T12:00:00Z" "widgetType": "CHECKOUT",
    "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: 'CHECKOUT',
      "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 checkout 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 checkout.

Step 1: Load the Widget - import module sdk

Include the widget library on the specific page where the checkout 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() .

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="checkout-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('CHECKOUT', {
  clientSecret: clientSecret, // From your backend
  containerId: 'checkout-container', // Fron your div ID
  businessId: 'biz_123', // Your assigned business ID
  transactionOrigin: 'CARD_PRESENT_KEYED',
  amount: {
    value: '50.00',
    currency: 'USD'
  },
  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('CHECKOUT', {
  clientSecret: clientSecret,
  containerId: '#checkout-container',
  businessId: 'biz_123',
  transactionOrigin: 'CARD_PRESENT_KEYED',
  environment: 'SANDBOX', // or 'LIVE'
  debug: false,
  amount: {
    value: '100.00',
    currency: 'USD'
  },
  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: {
    methods: {
      creditCard: true
    },
    enableCardSaving: true,
    showSavedCards: true
  },
  layout: {
    summary: {
      display: true,
      position: 'RIGHT',
      collapsible: true
    }
  },
  security: {
    allowedOrigin: 'https://yourdomain.com'
  },
  metadata: {
    orderId: 'ord_xyz',
    source: 'web'
    },
  theme: { /* WidgetTheme */ },
  onSuccess: (result) => {
    /* ... */
  },
  onError: (error) => {
    /* ... */
  },
  onCancel: () => {
    /* ... */
  }
});

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

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

2. Amount Configuration: This defines the transaction parameters that can be defined.

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

4. Payment Methods Configuration: These fields reflect which payment method will be shown.

4. Layout Configuration: These fields reflect how on the widget it will look.

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

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

Handling events After Payment Initiation

The Checkout Widget is event-driven and communicates transaction status directly to your application in real-time. Implementing callbacks is critical for managing user experience during declines and ensuring accurate backend reconciliation.

📘

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

Handling Success/Failure

1. Payment Completion "onSuccess": This event triggers immediately when a payment is successfully authorized and completed. It acts as the definitive signal to finalize the order, redirect the user, and record the amount in your backend systems.
   You can use result.transactionId and related fields to confirm the order, update status, or redirect. The following nodes are returned in payload transaction data:

   Field	Description
   transactionId	The unique identifier required for backend reconciliation and future lookups.
   data	Contains financial specifics, including the amount, currency, and paymentMethod (e.g., card.brand, last4digit.token )
   customer	Returns the Customer ID if one was attached to the session.
   metadata	Any custom business data (e.g., orderId, source) passed during initialization.
   timestamp	The Unix timestamp of the transaction completion.

2. Exception Handling "onError": This event is triggered whenever a transaction fails to complete, whether due to user input errors, bank declines, or system interruptions. You can refer to the nodes for error payload here:

   Field	Description
   code	A machine-readable error string for logging.
   type	Categorizes the failure into actionable groups: VALIDATION_ERROR, PAYMENT_ERROR, NETWORK_ERROR / SYSTEM_ERROR , AUTHENTICATION_ERROR
   message	A human-readable description of the error.
   details	Optional granular data, such as which specific field caused a validation failure.

Operational Note: While the payload provides detailed error information for your support logs, ensure you display safe, user-friendly messages in your UI to avoid exposing sensitive system details.

Payment Redirect

This is a Session Completion "onComplete" event, which triggers after onSuccess , once the user has finished the interaction (e.g., clicking a "Done" button). Use this for triggering final analytics events to mark the user journey as fully closed. The following nodes are returned in payload transaction data:

Testing & Troubleshooting

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.

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 team for an expedited resolution.