Migrating to Click to Pay Drop-In UI Version 1

Overview

The version 1 (v1) SDK simplifies your integration with fewer lines of code, a streamlined API, and enhancements such as auto-processing and a full event system. The core flow is the same in v1, and migrating to v1 involves only straightforward method renames.

This table summarizes the key method and behavior changes between v0 and v1:

This table provides a feature-by-feature comparison between the pre-v1 release and v1:

Initialization

Click to Pay Drop-In UI v1 initializes with a single asynchronous factory call and has no intermediate Accept object:

v0 Initialization

const accept = new Accept(sessionJWT);const up = accept.unifiedPayments();

v1 Initialization

const client = await VAS.UnifiedCheckout(sessionJWT);

Unified Checkout v1 validates the JWT signature and target origins during initialization.

Display the Payment UI

Unified Checkout v1 passes your UI payment selectors directly to mount().

v0 Display Payment UI with show()

// Sidebarconst token = await up.show({  containers: {    paymentSelection: '#buttons'  }});// Embeddedconst token = await up.show({  containers: {    paymentSelection: '#buttons',    paymentScreen: '#form'  }});

v1 Display Payment UI with mount()

// Sidebarconst result = await checkout.mount('#buttons');// Embeddedconst result = await checkout.mount({  paymentSelection: '#buttons',  paymentScreen: '#form'});

Events

Unified Checkout v0 does not include an event system; it relies on the promise resolution or rejection from show() and complete() instead. v1 includes a full event system at the client and integration levels.

v1 Full Event System

// Client-level — centralized error trackingclient.on('error', (err) => {  console.error(`[${err.source}] ${err.code}: ${err.message}`);});// Checkout-level — granular lifecycle eventscheckout.on('ready', (data) => {  console.log('Available methods:', data.availablePaymentMethods);});checkout.on('paymentMethodSelected', (data) => {  console.log('Selected:', data.type);});checkout.on('error', (err) => {  console.error('Checkout error:', err.code);});

Cleanup

Unified Checkout v1 distinguishes between unmount(), which is reversible, and destroy(), which is permanent. Before a cleanup, client.destroy() sends a destroyed event.

v0 Cleanup

up.hide();     // Hide UIup.dispose();  // Clean up resources

v1 Cleanup

checkout.unmount();   // Remove UI from page (can remount later)checkout.destroy();   // Permanent cleanupclient.destroy();     // Destroy client and clear all event listeners

Handle Errors

The UnifiedCheckoutError class and its reason codes are the same in v0 and v1:

v0 Error Handling

try {  const token = await up.show({    containers: {      paymentSelection: '#buttons'    }  });} catch (err) {  console.error(err.reason, err.message);}

v1 Error Handling

// Same error class, same propertiestry {  const result = await checkout.mount('#buttons');} catch (err) {  console.error(err.reason, err.message);}

Migrate Triggers

If your Unified Checkout v0 integration uses triggers, the migration is similar to checkout. In v1, client.createTrigger creates triggers, not UnifiedPayments as in v0. In v1, mount() replaces show().

v0 Triggers

const trigger = up.createTrigger('CLICKTOPAY', {  containers: { paymentScreen: '#screen' }});const token = await trigger.show();

v1 Triggers

const trigger = client.createTrigger('CLICKTOPAY');const result = await trigger.mount('#screen');

Reason Code Changes

Some reason codes were renamed in v1. This table shows the v0 reason code name and the corresponding name in the v1 client-side SDK:

Migration Checklist

This checklist lists the tasks required to migrate from Unified Checkout v0 to v1: