Update to `Click to Pay Drop-In UI` Version 1 {#uc_v1_migration_intro} ====================================================================== 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. | 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 Changes] {#uc_v1_migration_intro_rest-uc-cc-prod-code} | Feature | Pre V1 Support | V1 Support | Description | |:------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------| | Status | ![](/content/dam/documentation/cybs/en-us/common/images/circlecheck-filled.svg/jcr:content/renditions/original) | `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` | ![](/content/dam/documentation/cybs/en-us/common/images/circlex-filled.svg/jcr:content/renditions/original) | ![](/content/dam/documentation/cybs/en-us/common/images/circlecheck-filled.svg/jcr:content/renditions/original) | `Business Center` configuration is at the merchant level. | | `Unified Checkout` Look and Feel Using the API | ![](/content/dam/documentation/cybs/en-us/common/images/circlex-filled.svg/jcr:content/renditions/original) | ![](/content/dam/documentation/cybs/en-us/common/images/circlecheck-filled.svg/jcr:content/renditions/original) | 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` | ![](/content/dam/documentation/cybs/en-us/common/images/circlex-filled.svg/jcr:content/renditions/original) | ![](/content/dam/documentation/cybs/en-us/common/images/circlecheck-filled.svg/jcr:content/renditions/original) | `Business Center` configuration is at the merchant level. | | Three-decimal currency support | ![](/content/dam/documentation/cybs/en-us/common/images/circlex-filled.svg/jcr:content/renditions/original) | ![](/content/dam/documentation/cybs/en-us/common/images/circlecheck-filled.svg/jcr:content/renditions/original) | | | 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. | [Summary of v0 and v1 Changes] Initialization {#uc_v1_migration_intro_section_xzp_pbt_hjc} ----------------------------------------------------------- Initialization with `Click to Pay Drop-In UI` v1 is done in a single asynchronous factory call. There is no intermediate `Accept` object: v0 Initialization ``` const accept = new Accept(sessionJWT); const up = accept.unifiedPayments(); ``` {#uc_v1_migration_intro_codeblock_zzp_pbt_hjc} v1 Initialization ``` const client = await VAS.UnifiedCheckout(sessionJWT); ``` {#uc_v1_migration_intro_codeblock_b1q_pbt_hjc} `Unified Checkout` v1 validates the JWT signature and target origins during initialization. Display the Payment UI {#uc_v1_migration_intro_section_d1q_pbt_hjc} ------------------------------------------------------------------- `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' } }); ``` {#uc_v1_migration_intro_codeblock_f1q_pbt_hjc} v1 Display Payment UI with `mount()` ``` // Sidebar const result = await checkout.mount('#buttons'); // Embedded const result = await checkout.mount({ paymentSelection: '#buttons', paymentScreen: '#form' }); ``` {#uc_v1_migration_intro_codeblock_h1q_pbt_hjc} Events {#uc_v1_migration_intro_section_n1q_pbt_hjc} --------------------------------------------------- `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); }); ``` {#uc_v1_migration_intro_codeblock_p1q_pbt_hjc} Cleanup {#uc_v1_migration_intro_section_q1q_pbt_hjc} ---------------------------------------------------- `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 ``` {#uc_v1_migration_intro_codeblock_s1q_pbt_hjc} v1 Cleanup ``` checkout.unmount(); // Remove UI from page (can remount later) checkout.destroy(); // Permanent cleanup client.destroy(); // Destroy client and clear all event listeners ``` {#uc_v1_migration_intro_codeblock_u1q_pbt_hjc} Handle Errors {#uc_v1_migration_intro_section_v1q_pbt_hjc} ---------------------------------------------------------- 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); } ``` {#uc_v1_migration_intro_codeblock_x1q_pbt_hjc} v1 Error Handling ``` // Same error class, same properties try { const result = await checkout.mount('#buttons'); } catch (err) { console.error(err.reason, err.message); } ``` {#uc_v1_migration_intro_codeblock_z1q_pbt_hjc} Migrate Triggers {#uc_v1_migration_intro_section_abq_pbt_hjc} ------------------------------------------------------------- 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(); ``` {#uc_v1_migration_intro_codeblock_cbq_pbt_hjc} v1 Triggers ``` const trigger = client.createTrigger('CLICKTOPAY'); const result = await trigger.mount('#screen'); ``` {#uc_v1_migration_intro_codeblock_ebq_pbt_hjc}