On This Page

Update to `Click to Pay Drop-In UI` Version 1

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.

Summary of Changes


Aspect	v0	v1
Initialization	new Accept(session).unifiedPayments()	VAS.UnifiedCheckout(session)
Display the payment UI	up.show(options)	checkout.mount(target)
Events	None	Full event system on client and checkout
Cleanup	up.dispose()	checkout.destroy() + client.destroy()
Hide UI	up.hide()	checkout.unmount()
Target Origin	Multiple non-usable URLs can be included in the request.	If any origins are absent or mismatched, for example, they are not presented in `Click to Pay Drop-In UI`, the system prevents `Click to Pay Drop-In UI` from loading and displays a client-side error message.

Summary of v0 and v1 Changes
Feature	Pre V1 Support	V1 Support	Description
Status		`Business Center`
Capture context endpoint	/up/v1/capture-contexts	/up/v1/sessions
Capture context management	API only	API only or API and `Business Center`	`Business Center` configuration is at the merchant level.
`Unified Checkout` Look and Feel in `Business Center`			`Business Center` configuration is at the merchant level.
`Unified Checkout` Look and Feel Using the API			Configure the look and feel in a Sessions API request.
`Click to Pay` Configuration	API only	API or API and `Business Center`	`Business Center` configuration is at the merchant level.
Real-time preview in `Business Center`			`Business Center` configuration is at the merchant level.
Three-decimal currency support
SDK	Legacy Unified Payments SDK supported	New UC SDK
Payment Details API	/up/v1/payment-details/{id}	JTI used in place of transient token	JTI is located in the transient token
Future enhancements	Manual opt-in is required.	Automatic when the clientVersion is not included in the Sessions API request.	Legacy versions receive critical updates only.

Initialization

Initialization with Click to Pay Drop-In UI v1 is done in a single asynchronous factory call. There is no intermediate

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()

// Sidebar
const token = await up.show({
  containers: {
    paymentSelection: '#buttons'
  }
});

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

v1 Display Payment UI with

mount()

// Sidebar
const result = await checkout.mount('#buttons');

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

Events

Unified Checkout v0 does not include an event system, as the integration resolution or rejection from

show()

and

complete()

. v1 includes a full event system as the client and integration levels.

v1 Full Event System

// Client-level — centralized error tracking
client.on('error', (err) => {
  console.error(`[${err.source}] ${err.code}: ${err.message}`);
});

// Checkout-level — granular lifecycle events
checkout.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 UI
up.dispose();  // Clean up resources

v1 Cleanup

checkout.unmount();   // Remove UI from page (can remount later)
checkout.destroy();   // Permanent cleanup

client.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 properties
try {
  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, triggers are created from the

client.createTrigger

, not from

UnifiedPayments

as in v0. In v1,

show()

is renamed to

mount()

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');

Update to Click to Pay Drop-In UI Version 1

Summary of Changes

Initialization

Display the Payment UI

Events

Cleanup

Handle Errors

Migrate Triggers

Update to `Click to Pay Drop-In UI` Version 1