Update to `Unified Checkout` 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. Summary of Changes ------------------ | Aspect | v0 | v1 | |-------------------------|-----------------------------------------|----------------------------------------------------------------| | Initialization | `new Accept(session).unifiedPayments()` | `VAS.UnifiedCheckout(session)` | | Display the payment UI | `up.show(options)` | `checkout.mount(target)` | | Completing transactions | `up.complete(token)` | `checkout.complete(token)` or automatic using `autoProcessing` | | Events | None | Full event system on client and checkout | | Cleanup | `up.dispose()` | `checkout.destroy()` + `client.destroy()` | | Hide UI | `up.hide()` | `checkout.unmount()` | [ ] {#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` | | | `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) | | | Payment methods | API only | API or API and `Business Center` | | | 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) | | | 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 (link) | New UC SDK (link) | | | Payment Details API | `/up/v1/payment-details/`*{id}* | JTI used in place of transient token | | | Future enhancements | Manual opt-in is required. | Automatic. | Legacy versions receive critical updates only. | [Summary of v0 and v1 Changes] Initialization -------------- Initialization with `Unified Checkout` 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(); ``` 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()`. When `autoProcessing` is enabled, `mount()` returns the completed payment result rather than a transient token. 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' }); ``` Completing Transactions ----------------------- When `autoProcessing` is enabled in `Unified Checkout` v1, `mount()` returns the completed payment result and you do not need to send a separate complete() request. When `autoProcessing` is disabled in `Unified Checkout` v1, you must complete transactions manually. v0 Complete Transactions Manually ``` const token = await up.show({ containers: { paymentSelection: '#buttons' } }); const result = await up.complete(token); ``` v1 Complete Transactions Manually or Automatically ``` // Automatic (default when completeMandate is in session) const checkout = await client.createCheckout({ autoProcessing: true }); const result = await checkout.mount('#buttons'); // result is the completed transaction — no need to call complete() // Manual - similar to v0 const checkout = await client.createCheckout({ autoProcessing: false }); const token = await checkout.mount('#buttons'); const result = await checkout.complete(token); ``` 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'); ```