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. Class: Accept {#ctp-appendix-js-class-accept} ============================================= Accept ------ **Returns** Type: Promise.\<Accept\> **Example** *Basic Setup* ``` <script src="[INSERT clientLibrary VALUE HERE]" integrity=”[INSERT clientLibraryIntegrity VALUE HERE]” crossorigin=”anonymous”></script> //Note: Script location and integrity value should be sourced from the capture context response clientLibrary and clientLibraryIntegrity values. <script> Accept('header.payload.signature').then(function(accept) { // use accept object }); </script> ``` Methods ------- **dispose()**` → {void}` Dispose of this Accept instance. **Returns** Type: void **unifiedPayments(sidebar)**` → `**{Promise.<UnifiedPayments>}** Create a Unified Payments integration. | Name | Type | Attributes | Description | |:--------|:--------|:-------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | sidebar | Boolean | \<optional\> | Set the option to `false` to enable embedded functionality of Unified Checkout. This will configure Unified Checkout to place the Payment Entry form inline. If this value is not set, the default is `true` and Unified Checkout will open the Payment Entry form in the sidebar configuration. | [Parameters] **Throws:** AcceptError **Returns:** Type: Promise.\<UnifiedPayments\> **Examples** *Minimal Setup - sidebar* ``` const captureContext = document.getElementById('captureContext').value; Accept(captureContext) .then(accept => accept.unifiedPayments()) ``` *Embedded Payment Entry* ``` const captureContext = document.getElementById('captureContext').value; Accept(captureContext) .then(accept => accept.unifiedPayments(false)) ``` *Error Handling* ``` const captureContext = document.getElementById('captureContext').value; Accept(captureContext) .then(accept => accept.unifiedPayments()) .then(up => up.show(showArgs)) .then(tt => { document.getElementById('transientToken').value = tt; document.getElementById("authForm").submit(); }) .catch(error => { console.error(error); document.getElementById('logo').text = `Checkout error: ${JSON.stringify(error)}. Try again.`; }); ``` Class: AcceptError {#ctp-appendix-js-class-accept-error} ======================================================== AcceptError ----------- This class defines how errors are returned by the Unified Checkout JavaScript. Members ------- `(static, readonly) Reason Codes - Accept object creation` Possible errors that can occur during the creation of an Accept object. | Name | Type | Description | |:------------------------|:-------|:-----------------------------------------------------------------------------| | CAPTURE_CONTEXT_INVALID | string | Occurs when you pass an invalid JWT. | | CAPTURE_CONTEXT_EXPIRED | string | Occurs when the JWT you pass has expired. | | SDK_XHR_ERROR | string | Occurs when a network error is encountered while attempting to load the SDK. | [Properties:] `(static, readonly) Reason Codes - Show Errors` Possible errors that can occur during the rendering of payment selection list. | Name | Type | Description | |:-------------------------------------|:-------|:------------------------------------------------------------------------------------| | CHECKOUT_ERROR | string | Occurs when checkout failed to load. | | CLICK_TO_PAY_SDK_LOAD_ERROR | string | Occurs when the `Click to Pay` SDK fails to load. | | ENCRYPT_CARD_FOR_SRC_ENROLMENT_ERROR | string | Occurs when the card encryption for SRC enrollment fails to load. | | LAUNCH_SRC_CHECKOUT_ERROR | string | Occurs when the SRC checkout fails to load. | | SHOW_LOAD_CONTAINER_SELECTOR | string | Occurs when a DOM element cannot be located using the supplied CSS Selector string. | | SHOW_LOAD_ERROR | string | Occurs when there is an issue loading the payment iframe. | | SHOW_LOAD_INVALID_CONTAINER | string | Occurs when an invalid container parameter is supplied. | | SHOW_LOAD_SIDEBAR_OPTIONS | string | Occurs when an invalid container parameter is supplied when sidebar is selected. | | SHOW_PAYMENT_TIMEOUT | string | Occurs when an error is encountered during the handling of a payment option. | | SHOW_PAYMENT_UNAVAILABLE | string | Occurs when no payment types can be presented to the customer. | | SHOW_TOKEN_TIMEOUT | string | Occurs when the createToken call is unable to proceed. | | SHOW_TOKEN_XHR_ERROR | string | Occurs when a network error is encountered while attempting to create a token. | | UNIFIED_PAYMENTS_ALREADY_SHOWN | string | Occurs when you attempt to show a Unified Payments instance multiple times. | | UNKNOWN_ERROR | string | Occurs when an unknown error has occurred. | [Properties:] `(static, readonly) Reason Codes - Unified Payments Errors` Possible errors that can occur during the creation of a Unified Payments object. | Name | Type | Description | |:------------------------------------|:-------|:------------------------------------------------------------------------------------------| | CREATE_TOKEN_TIMEOUT | string | Occurs when the createToken call times out. | | CREATE_TOKEN_XHR_ERROR | string | Occurs when a network error is encountered while attempting to create a token. | | UNIFIED_PAYMENTS_PAYMENT_PARAMETERS | string | Occurs when no valid payment parameters exist while initializing button. | | UNIFIED_PAYMENTS_VALIDATION_PARAMS | string | Occurs when there's an issue with the parameters supplied to UnifiedPayments constructor. | [Properties:] `(nullable) correlationId :string` The correlationId of any underlying API call that resulted in this error. **Type:** string `(nullable) details :array` Additional error-specific information. **Type:** array `(nullable) informationLink :string` A URL link to online documentation for this error. **Type:** string `message :string` A human-readable explanation of the error that has occurred. **Type:** string `reason :string` A reason corresponding to the specific error that has occurred. Class: UnifiedPayments {#ctp-appendix-js-class-unified-payments} ================================================================ UnifiedPayments --------------- An instance of this class is returned upon the creation of a Unified Payments integration using accept.unifiedPayments(). Using this object you can add the payment options list to your checkout. Methods {#ctp-appendix-js-class-unified-payments_section_n1t_k5v_ncc} --------------------------------------------------------------------- `hide() → {Promise}` Hide button list. **Returns:** Type Promise **Example** Basic Usage ``` up.hide() .then(() => console.log('Hidden')) .catch(err => console.error(err)); ``` `show(optionsopt) → {Promise.<UnifiedPayments~TransientToken}` Show button list. | Name | Type | Attributes | Description | |:-----------------|:-------|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------| | options | object | \<optional\> | | | containers | object | \<optional\> | CSS selectors to locate containers in which to place various UI elements. If not specified, these will operate in a sidebar. | | paymentSelection | string | \<optional\> | For showing payment buttons. | | paymentScreen | string | \<optional\> | For the main payment flows. | [Parameters] **Returns:** Type Promise **Examples** Basic Usage With Full Sidebar Experience ``` const showArgs = { containers: { paymentSelection: #buttonPaymentListContainer' } }; up.show(showArgs).then(transientToken => console.log(transientToken)); ``` All Screens Embedded in Containers ``` const showArgs = { containers: { paymentSelection: '#buttonPaymentListContainer', paymentScreen: '#embeddedPaymentContainer' } }; up.show(showArgs).then(transientToken => console.log(transientToken)); ``` Type Definitions ---------------- **TransientToken** The response to a successful customer interaction with Unified Checkout is a transient token. The transient token is a reference to the payment data collected on your behalf. Tokens allow secure card payments to occur without risk of exposure to sensitive payment information. The transient token is a short-term token that lasts 15 minutes. This reduces your PCI burden and responsibility and ensures that sensitive information is not exposed to your backend systems. It is in a JSON Web Token format. The payload of the transient token may contain useful metadata in relation to the stored sensitive info. However , all of this info is safe to use and store on your systems. The transient token can be used to complete a payment or other services, after which the transient data will be evicted from the token store. **Type:** string **Examples** How to Split the Transient Token ``` const transientToken = 'hhhhhhhhhh.pppppppppp.sssssssssss'; const segments = transientToken.split('.'); const urlBase64Decode = (s) => atob(s.replace(/_/g, '/').replace(/-/g, '+')); const header = JSON.parse(urlBase64Decode(segments[0])); const payload = JSON.parse(urlBase64Decode(segments[1])); const signature = segments[2]; ``` Decoded Body ``` { "iss" : "Flex/00", "exp" : 1706910242, "type" : "gda-0.9.0", "iat" : 1706909347, "jti" : "1D1I2O2CSTMW3UIXOKEQFI4OQX1L7CMSKDE3LJ8B5DVZ6WBJGKLQ65BD6222D426", "content" : { "orderInformation" : { "billTo" : { // Empty fields present within this node indicate which fields were captured by // the application without exposing you to personally identifiable information // directly. }, "amountDetails" : { // Empty fields present within this node indicate which fields were captured by // the application without exposing you to personally identifiable information // directly. }, "shipTo" : { // Empty fields present within this node indicate which fields were captured by // the application without exposing you to personally identifiable information // directly. } }, "paymentInformation" : { "card" : { "expirationYear" : { "value" : "2028" }, "number" : { "maskedValue" : "XXXXXXXXXXXX1111", "bin" : "411111" }, "securityCode" : { }, "expirationMonth" : { "value" : "06" }, "type" : { "value" : "001" } } } } } ``` 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/vas/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/ctp-intro/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); ```