JavaScript 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= "https://apitest.cybersource.com/up/v1/assets/0.19.0/SecureAcceptance.js" script>
    // note: script location should be sourced from capture context response
    // "clientLibrary": "https://apitest.cybersource.com/up/v1/assets/0.19.0/SecureAcceptance.js",
    //"clientLibraryIntegrity": "sha256-ZYCOknqXyn4Zwsr8V0hNNr6ZR+Ya8IlsdtZeNHOl2XU="		

 	
<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

var captureContext = document.getElementById('captureContext').value;
  
Accept(captureContext)
	.then(accept => accept.unifiedPayments())

Embedded Payment Entry

var captureContext = document.getElementById('captureContext').value;
  
Accept(captureContext)
	.then(accept => accept.unifiedPayments(false))

Error Handling

var 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.`;
            });

JavaScript Reference

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
UNIFIED_PAYMENTS_ALREADY_SHOWN	string	Occurs when you attempt to show a Unified Payments instance multiple times.
SHOW_LOAD_CONTAINER_SELECTOR	string	Occurs when a DOM element cannot be located using the supplied CSS Selector string.
SHOW_LOAD_INVALID_CONTAINER	string	Occurs when an invalid container parameter is supplied.
SHOW_LOAD_ERROR	string	Occurs when there is an issue loading the payment iframe.
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.
SHOW_PAYMENT_TIMEOUT	string	Occurs when an error is encountered during the handling of a payment option.
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
UNIFIEDPAYMENTS_VALIDATION_PARAMS	string	Occurs when there's an issue with params supplied to UnifiedPayments constructor.
UNIFIEDPAYMENT_PAYMENT_PARAMETERS	string	Occurs when no valid payment parameters exist while initializing button.
CREATE_TOKEN_TIMEOUT	string	Occurs when the createToken call was unable to proceed.
CREATE_TOKEN_XHR_ERROR	string	Occurs when a network error is encountered while attempting to create a token.

(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

JavaScript Reference

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

Properties

Name

Type

Attributes

Description

containers

object

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

var showArgs = {
            containers: {
                paymentSelection: #buttonPaymentListContainer'
            }
        };

up.show(showArgs).then(transientToken => console.log(transientToken));

All Screens Embedded in Containers

var 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

var transientToken = 'hhhhhhhhhh.pppppppppp.sssssssssss';

var segments = transientToken.split('.');
var urlBase64Decode = (s) => atob(s.replace(/_/g, '/').replace(/-/g, '+'));

var header = JSON.parse(urlBase64Decode(segments[0]));
var payload = JSON.parse(urlBase64Decode(segments[1]));
var 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"
        }
      }
    }
  }
}

JavaScript Reference