JavaScript API Reference {#uc-appendix-js-reference-v1_api_reference} ===================================================================== This reference provides details about the JavaScript API for creating the `Unified Checkout` v1 payment form. VAS.UnifiedCheckout(sessionJWT) {#uc_appendix_js_initialize} ============================================================ This is a factory function that initializes the SDK. It returns a frozen, immutable client interface. | Name | Type | Required? | Description | |--------------|----------|-----------|-------------------------------------------------------------------| | `sessionJWT` | `string` | Yes | Signed JSON Web Token (JWT) from the server-side session endpoint | [VAS.UnifiedCheckout(sessionJWT) Parameters] **Returns** : `Promise<UnifiedCheckoutInterface>` **Errors** : Returns `UnifiedCheckoutError` with reason `CAPTURE_CONTEXT_INVALID` if the JWT signature is invalid, or `UNUSED_TARGET_ORIGINS` if the current page origin is not in the JWT's `targetOrigins` list. **Example** : ``` const client = await VAS.UnifiedCheckout(sessionJWT); ``` UnifiedCheckoutInterface {#uc_appendix_js_interface} ==================================================== The client object returned by `VAS.UnifiedCheckout()`. All methods throw an `Error` if called after `destroy()`. client.createCheckout(options?) ------------------------------- | Name | Type | Required? | Description | |-----------|-------------------------|-----------|--------------------------------| | `options` | `CreateCheckoutOptions` | No | Configuration for the checkout | [client.createCheckout(options?) Parameters] | Property | Type | Default | Description | |------------------|-----------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `autoProcessing` | `boolean` | Inferred from capture context. | * `true`: `mount()` returns completed payment result. Defaults to `true` when completeMandate is included in the capture context. * `false`: `mount()` returns transient token. | [`CreateCheckoutOptions` Properties] **Returns** : `Promise<Checkout>` **Example** : ``` const checkout = await client.createCheckout({ autoProcessing: false }); ``` client.createTrigger(paymentType, options?) ------------------------------------------- | Name | Type | Required? | Description | |---------------|------------------------|-----------|-------------------------------------------------| | `paymentType` | `AllowedPaymentType` | Yes | Only `PANENTRY` and `CLICKTOPAY` are supported. | | `options` | `CreateTriggerOptions` | No | The configuration for the trigger. | [client.createTrigger(paymentType, options?) Parameters] | Property | Type | Default | Description | |------------------|-----------|-----------------------|-----------------------------------| | `autoProcessing` | `boolean` | Inferred from session | Same as checkout `autoProcessing` | [`CreateTriggerOptions` Properties] **Returns** : `Trigger` **Errors** : Returns `UnifiedCheckoutError` with reason `TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED` when the payment type cannot be used with a trigger. **Example** : ``` const trigger = client.createTrigger('PANENTRY'); ``` client.createButton(paymentType, options?) (Experimental) --------------------------------------------------------- Creates an individual payment method button. | Name | Type | Required? | Description | |---------------|-----------------------|-----------|-----------------------------------------------------------------------| | `paymentType` | `AllowedPaymentType` | Yes | Payment type for the button. For example, `GOOGLEPAY` and `APPLEPAY`. | | `options` | `CreateButtonOptions` | No | The configuration for the button. | [client.createButton(paymentType, options?) Parameters] | Property | Type | Default | Description | |------------------|-----------|-----------------------|-----------------------------------| | `autoProcessing` | `boolean` | Inferred from session | Same as checkout `autoProcessing` | [`CreateButtonOptions` Properties] **Returns** : `PaymentButton` **Example** : ``` const button = client.createButton('GOOGLEPAY'); ``` client.on(event, callback) -------------------------- Subscribes to a client-level event and returns an unsubscribe function. | Name | Type | Required? | Description | |------------|------------|-----------|------------------------------------------------------------------------| | `event` | `string` | Yes | Event name. Possible values: * `*` * `created` * `destroyed` * `error` | | `callback` | `function` | Yes | Handler function that receives event-specific payload. | [client.on(event, callback) Parameters] | Property | Type | Default | Description | |------------------|-----------|-----------------------|-----------------------------------| | `autoProcessing` | `boolean` | Inferred from session | Same as checkout `autoProcessing` | [`CreateButtonOptions` Properties] **Returns** : `Unsubscribe`: A function that removes the handler when called. **Errors** : Returns `Error` when `event` is not a valid event name with reason `TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED` when the payment type cannot be used with a trigger. **Example** : ``` const unsubscribe = client.on('error', (err) => { console.error(err.source, err.code, err.message); }); // Later unsubscribe(); ``` client.off(event, callback?) ---------------------------- Removes an event handler. This method is permissive --- calling it with an unknown event or callback does not throw. | Name | Type | Required? | Description | |------------|------------|-----------|------------------------------------------------------------------------------------------------| | `event` | `string` | Yes | Event name to unsubscribe from | | `callback` | `function` | No | Specific handler to remove. When this is not included, all handlers for the event are removed. | [client.off(event, callback?) Parameters] client.destroy() ---------------- Permanently destroys the client. Returns a `destroyed` event, clears all event listeners, and marks the instance as destroyed. You can call `destroy()` multiple times. client.isDestroyed() -------------------- Returns a value of `true` if client.destroy() is called. Checkout {#uc_appendix_js_checkout} =================================== This field is returned by `client.createCheckout()` and manages the full checkout UI lifecycle. checkout.mount(target) ---------------------- Subscribes to a client-level event and returns an unsubscribe function. | Name | Type | Required? | Description | |----------|----------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------| | `target` | `string` or `CheckoutContainers` | No | CSS selector string for sidebar mode, or an object with `paymentSelection` and `paymentScreen` for embedded mode. Omit for full sidebar | [checkout.mount(target) Parameters] | Property | Type | Default | Description | |--------------------|----------|---------|-------------------------------------------------------------------------------------------------| | `paymentSelection` | `string` | Yes | CSS selector for the button list container | | `paymentScreen` | `string` | No | CSS selector for the payment form container. If omitted, payment screens appear in sidebar mode | [`CheckoutContainers` Properties] **Returns** : `Promise<string>`: This is a transient token JWT when `autoProcessing: false` or completed payment result JWT when `autoProcessing: true`. **Errors** : Returns `UnifiedCheckoutError`. For information about how to handle mount error codes, see [Handle Errors](/docs/vas/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/uc-intro/uc-reference-test-cards/uc-handle-errors.md ""). **Example** : ``` // Sidebar const result = await checkout.mount('#buttons'); // Embedded const result = await checkout.mount({ paymentSelection: '#buttons', paymentScreen: '#form' }); ``` checkout.unmount() ------------------ Removes the payment UI from the page. The checkout is not destroyed --- you can call `mount()` again. checkout.complete(transientToken) --------------------------------- Manually completes the payment flow. This is only available when `autoProcessing` is set to `false`. | Name | Type | Required? | Description | |------------------|----------|-----------|--------------------------------------------------------| | `transientToken` | `string` | Yes | The transient token JWT that is returned by `mount()`. | [checkout.complete(transientToken) Parameters] | Property | Type | Default | Description | |--------------------|----------|---------|-------------------------------------------------------------------------------------------------| | `paymentSelection` | `string` | Yes | CSS selector for the button list container | | `paymentScreen` | `string` | No | CSS selector for the payment form container. If omitted, payment screens appear in sidebar mode | [`CheckoutContainers` Properties] **Returns** : `Promise<string>`: This is the completed payment result JWT. **Errors** : Returns `UnifiedCheckoutError`. For information about how to handle mount error codes, see [Handle Errors](/docs/vas/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/uc-intro/uc-reference-test-cards/uc-handle-errors.md ""). **Example** : ``` const token = await checkout.mount('#buttons'); const result = await checkout.complete(token); ``` checkout.isMounted() -------------------- Returns `true` when the checkout UI is mounted. checkout.isDestroyed() ---------------------- Returns `true` when `destroy()` is called. checkout.on(event, handler) --------------------------- Subscribes to a checkout-level event and returns an unsubscribe function. Valid events: * `mounted` * `ready` * `unready` * `unmounted` * `destroyed` * `paymentMethodSelected` * `paymentMethodCancelled` * `paymentMethodUpdate"` * `error` * `*` checkout.off(event, handler?) ----------------------------- Removes a checkout event handler. checkout.destroy() ------------------ Permanently destroys the checkout. This field removes the payment UI, cleans up iframes, and emits a `destroyed` event. Trigger {#uc_appendix_js_trigger} ================================= The trigger is returned by `client.createTrigger()` and programmatically launches a specific payment method. trigger.mount(target?) ---------------------- Launches the payment method UI. | Name | Type | Required? | Description | |----------|----------|-----------|--------------------------------------------------------| | `target` | `string` | No | CSS selector for embedded mode. Omit for sidebar mode. | [trigger.mount(target?) Parameters] **Returns** : `Promise<string>`: A transient token or completed payment result. **Example** : ``` const result = await trigger.mount('#payment-screen'); ``` trigger.unmount() ----------------- Hides the payment method UI. The trigger is not destroyed. trigger.complete(transientToken) -------------------------------- Manually completes the payment. Same interface as `checkout.complete()`. trigger.isMounted() ------------------- Returns a boolean value. trigger.isDestroyed() --------------------- Returns a boolean value. trigger.on(event, handler) -------------------------- Subscribes to trigger events. Same event names and payloads as checkout events. trigger.off(event, handler?) ---------------------------- Removes a trigger event handler. trigger.destroy() ----------------- Permanently destroys the trigger. PaymentButton {#uc_appendix_js_pay_button} ========================================== This is returned by `client.createButton()`. It renders an individual payment method button. button.mount(container) ----------------------- Mounts the button into a container. | Name | Type | Required? | Description | |-------------|---------------------------|-----------|-------------------------------------------------------------------------------------| | `container` | `string` or `HTMLElement` | Yes | CSS selector string or Document Object Model (DOM) element for the button container | [button.mount(container) Parameters] **Returns** : `Promise<string>`: A transient token or completed payment result. button.unmount() ---------------- Removes the button from the page. The button is not destroyed. button.isMounted() ------------------ Returns a boolean value if the button is mounted (`true`) or not mounted (`false`). button.isDestroyed() -------------------- Returns a boolean value if the button is destroyed (`true`) or not destroyed (`false`). button.on(event, callback) -------------------------- Subscribes to button events. Returns `void`. Use `button.off()` to remove handlers. > IMPORTANT The button event system is under development. Event names and payloads may change in future releases. button.off(event, callback?) ---------------------------- Removes a button event handler. button.destroy() ---------------- Permanently destroys the button. Idempotent. Events {#uc-appendix-js-events} =============================== `Unified Checkout` provides a type-safe event system for monitoring the payment lifecycle. Events are emitted at the client and integration levels. Subscribe to Events {#uc-appendix-js-events_uc-appendix-js-events-subscribe} ---------------------------------------------------------------------------- Use `on()` to subscribe to events. this returns an unsubscribe function: ``` const unsubscribe = checkout.on('ready', (data) => { console.log('Ready:', data.availablePaymentMethods); }); // Later, remove the handler unsubscribe(); ``` You can use `off()` to remove a specific handler: ``` function onReady(data) { /* ... */ } checkout.on('ready', onReady); checkout.off('ready', onReady); ```