On This Page
JavaScript API Reference
This reference provides details about the JavaScript API for creating the
Unified Checkout
payment form.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. |
Throws:
AcceptErrorReturns:
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
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. |
(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. |
(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 params supplied to
UnifiedPayments constructor. |
(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:
stringmessage :string
A human-readable explanation of the error that has occurred.
Type:
stringreason :string
A reason corresponding to the specific error that has occurred.
Type:
string(static, readonly) Reason Codes – Complete API Response
Errors
Possible errors that can occur when calling the complete
API.
Name | Type | Description |
|---|---|---|
COMPLETE_AUTHENTICATION_CANCELED | string | Occurs when the user cancels the authentication process during
Cardinal step-up. |
COMPLETE_AUTHENTICATION_FAILED | string | Occurs when the complete authentication process fails during Cardinal
step-up. |
COMPLETE_ERROR | string | Occurs when an error occurs while attempting to process a payment
using the complete API. |
COMPLETE_IN_PROGRESS | string | Occurs when complete has already been invoked but has not yet
finished processing. |
COMPLETE_NOT_ALLOWED | string | Occurs if complete is not allowed for this transaction. |
COMPLETE_TRANSACTION_CANCELLED | string | Occurs when consumer cancelled the transaction. |
COMPLETE_TRANSACTION_FAILED | string | Occurs when consumer transaction fails. |
COMPLETE_VALIDATION_ERROR | string | Occurs when there is a validation issue relating to the parameters
you have supplied in your complete call. |
Class: UnifiedPayments
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
hide() → {Promise}
Hide button list.
Returns:
Type PromiseExample
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> |
|
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:
stringExamples
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" } } } } }