JavaScript API Reference {#ctp-appendix-js-reference_api_reference} =================================================================== This reference provides details about the JavaScript API for creating the `Click to Pay Drop-In UI` payment form. VAS.UnifiedCheckout(sessionJWT) {#ctp_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 {#ctp-appendix-js-interface} ===================================================== The client object returned by `VAS.UnifiedCheckout()`. All methods throw an `Error` if called after `destroy()`. client.createCheckout(options?) {#ctp-appendix-js-interface_section_zcx_g1s_hjc} -------------------------------------------------------------------------------- | 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. | `false`: `mount()` returns transient token. | [`CreateCheckoutOptions` Properties] **Returns** : `Promise<Checkout>` **Example** : ``` const checkout = await client.createCheckout({ autoProcessing: false }); ``` {#ctp-appendix-js-interface_codeblock_edx_g1s_hjc} {#ctp-appendix-js-interface_dl_ddx_g1s_hjc} client.createTrigger(paymentType, options?) {#ctp-appendix-js-interface_section_fdx_g1s_hjc} -------------------------------------------------------------------------------------------- | Name | Type | Required? | Description | |---------------|------------------------|-----------|-------------------------------------------------------| | `paymentType` | `AllowedPaymentType` | Yes | Support trigger of the UI from client- driven button. | | `options` | `CreateTriggerOptions` | No | The configuration for the trigger. | [client.createTrigger(paymentType, options?) Parameters] **Returns** : `Trigger` **Example** : ``` const trigger = client.createTrigger(CLICKTOPAY); ``` {#ctp-appendix-js-interface_codeblock_jdx_g1s_hjc} {#ctp-appendix-js-interface_dl_idx_g1s_hjc} client.on(event, callback) {#ctp-appendix-js-interface_section_qdx_g1s_hjc} --------------------------------------------------------------------------- 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` {#ctp-appendix-js-interface_ul_sdx_g1s_hjc} | | `callback` | `function` | Yes | Handler function that receives event-specific payload. | [client.on(event, callback) Parameters] **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(); ``` {#ctp-appendix-js-interface_codeblock_vdx_g1s_hjc} {#ctp-appendix-js-interface_dl_udx_g1s_hjc} client.off(event, callback?) {#ctp-appendix-js-interface_section_wdx_g1s_hjc} ----------------------------------------------------------------------------- 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() {#ctp-appendix-js-interface_section_ydx_g1s_hjc} ----------------------------------------------------------------- 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() {#ctp-appendix-js-interface_section_zdx_g1s_hjc} --------------------------------------------------------------------- Returns a value of `true` if client.destroy() is called. Checkout {#ctp-appendix-js-checkout} ==================================== This field is returned by `client.createCheckout()` and manages the full checkout UI lifecycle. checkout.mount(target) {#ctp-appendix-js-checkout_section_c32_hbs_hjc} ---------------------------------------------------------------------- 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`. **Errors** : Returns `UnifiedCheckoutError`. For information about how to handle mount error codes, see [Handle Errors](/docs/barclays/en-us/click-to-pay/developer/all/rest/click-to-pay/ctp-testing-intro/ctp-handle-errors.md ""). **Example** : ``` // Sidebar const result = await checkout.mount('#buttons'); // Embedded const result = await checkout.mount({ paymentSelection: '#buttons', paymentScreen: '#form' }); ``` {#ctp-appendix-js-checkout_codeblock_g32_hbs_hjc} {#ctp-appendix-js-checkout_dl_f32_hbs_hjc} checkout.unmount() {#ctp-appendix-js-checkout_section_h32_hbs_hjc} ------------------------------------------------------------------ Removes the payment UI from the page. The checkout is not destroyed --- you can call `mount()` again. checkout.isMounted() {#ctp-appendix-js-checkout_section_n32_hbs_hjc} -------------------------------------------------------------------- Returns `true` when the checkout UI is mounted. checkout.isDestroyed() {#ctp-appendix-js-checkout_section_o32_hbs_hjc} ---------------------------------------------------------------------- Returns `true` when `destroy()` is called. checkout.on(event, handler) {#ctp-appendix-js-checkout_section_p32_hbs_hjc} --------------------------------------------------------------------------- Subscribes to a checkout-level event and returns an unsubscribe function. Valid events: * `mounted` * `ready` * `unready` * `unmounted` * `destroyed` * `paymentMethodSelected` * `paymentMethodCancelled` * `paymentMethodUpdate"` * `error` * `*` {#ctp-appendix-js-checkout_ul_q32_hbs_hjc} checkout.off(event, handler?) {#ctp-appendix-js-checkout_section_r32_hbs_hjc} ----------------------------------------------------------------------------- Removes a checkout event handler. checkout.destroy() {#ctp-appendix-js-checkout_section_s32_hbs_hjc} ------------------------------------------------------------------ Permanently destroys the checkout. This field removes the payment UI, cleans up iframes, and emits a `destroyed` event. Trigger {#ctp-appendix-js-trigger} ================================== The trigger is returned by `client.createTrigger()` and programmatically launches a specific payment method. trigger.mount(target?) {#ctp-appendix-js-trigger_section_nmc_sbs_hjc} --------------------------------------------------------------------- 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. {#ctp-appendix-js-trigger_dl_pmc_sbs_hjc} **Example** : ``` const result = await trigger.mount('#payment-screen'); ``` {#ctp-appendix-js-trigger_codeblock_smc_sbs_hjc} {#ctp-appendix-js-trigger_dl_rmc_sbs_hjc} trigger.unmount() {#ctp-appendix-js-trigger_section_tmc_sbs_hjc} ---------------------------------------------------------------- Hides the payment method UI. The trigger is not destroyed. trigger.isMounted() {#ctp-appendix-js-trigger_section_vmc_sbs_hjc} ------------------------------------------------------------------ Returns a boolean value. trigger.isDestroyed() {#ctp-appendix-js-trigger_section_wmc_sbs_hjc} -------------------------------------------------------------------- Returns a boolean value. trigger.on(event, handler) {#ctp-appendix-js-trigger_section_xmc_sbs_hjc} ------------------------------------------------------------------------- Subscribes to trigger events. Same event names and payloads as checkout events. trigger.off(event, handler?) {#ctp-appendix-js-trigger_section_ymc_sbs_hjc} --------------------------------------------------------------------------- Removes a trigger event handler. trigger.destroy() {#ctp-appendix-js-trigger_section_zmc_sbs_hjc} ---------------------------------------------------------------- Permanently destroys the trigger. Events {#ctp_appendix_js_events} ================================ `Click to Pay` provides a type-safe event system for monitoring the payment lifecycle. Events are emitted at the client and integration levels. Subscribe to Events {#ctp_appendix_js_events_section_r13_l2n_djc} ----------------------------------------------------------------- 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); ```