On This Page
JavaScript API Reference
This reference provides details about the JavaScript API for creating the
Click to Pay Drop-In UI
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 the parameters 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.
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> | |
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. |
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" } } } } }
VAS.UnifiedCheckout(sessionJWT)
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 |
- Returns
- Promise<UnifiedCheckoutInterface>
- Errors
- ReturnsUnifiedCheckoutErrorwith reasonCAPTURE_CONTEXT_INVALIDif the JWT signature is invalid, orUNUSED_TARGET_ORIGINSif the current page origin is not in the JWT’stargetOriginslist.
- Example
- const client = await VAS.UnifiedCheckout(sessionJWT);
UnifiedCheckoutInterface
The client object returned by
VAS.UnifiedCheckout()
. All methods
throw an Error
if called after destroy()
.client.createCheckout(options?)
client.createCheckout(options?)
Name | Type | Required? | Description |
|---|---|---|---|
options | CreateCheckoutOptions | No | Configuration for the checkout |
Property | Type | Default | Description |
|---|---|---|---|
autoProcessing | boolean | Inferred from capture context. | false : mount() returns
transient token. |
- Returns
- Promise<Checkout>
- Example
- const checkout = await client.createCheckout({ autoProcessing: false });
client.createTrigger(paymentType, options?)
client.createTrigger(paymentType, options?)
Name | Type | Required? | Description |
|---|---|---|---|
paymentType | AllowedPaymentType | Yes | Support trigger of the UI from client- driven button. |
options | CreateTriggerOptions | No | The configuration for the trigger. |
- Returns
- Trigger
- Example
- const trigger = client.createTrigger(CLICKTOPAY);
client.on(event, callback)
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:
|
callback | function | Yes | Handler function that receives event-specific payload. |
- Returns
- Unsubscribe: A function that removes the handler when called.
- Errors
- ReturnsErrorwheneventis not a valid event name with reasonTRIGGER_PAYMENT_TYPE_NOT_SUPPORTEDwhen 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?)
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.destroy()
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()
client.isDestroyed()
Returns a value of
true
if client.destroy()
is
called.Checkout
This field is returned by
client.createCheckout()
and manages the
full checkout UI lifecycle.checkout.mount(target)
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 |
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 |
- Returns
- Promise<string>: This is a transient token JWT whenautoProcessing: false.
- Errors
- ReturnsUnifiedCheckoutError. For information about how to handle mount error codes, see Handle Errors.
- Example
- // Sidebar const result = await checkout.mount('#buttons'); // Embedded const result = await checkout.mount({ paymentSelection: '#buttons', paymentScreen: '#form' });
checkout.unmount()
checkout.unmount()
Removes the payment UI from the page. The checkout is not destroyed — you can call
mount()
again.checkout.isMounted()
checkout.isMounted()
Returns
true
when the checkout UI is mounted. checkout.isDestroyed()
checkout.isDestroyed()
Returns
true
when destroy()
is called.checkout.on(event, handler)
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?)
checkout.off(event, handler?)
Removes a checkout event handler.
checkout.destroy()
checkout.destroy()
Permanently destroys the checkout. This field removes the payment UI, cleans up
iframes, and emits a
destroyed
event.Trigger
The trigger is returned by
client.createTrigger()
and
programmatically launches a specific payment method.trigger.mount(target?)
trigger.mount(target?)
Launches the payment method UI.
Name | Type | Required? | Description |
|---|---|---|---|
target | string | No | CSS selector for embedded mode. Omit for sidebar mode. |
- Returns
- Promise<string>: A transient token or completed payment result.
- Example
- const result = await trigger.mount('#payment-screen');
trigger.unmount()
trigger.unmount()
Hides the payment method UI. The trigger is not destroyed.
trigger.isMounted()
trigger.isMounted()
Returns a boolean value.
trigger.isDestroyed()
trigger.isDestroyed()
Returns a boolean value.
trigger.on(event, handler)
trigger.on(event, handler)
Subscribes to trigger events. Same event names and payloads as checkout events.
trigger.off(event, handler?)
trigger.off(event, handler?)
Removes a trigger event handler.
trigger.destroy()
trigger.destroy()
Permanently destroys the trigger.
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
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);