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.
Parameters
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:
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

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.
Properties:
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.
Properties:
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.
Properties:
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:
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.
Type:
string
(static, readonly) Reason Codes – Complete API Response Errors
Possible errors that can occur when calling the complete API.
Properties:
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 Promise
Example
Basic Usage
up.hide() .then(() => console.log('Hidden')) .catch(err => console.error(err));
show(optionsopt) → {Promise.<UnifiedPayments~TransientToken}
Show button list.
Parameters
Name
Type
Attributes
Description
options
object
<optional>
Properties
Name
Type
Attributes
Description
containers
object
<optional>
CSS selectors to locate containers in which to place various UI elements. If not specified, these will operate in a sidebar.
Properties
Name
Type
Attributes
Description
paymentSelection
string
<optional>
For showing payment buttons.
paymentScreen
string
<optional>
For the main payment flows.
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" } } } } }