`Unified Checkout` Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose: This document is written for merchants who want to enable Unified Checkout so that they can accept payments on their e-commerce page. Merchants use the Unified Checkout JavaScript SDK to place a digital button widget on their e-commerce site, allowing Visa Acceptance Solutions to capture payment data on their behalf.
Conventions: This statement is used in this document:

IMPORTANT

An Important
statement contains information essential to successfully completing a task or learning a concept.

Recent Revisions to This Document

25.08.02

Added more information about JSON Web Tokens. See JSON Web Tokens.

25.08.01

Client-Side Setup: Added information for creating a trigger. See JavaScript Example: Client-Defined Trigger for Click to Pay or PAN Entry.
Capture Context: Added PayPak as a payment method. See Capture Context API.; Added information for client version 0.28. See Client Version History.

25.05.01

Capture Context: Added information for the complete mandate. See Capture Context API.; Added information on the available features and the fields specific to each feature to the Capture Context API. See Capture Context API.; Added Paze to the list of allowed payment types. See Capture Context API.; Added capture context validation. See Validating the Capture Context.
Unified Checkout Appendix: Added a client version history and the features included in each version. See Client Version History.; Added Unified Checkout payment examples. See Unified Checkout Examples.; Updated the list of supported languages. See Supported Locales.
Client-Side Set Up: Updated the examples for loading the JavaScript library:
JavaScript Example: Initializing the SDK
JavaScript Example: Displaying the Button List
JavaScript Example: Processing a Payment.
Click to Pay: Updated the list of supported countries to include Bulgaria, Greece, Japan, Romania, Slovenia, Thailand, and Vietnam. See Supported Countries for Digital Payments.

25.03.02

Added information about choosing your preferred card number prefix length and supported scenarios. See the Include Card Prefix sections of these topics:

Capture Context

Capture Context API

25.03.01

Replaced check
digital payment method with eCheck
digital payment method throughout Capture Context.

Corrected the example code in REST Example: Requesting the Capture Context.

Added information on using customer authentication with

Click to Pay

for Visa transactions. See Customer Authentication.

25.02.01

Added optional setup parameters to control the types of credentials that Google Pay on Unified Checkout receives from Google. See Managing Google Pay Authentication Types.

Added test card numbers. See Test Payment Details.

25.01.01

Updated the Important note about China UnionPay cards that do not have CVNs. See Capture Context.

Added steps for enrolling in Apple Pay. See Preparing a Device for Testing Apple Pay on Unified Checkout.

24.12.01

Capture Context: Updated the capture context request sections to include the most recent client version and allowed payment types. See Capture Context and Capture Context API.
Dual-Branded and Co-Badged Cards: Added information about dual-branded cards. See Dual-Branded Cards.

24.10.01

Added information about China UnionPay cards that do not have a card verification number (CVN) and expiration date. See the Important note in Capture Context.

24.09.01

Added a note about transient token expiration. See Authorizations with a Transient Token.

Added the Unified Checkout JavaScript Reference. See JavaScript API Reference.

Introduction to `Unified Checkout`

Unified Checkout provides a single interface with which you can accept numerous types of digital payments. Unified Checkout calls other follow-on services such as Payments, Decision Manager, and Payer Authentication.

Unified Checkout consists of a server-side component and a client-side JavaScript library.

The server-side component authenticates your merchant identity and instructs the system to act within your payment environment. The response contains limited-use public keys. The keys are for end-to-end encryption and contain merchant-specific payment information that drives the interaction of the application. The client-side JavaScript library dynamically and securely places digital payment options onto your e-commerce page.

The provided JavaScript library enables you to securely accept many payment options within your e-commerce environment. Unified Checkout can be embedded seamlessly into your existing webpage, simplifying payment acceptance.

When a customer selects a payment method from the button widget, Unified Checkout handles all of the interactions with the digital payment that was chosen. Unified Checkout is also able to orchestrate requests for to follow-on services such as Payments, Decision Manager, and Payer Authentication before it provides a response to your e-commerce system.

The figure below shows Unified Checkout with customer checkout payment options.

For examples of different payment method UIs through Unified Checkout, see Unified Checkout UI.

IMPORTANT

Each request that you send to Visa Acceptance Solutions requires header information. For information about constructing the headers for your request, see the Getting Started with REST Developer Guide
.

`Unified Checkout` Flow

To integrate Unified Checkout into your platform, you must follow several integration steps. This section gives a high-level overview of how to integrate and launch Unified Checkout on your webpage and process a transaction. You can find the detailed specifications of the APIs later in this document.

The integration flow consists of four events:

You send a server-to-server API request for a capture context. This request is fully authenticated and returns a JSON Web Token (JWT) that is necessary in order to invoke the frontend JavaScript library. For information on setting up the server side, see Server-Side Set Up.

You invoke the Unified Checkout JavaScript library using the JWT response from the capture context request. For information on setting up the client side, see Client-Side Set Up.

You process the payment through the Unified Checkout complete mandate feature and interpret the response of the transaction flow that is displayed on your browser.

IMPORTANT

If you do not use the complete mandate for Unified Checkout, you must request follow-on services using a transient token to process the payment.

Optional:
Capture the full payment response through webhook notifications.

Information that is captured by Unified Checkout, including the billing and shipping address, can be retrieved using the payment details API.

The figure below shows the Unified Checkout payment flow.

Diagram that shows the sequence and flow of a Unified Checkout payment. — `Unified Checkout` Payment Flow

For more information on the specific APIs referenced, see these topics:

Capture Context API

Payment Details API

Enabling `Unified Checkout` in the `Business Center`

To begin using Unified Checkout, you must first ensure that your merchant ID (MID) is configured to use the service and that any payment methods you intend to use are properly set up.

Log in to the Business Center:

Test URL:

https://businesscentertest.visaacceptance.com/ebc2

Production URL:

https://businesscenter.visaacceptance.com/ebc2

If you are unable to access this page, contact your sales representative.

In the Business Center, go to the left navigation panel and choose

Payment Configuration

>

Unified Checkout

.

You can configure various payment methods such as Apple Pay, Click to Pay, and Google Pay. Click

Set up

and follow the instructions for your selected payment methods. When payment methods are enabled, they appear on the payment configuration page.

IMPORTANT

You must configure payment methods you want to use for each transacting MID.

Click

Manage

to edit your existing payment method configurations or enroll in new payment methods as they are released.

Server-Side Set Up

This section contains the information you need to set up your server. Initializing Unified Checkout within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials, and establishes how the Unified Checkout frontend components will function. The sessions API request contains parameters that define how Unified Checkout performs.

The server-side component provides this information:

A transaction-specific public key is used by the customer's browser to protect the transaction.

An authenticated context description package that manages the payment experience on the client side. It includes available payment options such as card networks, payment interface styling, and payment methods.

The functions are compiled in a JSON Web Token (JWT) object referred to as the capture context
. For information JSON Web Tokens, see JSON Web Tokens.

Capture Context

This section contains the information you need to set up your server. Initializing Unified Checkout within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials, and establishes how the frontend components will function. The sessions API request contains parameters that define how Unified Checkout performs.

The server-side component provides this information:

A transaction-specific public key is used by the customer's browser to protect the transaction.

An authenticated context description package that manages the payment experience on the client side. It includes available payment options such as card networks, payment interface styling, and payment methods.

The functions are compiled in a JSON Web Token (JWT) object referred to as the capture context
.

For information on JWTs see JSON Web Tokens.

The capture context request is a signed JSON Web Token (JWT) that includes all of the merchant-specific parameters. This request tells the frontend JavaScript library how to behave within your payment experience. The request provides authentication, one-time keys, the target origin to the Unified Checkout integration in addition to allowed card networks and payment types. The capture context request includes these elements:

allowedCardNetworks

allowedPaymentTypes

clientVersion

targetOrigin

completeMandate

Use the

targetOrigins

and the

allowedPaymentTypes

fields to define the target origin and the accepted digital payment methods in your capture context. Use the

comppleteMandate

to orchestrate follow-on services such as Payments, Decision Manager, and Payer Authentication. For example:

{
  "clientReferenceInformation": {
    "code": "TAGX001"
  },
  "targetOrigins": [
    "https://www.test.com"
  ],
  "clientVersion": "0.28",
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "PANENTRY",
    "CLICKTOPAY",
    "GOOGLEPAY"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "1.01",
      "currency": "USD"
    }
  },
  "completeMandate": {
    "type": "CAPTURE",
    "decisionManager": true,
    "consumerAuthentication": true
  }
}

This diagram shows how elements of the capture context request appear in the card entry form.

Image of the capture context request code and how it appears in the
entry form elements. — Anatomy of a Manual Card Entry Form

Client-Side Set Up

This section contains the information you need to set up the client side. You use the Unified Checkout JavaScript library to add the payment interface to your e-commerce site. It has two primary components:

The button widget, which lists the payment methods available to the customer.

The payment acceptance page, which captures payment information from the cardholder. You can set up the payment acceptance page to be embedded with your webpage or added as a sidebar.

Follow these steps to set up the client:

Load the JavaScript library.

Initialize the accept object, the capture context JWT. For information JSON Web Tokens, see JSON Web Tokens.

Initialize the unified payment object with optional parameters.

Show the button list or payment acceptance page or both.

Process the payment request using the instructions included within the capture mandate.

The response to these interactions is a transient token that you use to retrieve the payment information captured by the UI.

Loading the JavaScript Library and Invoking the Accept Function

Use the client library asset path and client library integrity value that is returned by the capture context response to invoke Unified Checkout on your page.

You can retrieve these values from the

clientLibrary

and

clientLibraryIntegrity

fields that are returned in the JWT from

https://apitest.visaacceptance.com/up/v1/capture-contexts

. You can use these values to create your script tags.

You must perform this process for each transaction, as these values may be unique for each transaction. You must avoid hard-coding values for the

clientLibrary

and

clientLibraryIntegrity

fields to prevent client-side errors.

For example, a response from

https://apitest.visaacceptance.com/up/v1/capture-contexts

would include:

"data": {
    "clientLibrary":"[EXTRACT clientLibrary VALUE from here]",
    "clientLibraryIntegrity": "[EXTRACT clientLibraryIntegrity VALUE from here]"
}

Below is an example script tag:

<script src="[INSERT clientLibrary VALUE HERE]" 
    integrity=”[INSERT clientLibraryIntegrity VALUE HERE]”
    crossorigin=”anonymous”></script>

IMPORTANT

Use the

clientLibrary

and

clientLibraryIntegrity

parameter values in the capture context response to obtain the Unified Checkout JavaScript library URL and the integrity value. This ensures that you are always using the most up-to-date library and protects against fraud. Do not hard-code the Unified Checkout JavaScript library URL or integrity value.

When you load the library, the capture context from your initial server-side request is used to invoke the accept function.

JavaScript Example: Initializing the SDK

try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);


      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }

In this example,

captureContext

refers to the capture context JWT.

JavaScript Example: Displaying the Button List

After you initialize the Unified Checkout object, you can add the payment application and payment acceptance pages to your webpage. You can attach the embedded Unified Checkout tool and payment acceptance pages to any named element within your HTML. Typically, they are attached to explicit named components that are replaced with Unified Checkout’s iframes.

try {
    const accept = await Accept(captureContext);
    const up = await accept.unifiedPayments(sidebar);
    const tt = await up.show(showArgs);
} catch (error) {
    // merchant logic for handling issues
    console.error("something went wrong: " + error);
}

To display the Unified Checkout Button List within your payment page, a call is made to the unifiedPayments.Show() function. This function accepts a JSON object that links the

<div>

tags within your payment page to place the Unified Checkout button list and optional embeddable payment page.

const showArgs = {
    containers: {
        paymentSelection: '#buttonPaymentListContainer',
        paymentScreen: '#embeddedPaymentContainer'
    }
};

The response to the unifiedPayment.show() method is a JWT data object referred to here as a transient token. The transient token contains all the payment information captured during the Unified Checkout payment journey.

JavaScript Example: Client-Defined Trigger for `Click to Pay` or PAN Entry

When you are presenting

CLICKTOPAY

or

PANENTRY

as allowed payment types, you can load the UI without displaying the

Checkout with Card

button by creating a trigger that defines what loads the UI.

You can create a trigger by calling the

createTrigger()

method on an existing unified payments object and pass in these two parameters:

The payment method that the trigger is linked to. It is required.

IMPORTANT

You can create a trigger only for

CLICKTOPAY

or

PANENTRY

payment methods.

The container for the payment screen. It is required when you are in embedded mode.

// Example: Basic usage with full sidebar experience
// Create a trigger
const trigger = up.createTrigger("CLICKTOPAY");

// Show the trigger
// In this example, when a button in your UI is clicked
const myButton = document.getElementById("myButton");

myButton.addEventListener("click", async () => {
  const transientToken = await trigger.show();
  console.log(transientToken);
})

// Example: Payment screen in a container
// Define the container for the payment screen to be rendered in 
var options = { containers: { paymentScreen: '#paymentScreenContainer' } };
// Create the trigger
const trigger = up.createTrigger("CLICKTOPAY", options);

// Show the trigger
// In this example, when a button in your UI is clicked
const myButton = document.getElementById("myButton");

myButton.addEventListener("click", async () => {
  const transientToken = await trigger.show();
  console.log(transientToken);
})

JavaScript Example: Processing a Payment

Payment is initiated when Unified Checkout captures the customer's payment information by calling the

unifiedPayment.complete()

function and passing the transient token.

try {
    const accept = await Accept(captureContext);
    const up = await accept.unifiedPayments(sidebar);
    const tt = await up.show(showArgs);
    const completeResponse = await up.complete(tt);

    console.log(completeResponse); // merchant logic for handling complete response
} catch (error) {
    // merchant logic for handling issues
    console.error("something went wrong: " + error);
}
}

When you include this in your capture context, Unified Checkout is leveraged to initiate payment. Alternatively, you can call the payment APIs directly. See Authorizations with a Transient Token.

JavaScript Example: Setting Up with Full Sidebar

<html>
<head>
  <script
    src="[INSERT clientLibrary VALUE HERE]"
    integrity="[INSERT clientLibraryIntegrity VALUE HERE]”
    crossorigin=”anonymous"
  ></script>
</head>
<body>
  <h1>Unified Checkout Integration</h1>
  <input
    type="hidden"
    name="captureContext"
    value="[INSERT captureContext HERE]"
  />
  <script type="text/javascript">
    const sidebar = true;
    const captureContext = document.getElementById("captureContext").value;
const showArgs = { containers: {
paymentSelection: '#buttonPaymentListContainer', 
}
};
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        const completeResponse = await up.complete(tt);
    
        console.log(completeResponse); // merchant logic for handling complete response
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }

    // Call the function
    launchCheckout();
  </script>
</body>

JavaScript Example: Setting Up with the Embedded Component

The main difference between using an embedded component and the sidebar is that the

accept.unifiedPayments

object is set to

false

, and the location of the payment screen is passed in the containers argument.

IMPORTANT

If you do not specify a location for the payment acceptance page, it is placed in the side bar.

<html>
<head>
  <script
    src="[INSERT clientLibrary VALUE HERE]"
    integrity="[INSERT clientLibraryIntegrity VALUE HERE]”
    crossorigin=”anonymous"
  ></script>
</head>
<body>
  <h1>Unified Checkout Integration</h1>
  <input
    type="hidden"
    name="captureContext"
    value="[INSERT captureContext HERE]"
  />
  <script type="text/javascript">
    const sidebar = false;
    const captureContext = document.getElementById("captureContext").value;
    const showArgs = {
      containers: { paymentSelection: "#buttonPaymentListContainer",
paymentScreen:	'#embeddedPaymentContainer' }
    };
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        const completeResponse = await up.complete(tt);
    
        console.log(completeResponse); // merchant logic for handling complete response
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }

    // Call the function
    launchCheckout();
  </script>
</body>

Transient Tokens

The response to a successful customer interaction with Unified Checkout is a transient token. This is returned in the response from the

unifiedPayment.show()

function. 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 expires after 15 minutes. This reduces your PCI burden/responsibility and ensures that sensitive information is not exposed to your back-end systems.

Transient tokens can be included requests sent to the Payment Details and Payment Credentials APIs in exchange for the customer payment data that is collected. This data can include the payment account number (PAN) or tokenized credentials.

Transient Token Format

The transient token is issued as a JSON Web Token (JWT) (RFC 7519). For information on JSON Web Tokens, see JSON Web Tokens.

The payload portion of the token is a Base64-encoded JSON string and contains various claims. For more information, see JSON Web Tokens.

Example: Transient Token Format

Transient Token Payload

{
  "iss": "Flex/00",
  "exp": 1706910242,
  "type": "gda-0.9.0",
  "iat": 1706909347,
  "jti": "1D1I2O2CSTMW3UIXOKEQFI4OQX1L7CMSKDE3LJ8B5DVZ6WBJGKLQ65BD6222D426",
  "metadata": {
    "consumerPreference": {
      "saveCard": true
    },
    "tokenizedCard": {
      "card": {
        "maskedValue": "XXXXXXXXXXXX9876",
        "prefix": "123456",
        "expirationMonth": "MM",
        "expirationYear": "YYYY"
      }
    }
  },
  "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"
        }
      }
    }
  }
}

PAN BIN in

metadata

Object

The

cardDetails

object, including the PAN BIN, is included in the transient token

metadata

when a Click to Pay network token is used as a payment method. This allows you to display information about the card on invoices and see the BIN details that are linked to the underlying card.

"metadata": {
  "cardDetails": {
    "suffix": "9876",
    "prefix": "123456",
    "expirationMonth": "MM",
    "expirationYear": "YYYY"
  }
}

Authentication Status in

metadata

Object

The

authenticationStatus

object is included in the

metadata

and enables you to determine if the payload is fully authenticated. When

authenticationStatus

is set to

true

, the payload is fully authenticated. When

authenticationStatus

is set to

false

, the transaction is not authenticated.

If you are using Unified Checkout with the complete API and you include

consumerAuthentication

in the complete mandate request, then Payer Authentication is called automatically if it is available for the selected payment method and card network. In this case, there is no action required on your part.

"metadata": {
  "authenticationStatus": "true"
  }
}

Token Verification

When you receive the transient token, you should cryptographically verify its integrity using the public key embedded within the capture context. Doing so verifies that Visa Acceptance Solutions issued the token and that the data has not been tampered with in transit. Verifying the transient token JWT involves verifying the signature and various claims within the token. Programming languages each have their own specific libraries to assist.

Dual-Branded Cards

Unified Checkout accepts dual-branded cards. To use this feature, you must include the card networks that have overlapping BIN ranges in the capture context request. For example:

"allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES"]

When a card number within an overlapping BIN range is entered, the network that is listed first in the value array for the

allowedCardNetworks

field is used. For example, if the card number 403550XXXXXXXXXX is entered, the payment network is Visa.

During the transaction, the card type is populated with the first network in the list, and the detectedCardTypes
field includes all of the detected card types in the transient token.

The

detectedCardTypes

field is returned in the transient token response only when more than one card type is detected.

Authorizations with a Transient Token

This section provides the minimum information required in order to perform a successful authorization with a Unified Checkout transient token. You can use this method to construct more complex payment scenarios that are not supported by the

unifiedPayment.complete()

payment method.

IMPORTANT

When you process payments through Unified Checkout, Unified Checkout invokes service orchestration directly. When you send an authorization request using a transient token, you are using an alternative method for processing payments.

The transient token is a short-term token that expires after 15 minutes. Doing so eliminates the need to send sensitive payment data along with the request. For more information on transient tokens, see Transient Tokens.

To send the transient token with a request, use the

tokenInformation.transientTokenJwt

field.

This example shows a transient token in the context of an authorization request:

"tokenInformation": { 
    "transientTokenJwt": "eyJraWQiOiIwOG4zUnVsRTJGQXJDRktycVRkZFlkWGZSWFhMNXFoNSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJGbGV4LzA3IiwiZXhwIjoxNTk3MDg0ODk3LCJ0eXBlIjoiZ2RhLTAuMS4xIiwiaWF0IjoxNTk3MDgzOTk3LCJqdGkiOiIxQzI2VlpSkVJUU1PTzVIMDUwNEtINDdJMEFNMklaRkM0M1Y1TDU0MUhCTE45Q09JM0w3NUYzMTk0RTE5NkExIn0.SNm1VZaZr3DkTqUg9CdV0F5arRe-uQU9oUWPKfWIpbIzIPZutRokv5DSDcM7asZIKNJyNIBx5DLsl_yQPrKgzhwQxZ8qbhto7cu3t-v8DHG2yO951plPQVQnj7x-vEDcXkLUL1F8sqY23R5HW-xSDAQ3AFLawCckn7Q2eudRGeuMhLWH742Gflf9Hz3KyKnmeNKA3o9yW2na16nmeVZaYGqbUSPVITdl5cMA0o9lEob8E3OQH0HHdmIsu5uMA4x7DeBjfTKD1rQxFP3JBNVcv30AIMLkNcw0pHbtHDVzKBWxUVxvnm3zFEdiBuSAco2uWhC9zFqHrrp64ZvzxZqoGA" 
}

To retrieve non-sensitive data from a Unified Checkout transient token, use the

payment-details

endpoint. This data includes cardholder name and billing and shipping details. For more information, see Payment Details API.

IMPORTANT

Fields supplied directly in an API request supersede those that are also present in the transient token. For example, in the request below, the total amount might have been overridden because of a tax calculation.

Endpoint

Production:

POST https://api.visaacceptance.com/pts/v2/payments

Test:

POST https://apitest.visaacceptance.com/pts/v2/payments

Required Field for an Authorization with a Transient Token

tokenInformation.transientTokenJwt

REST Example: Requesting an Authorization with a Transient Token

{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "processingInformation": {
    "commerceIndicator": "internet"
  },
  "tokenInformation": {
    "transientTokenJwt": "eyJraWQiOiIwOG4zUnVsRTJGQXJDRktycVRkZFlkWGZSWFhMNXFoNSIsImFs
ZyI6IlJTMjU2In0.eyJpc3MiOiJGbGV4LzA3IiwiZXhwIjoxNTk3MDg0ODk3LCJ0eXBlIjoiZ2RhLTAuMS4xIi
wiaWF0IjoxNTk3MDgzOTk3LCJqdGkiOiIxQzI2VlpSRkVJUU1PTzVIMDUwNEtINDdJMEFNMklaRkM0M1Y1TDU0
MUhCTE45Q09JM0w3NUYzMTk0RTE5NkExIn0.SNm1VZaZr3DkTqUg9CdV0F5arRe-uQU9oUWPKfWIpbIzIPZutR
okv5DSDcM7asZIKNJyNIBx5DLsl_yQPrKgzhwQxZ8qbhto7cu3t-v8DHG2yO951plPQVQnj7x-vEDcXkLUL1F8
sqY23R5HW-xSDAQ3AFLawCckn7Q2eudRGeuMhLWH742Gflf9Hz3KyKnmeNKA3o9yW2na16nmeVZaYGqbUSPVIT
dl5cMA0o9lEob8E3OQH0HHdmIsu5uMA4x7DeBjfTKD1rQxFP3JBNVcv30AIMLkNcw0pHbtHDVzKBWxUVxvnm3z
FEdiBuSAco2uWhC9zFqHrrp64ZvzxZqoGA"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1Market St",
      "address2": "Address 2",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "[email protected]",
      "phoneNumber": "4158880000"
    }
  }
}

Capture Context API

The capture context request contains all of the merchant-specific parameters that tell the front-end JavaScript library what to do within your payment experience.

The capture context is a signed JSON Web Token (JWT) containing this information:

Merchant-specific parameters that dictate the customer payment experience for the current payment transaction.

A one-time public key that secures the information flow during the current payment transaction.

The capture context request includes these fields:

allowedCardNetworks

allowedPaymentTypes

clientVersion

targetOrigins

transientTokenResponseOptions.includeCardPrefix

completeMandate

For information on JSON Web Tokens, see JSON Web Tokens.

Target Origin: The target origin is defined by the scheme (protocol), hostname (domain), and port number (if used).

You must use the https:// protocol. Sub domains must also be included in the target origin.

Any valid top-level domains, such as .com, .co.uk, and .gov.br, are supported. Wildcards are not supported.

For example, if you are launching Unified Checkout on example.com, the target origin could be any of the following:

https://example.com
https://subdomain.example.com
https://example.com:8080

You can define the payment cards and digital payments that you want to accept in the capture context.
Allowed Card Networks: Use the
allowedCardNetworks
field to define the card types.

These card networks are available for card entry:
American Express
Cartes Bancaires
Carnet
China UnionPay
Diners Club
Discover
EFTPOS
ELO
JCB
JCrew
mada
Maestro
Mastercard
Meeza
PayPak
Visa

To support dual-branded or co-badged cards, you must list your supported card type values for the
allowedCardNetworks
field based on your preference for processing card numbers. For example, if a card is dual-branded as Visa and Cartes Bancaires, and Cartes Bancaires is listed first, the card type is set to Cartes Bancaires after the card number is entered in your Unified Checkout card collection form. For information on dual-branded or co-badged cards, see Dual-Branded Cards.

Allowed Payment Types: You can specify the type of Unified Checkout digital payment methods that you want to accept in the capture context.; Use the
allowedPaymentTypes
field to define the payment type:
APPLEPAY
CHECK
CLICKTOPAY
GOOGLEPAY
PANENTRY
PAZE
AFTERPAY
IDEAL
MULTIBANCO
IMPORTANT

Click to Pay accepts American Express, Mastercard, and Visa for saved cards. Visa and Mastercard tokenize payment credentials using network tokenization for all Click to Pay requests. Click to Pay uses Click to Pay Token Requester IDs (TRIDs) rather than your existing TRIDs to generate network tokens.
For more information on enabling and managing these digital payment methods, see these topics:
Enrolling in Apple Pay
Enabling Click to Pay
Enrolling in Google Pay
Complete Mandate: The complete mandate feature provides service orchestration within Unified Checkout and simplifies your integration. Service orchestration enables Unified Checkout to orchestrate services on your behalf. The complete mandate feature provides instructions to the
unifiedPayment.complete()
method in the JavaScript SDK. You must include the
completeMandate
field object in your capture context to enable Unified Checkout to initiate services on your behalf from the browser.

The complete mandate feature is defined by three fields:
completeMandate.type
: This field is used to indicate how a payment should be processed.
Possible values:
AUTH
: Authorize the payment and capture the funds at a later date.
CAPTURE
: Perform a sale.
PREFER_AUTH
: Perform an authorization if possible. If a payment method requires the funds to be captured immediately, then Unified Checkout captures the payment.
completeMandate.decisionManager
: This field determines whether Decision Manager is run. Set this field to
true
and include
complete.Mandate.type
in your request to run Decision Manager and device fingerprinting services. When Decision Manager runs, it uses the associated Decision Manager configuration based on the merchant ID that is included in the request.
When this field is set to
false
or is not included in the request, Decision Manager and device fingerprinting services are not run.
completeMandate.consumerAuthentication
: This field determines whether Payer Authentication should be used. Set this field to
true
and include
complete.Mandate.type
in your request to run Payer Authentication. When this field set to
true
, Payer Authentication runs. When this field is set to
false
or is not included in the request, Payer Authentication does not run.
Consumer authentication is available for these card types:
American Express
Cartes Bancaires
China UnionPay
Discover
ELO
JCB
Mastercard
Visa
Include Card Prefix: You can control the length of the card number prefix to be received in the response to the capture context
/sessions
request:
Six digits
Eight digits
No prefix
To specify your preferred card number prefix length, include or exclude the
transientTokenResponseOptions.includeCardPrefix
field in the capture context
/sessions
request.; To receive a six-digit card number prefix in the response, follow this step:

Do not
include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context
/sessions
request.

This example shows how a six-digit card number prefix
411111
is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”, "bin" : "411111"; To receive an eight-digit card number prefix in the response, follow this step:

Include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context request, and set the value to
true
.
IMPORTANT

This PCI DSS requirement applies only to card numbers longer than 15 digits and only for Discover, JCB, Mastercard, UnionPay, and Visa brands.
If the card type entered is not part of these brands, a six-digit card number prefix is returned instead.
If the card type entered is not part of these brands but is co-branded
with these brands, an eight-digit card number prefix is returned.
This example shows how an eight-digit card prefix
41111102
is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”, "prefix" : "41111102"; To not receive a card number prefix in the response, follow this step:

Include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context request, and set the value to
false
.

This example shows how a card number is returned without a card number prefix in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111"; Best practice:
If your application does not require card number prefix information for routing or identification, Visa Acceptance Solutions recommends that you include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context request and set its value to
false
. Doing so limits the exposure of payment data to only what is necessary for your processing needs.
For more information about PCI DSS, see
Frequently Asked Questions
on the PCI Security Standards Council site.

IMPORTANT

Visa Acceptance Solutions recommends that you dynamically parse the response for the fields that you are looking for when you integrate with Visa Acceptance Solutions APIs. Visa Acceptance Solutions may add additional fields in the future.

You must ensure that your integration can handle new fields that are returned in the response. Even though the underlying data structures do not change, you must also ensure that your integration can handle changes to the order in which the data is returned. Visa Acceptance Solutions uses semantic versioning practices, which enables you to retain backwards compatibility as new fields are introduced in minor version updates.

Features

Unified Checkout comprises these features.

Save Card: Click to Pay and PAN entry payment methods support Save Card when they are set as allowed payment types on Unified Checkout.

When the feature is enabled, the customer can save their card information for future purchases placed at your website.
IMPORTANT

This feature is available only for card credentials that are manually entered during checkout.

When the customer checks the box and finalizes their purchase, you receive a notification in the transient token response to your capture context request. The transient token payload includes the
consumerPreference.saveCard
field value set to
true
:
"captureMandate" : { "requestSaveCard": true }
Combo Cards: A combo card is a single card in Brazil that functions as both a debit and a credit card. Unified Checkout enables the cardholder to choose whether to pay for a transaction using a debit or credit card. The cardholder can choose the card that they want to use when they enter their card details or when they choose a stored Visa card from their Click to Pay wallet during checkout. While in the card details section of the payment form, the cardholder is prompted for a debit or credit card. Credit is the default option.
IMPORTANT

Combo cards are supported on client version 0.24 and later.
To enable combo cards during checkout, you must include the
comboCard
field in your capture context request and set the field value to
true
. When the
comboCard
field value is set to
true
, the option to use a debit or credit card appears for all Visa cards that are entered in
Unified Checkout
and for all cards that are already stored in Click to Pay. If you do not want to offer a combo card at checkout, do not include the
comboCard
field in your capture context request:
"captureMandate" : { "comboCard": true }
Cadastro de Pessoas Físicas (CPF) – Brazilian Tax ID: The tax ID feature is for customers in Brazil and provides your customers with a way to include their Consumer National Identifier when it is requested at checkout. Include this field in the capture context to display this field within the flow for manual card entry and Click to Pay transactions:
"captureMandate" : { "CPF": { "required": true } }
Email Autolookup: Automatic email lookup occurs when an email address is included in the capture context request. If the user has a Click to Pay account but is not on a recognized device, a one-time password (OTP) screen appears and the user is prompted to enter their OTP. If the user does not have a Click to Pay account, the user must enter their card information manually. They will have the option to create a Click to Pay account.
To enable email autolookup, you must include
CLICKTOPAY
as a value in the
allowedPaymentTypes
field and include an email address in the capture context.
Removal of Confirm and Continue Screen: You can opt to not show the confirmation screen to the cardholder during checkout when a user selects an existing Click to Pay card from their Click to Pay account. To hide the confirmation screen you must set these fields to these corresponding values in the capture context:
billingType
=
NONE
requestShipping
=
false
showConfirmationStep
=
false
{ "captureMandate": { "showConfirmationStep": false } }
Click to Pay Enrollment Pre-Check: You can have the Click to Pay box pre-checked when a user is manually entering their card details and Click to Pay is enabled. The customer can uncheck the box if necessary, which means the request is processed as a one-time manual PAN transaction.
Click to Pay enrollment pre-check is available in these countries:
Argentina
Brazil
Chile
Colombia
Kuwait
Mexico
Peru
Qatar
Saudi Arabia
South Africa
Ukraine
United Arab Emirates
{ "allowedPaymentTypes": [ "PANENTRY", "GOOGLEPAY", { "type": "CLICKTOPAY", "options": { "autoCheckEnrollment": true } }, "APPLEPAY", "PAZE" ] }

Client Version History

Below is a list of client versions and the features that are included in each version.

IMPORTANT

Visa Acceptance Solutions recommends that you use the most recent client version in your integration.

0.23: Accepts these card networks in the
allowedCardNetworks
field for manual card entry:
Carnet
Cartes Bancaires
China UnionPay with card verification value (CVV)
EFTPOS
ELO
JCrew PLCC
mada
Meeza; Ordering controls for the
allowedPaymentTypes
button.; De-coupling of PANENTRY from other payment types in the
allowedPaymentTypes
field.
0.24: Support for enabling combo cards in the capture context.; Support for eight-digit BINs.; Support for enabling card save in the capture context.
0.25: Addition of Skip Verification next time
in the Click to Pay payment flow.; Support for CPF in the capture context.
0.26: Support for auto-lookup in Click to Pay when an email is included in the capture context.; Inclusion of the
cardDetails
field object in the transient token response.; Support for the
authenticationStatus
field object in the transient token response.; Support for the complete mandate.
0.28: Complete mandate enhancement to support Payer Authentication for manual card entry for Visa, Mastercard, American Express, Discover, JCB, Cartes Bancaires, China UnionPay, and ELO card brands.; Support for PayPak as an
allowedCardNetwork
.; Auto-enrollment for Click to Pay in supported markets.; Removal of the confirm or continue screen for specific use cases.; Static button for Click to Pay flows.

Requesting the Capture Context

This section contains the information you need in order to request the capture context.

Endpoint

Production:

POST https://api.visaacceptance.com/up/v1/capture-contexts

Test:

POST https://apitest.visaacceptance.com/up/v1/capture-contexts

Required Fields for Requesting the Capture Context

Use these required fields to request the capture context:

allowedPaymentTypes
clientVersion
country
locale
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
targetOrigins: The URL in this field value must contain
https
.

REST Example: Requesting the Capture Context

Request

{
  "clientReferenceInformation": {
    "code": "TAGX001"
  },
  "targetOrigins": [
    "https://www.test.com"
  ],
  "clientVersion": "0.28",
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "PANENTRY",
    "CLICKTOPAY",
    "GOOGLEPAY"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "1.01",
      "currency": "USD"
    }
  },
  "completeMandate": {
    "type": "CAPTURE",
    "decisionManager": true,
    "consumerAuthentication": true
  }
}

Encrypted JWT Response to a Successful Request

eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJHeUhXV0d5SG5lK2Fld1JsalVUaGJoQUFFQVZMbTR6QTA0UHBqaGFXOHVSZ2UvNFQweEtIbW9KUWNYaE1hd0RmVzVQVFBLNXBlZ05vRkVocnNacjdnbldLeHBRdTNWSm4vTDBjbmZOaTRSdjdlTElcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoibVhHbi1DbllDX1pkODVQdTJaaDluVDdZOUpQX1RjUV9BSzlBQTFHQkJfOFVXd2FHWEZIMGxfa2EwXzV0ekFleU5uVWZLQ016WFFHV2dMZ2hnZXdLMjJzWlVXVTdDT0k4RkNTWktpUjBYRGJ2TTVZYkYxejk0TmNmWVJGc0p0ZzhTbE1jY0stS00tOUFjdldYQWlxUEs0Mk5GZnlIVE5uX3BpVDdhZHRDMGFZQlhCdkw2WXFmcWM5bXBua05FQTJVN0x5VWFyRy1rVFVIQW8xX2tjdW1tTEF1X1Y5OEQyMndsaHMtekhEcnFVTFhsNEdKSGF6WjNXVWJDWHc5c0o2dFowVmVnX1Bpbnhmck9mazA0RWNaVlM5clBXWW1HRnA3V2NyR0FQTkRCQzFPZ0NKNW1mRmpMNEtpcVpVNURpTWFsbURGdzg5VVp1bllBVWlrdUU1SURRIiwia2lkIjoiMDBDeWg5UHhhdDdCUkMwa0pXUG5hUVJsOU9jTGMzZVoifX0sImN0eCI6W3siZGF0YSI6eyJhbGxvd2VkUGF5bWVudFR5cGVzIjpbeyJwYWdlIjoxLCJ0eXBlIjoiUEFORU5UUlkifSx7InBhZ2UiOjIsInR5cGUiOiJTUkNWSVNBIn0seyJwYWdlIjozLCJ0eXBlIjoiU1JDTUFTVEVSQ0FSRCJ9LHsicGFnZSI6NCwidHlwZSI6IlNSQ0FNRVgifSx7InBhZ2UiOjUsInR5cGUiOiJHT09HTEVQQVkifSx7InBhZ2UiOjYsInR5cGUiOiJBUFBMRVBBWSJ9XSwicGF5bWVudENvbmZpZ3VyYXRpb25zIjp7IlNSQ1ZJU0EiOnsib3JpZ2luIjoiaHR0cHM6Ly9zYW5kYm94LWFzc2V0cy5zZWN1cmUuY2hlY2tvdXQudmlzYS5jb20iLCJwYXRoIjoiL2NoZWNrb3V0LXdpZGdldC9yZXNvdXJjZXMvanMvc3JjLWktYWRhcHRlci92aXNhU2RrLmpzIiwicGFuRW5jcnlwdGlvbktleSI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsImtpZCI6IldaTEQzS0VBUFdJRThMS0pEMU0xMTNYMXExamZUZE5pNTI0al9aQWxLVmtlanBxM0EiLCJuIjoic1pQSXVzRGY3eVFubmhCa1U5bXUxNFZPTzNDcnVpM2I3ckFmMktZZW9iVVJtWEExN2IxSlg5amcwQ2QtdmdwbXV5VHJ4QlVTYy00YjAtVVBnU3dHRnFQV1VweDA4RXhxcndQRE92Rm9qQm91MndseXE4YmN5MFVzLUJmZUN6U0U1bE1WZFNYVFhYWGNOcXUtcWIyMmpDQ0NKQUxweHNBcnNib01PWHNMZWRoM000WE5RNVhHQXRSZjdiLS11VFk1RHI5S0xZeVV2WktBblkwNE1LSlBFTzU0WWlJRk01RFRBaE5PbXMwODlqZE1keC1VUklLSmpQVTItUnBIRzF1OExDRzAyOFJUSXBQc05iUmFudVM1VEFZX3pseERnYjFoS0ozNlliWkVOSExnOVBYVEJoZE9NbFU5MERUTGxmY2JMVGEtRDdEZ2xqQWFXQ3V2ekxQYUd3In0sInBhcmFtZXRlcnMiOnsic3JjSW5pdGlhdG9ySWQiOiJSNDVOMzQzRDZLWFpSWU1CSVhMSTIxeDgtWGtMaWh4Q21lcFMzaEFlUm91RWcwaTVVIiwic3JjaURwYUlkIjoiOTBhZDlhN2QtOTU5Ni00ZWQxLWE3MTEtMmJjOTllM2JjNWZmIiwic3JjaVRyYW5zYWN0aW9uSWQiOiIzMWJkNTRjZi1hOGIyLTQwMTEtODQ0Ny1jYjczZDM4OGU0NjYiLCJkcGFUcmFuc2FjdGlvbk9wdGlvbnMiOnsiZHBhTG9jYWxlIjoiZW5fVVMiLCJwYXlsb2FkVHlwZUluZGljYXRvciI6IkZVTEwiLCJyZXZpZXdBY3Rpb24iOiJjb250aW51ZSIsImRwYUFjY2VwdGVkQmlsbGluZ0NvdW50cmllcyI6W10sImRwYUFjY2VwdGVkU2hpcHBpbmdDb3VudHJpZXMiOltdLCJkcGFCaWxsaW5nUHJlZmVyZW5jZSI6IkFMTCIsImRwYVNoaXBwaW5nUHJlZmVyZW5jZSI6IkFMTCIsImNvbnN1bWVyTmFtZVJlcXVlc3RlZCI6dHJ1ZSwiY29uc3VtZXJFbWFpbEFkZHJlc3NSZXF1ZXN0ZWQiOnRydWUsImNvbnN1bWVyUGhvbmVOdW1iZXJSZXF1ZXN0ZWQiOnRydWUsInRyYW5zYWN0aW9uQW1vdW50Ijp7InRyYW5zYWN0aW9uQW1vdW50IjoiMS4wMSIsInRyYW5zYWN0aW9uQ3VycmVuY3lDb2RlIjoiVVNEIn0sInBheW1lbnRPcHRpb25zIjp7ImRwYUR5bmFtaWNEYXRhVHRsTWludXRlcyI6MTUsImR5bmFtaWNEYXRhVHlwZSI6IlRBVlYiLCJkcGFQYW5SZXF1ZXN0ZWQiOmZhbHNlfX19fSwiU1JDTUFTVEVSQ0FSRCI6eyJvcmlnaW4iOiJodHRwczovL3NhbmRib3guc3JjLm1hc3RlcmNhcmQuY29tIiwicGF0aCI6Ii9zZGsvc3Jjc2RrLm1hc3RlcmNhcmQuanMiLCJwYW5FbmNyeXB0aW9uS2V5Ijp7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwidXNlIjoiZW5jIiwia2lkIjoiMjAyMzAyMDcyMjM1MjEtc2FuZGJveC1mcGFuLWVuY3J5cHRpb24tc3JjLW1hc3RlcmNhcmQtaW50Iiwia2V5X29wcyI6WyJlbmNyeXB0Iiwid3JhcEtleSJdLCJhbGciOiJSU0EtT0FFUC0yNTYiLCJuIjoidDA2SThzamxTLXJyczd1Q2FnSDhldm9ldW1hUm92S3ppWlNJOVMyTjlJRFE5dFcyUGFwZlJhOUxjMUt2ZUVCRFZzMjdQa2hrVTVPeUhnUDBpRWpUdUtWcHZoNTlUNGxhLW1CU0lsczdVZWNVUUxMYTBXa21idEw3ak5kbHRBNWZxN0FoY0FyNXFjYTk4OHFyTGQ3SXlyOUUwQzNUeGJUOXRvMWlRY3B6OG9jWk9EUlhvaWRGQW5PVkw1WUdGbWxzcmVEYko0VmhzaTBwQWRjY1FjaWwteWRTZ3VyS0ItcnFLcHBiOWVwb211NFFVaDMzODJDdjhOb2JZbUYzb3M4bkdHZ0dQLWN5WG8wbnNLY1BBZ2ZybFF6b3M3cUh4VU9yRmUyeF9sWjFHMUFFLVhya3J4akJ5czlxNTNHTVJTTkNROGMtX21jRjlwYnE0SFlCcy12RDVRIn0sInBhcmFtZXRlcnMiOnsic3JjaVRyYW5zYWN0aW9uSWQiOiIzMWJkNTRjZi1hOGIyLTQwMTEtODQ0Ny1jYjczZDM4OGU0NjYiLCJzcmNpRHBhSWQiOiI5ODQ4Y2ZmNC1jODY0LTRmMTgtOWYwMy1hOGY1MGE2OTJlZGRfc3lzdGVtdGVzdCIsInNyY0luaXRpYXRvcklkIjoiNmY1ZDZjMDktZjhlMi00MzMwLWEzZGYtMjBiOWFkN2E0NTJiIiwiZHBhVHJhbnNhY3Rpb25PcHRpb25zIjp7InRyYW5zYWN0aW9uVHlwZSI6IlBVUkNIQVNFIiwiZHBhTG9jYWxlIjoiZW5fVVMiLCJkcGFBY2NlcHRlZFNoaXBwaW5nQ291bnRyaWVzIjpbXSwiY29uc3VtZXJFbWFpbEFkZHJlc3NSZXF1ZXN0ZWQiOnRydWUsImNvbnN1bWVyUGhvbmVOdW1iZXJSZXF1ZXN0ZWQiOnRydWUsInRyYW5zYWN0aW9uQW1vdW50Ijp7InRyYW5zYWN0aW9uQW1vdW50IjoiMS4wMSIsInRyYW5zYWN0aW9uQ3VycmVuY3lDb2RlIjoiVVNEIn0sImRwYUFjY2VwdGVkQmlsbGluZ0NvdW50cmllcyI6W10sImRwYUJpbGxpbmdQcmVmZXJlbmNlIjoiRlVMTCIsImRwYVNoaXBwaW5nUHJlZmVyZW5jZSI6IkZVTEwiLCJjb25zdW1lck5hbWVSZXF1ZXN0ZWQiOnRydWUsInBheWxvYWRUeXBlSW5kaWNhdG9yIjoiRlVMTCIsInBheW1lbnRPcHRpb25zIjp7ImR5bmFtaWNEYXRhVHlwZSI6IkNBUkRfQVBQTElDQVRJT05fQ1JZUFRPR1JBTV9TSE9SVF9GT1JNIn19fX0sIlNSQ0FNRVgiOnsib3JpZ2luIjoiaHR0cHM6Ly9xd3d3LmFleHAtc3RhdGljLmNvbSIsInBhdGgiOiIvYWthbWFpL3JlbW90ZWNvbW1lcmNlL3NjcmlwdHMvYW1leFNESy0xLjAuMC5qcyIsInBhbkVuY3J5cHRpb25LZXkiOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJraWQiOiJzcmMtYW1leC1jYXJkLWVuYy0yMDI0IiwiYWxnIjoiUlNBLU9BRVAtMjU2IiwibiI6Im1FazBibUxDMlpRVy1hNEtYMW5EWTNaZlBMRnJIOHRuVXlJYjVrVEtnemFlYWdpbWFINFhxUDRadzA1aWk2TXZkdk4wVDJweVNKUTRqb2toUEMySVdlbWlWUEc4ZkNQQk1KeHhqeTJFdTlvdGJpd0dSQkNneHdjdS1hY2pZYXVwVlB0RE43ZW5nSERkbk9nYXJsb0dyUFVNNklFRVpXX3ZFQjljU3JNX0JhOFNjQzhSYWZnTlNZODFpeGF4UEE4Y09oQUF2ckxRN0toRTVReFN6SU1mcnpiMUxCWUdMNFlQQnVuZk5BMnczZnZMd2ZCbDJfLVJGUkNVbVBFdjFOdVhxeG8xUk4wOGoydW44ZWljR3ZudDBndC0yMW5HcmJjNnhwcDdwWlkyb2otaGMwWlVsTnlFX2tKcExTNU9VWjhHZU9acDRxVlJ4aGtJUEd4RWVGLVFXaVNnOHVXazF4Nm5jdGhyTVVKWVYxSFB1OHRIa0pEbThBYS1Ec2hQTmVpeERqX1ZGVkVTOFYteUlJUndnLVUyODJXUGIwVDJ0S1JYZG5qbE52Y2xCc0lfNFZ3ZzVjV0VoU2tTc3pVQXkxUENTRm5rWjVJRU9yaGdfMFRwZTdhaU84dzVzUndOaFpuUnBKeUlzUHQtbE1Dbzd6cjg1QjJ2eGNvUGZmU1NwM0ZaIn0sInBhcmFtZXRlcnMiOnsic3JjaVRyYW5zYWN0aW9uSWQiOiIzMWJkNTRjZi1hOGIyLTQwMTEtODQ0Ny1jYjczZDM4OGU0NjYiLCJzcmNJbml0aWF0b3JJZCI6ImQyZTdkOTc1LWIwYWEtNGZhYS05YTUxLTY4MDAyMjkwZDc1NiIsImRwYURhdGEiOnsiZHBhTmFtZSI6InRlc3QgU2hvcCB3ZWJzaXRlIFJlZ2lzdHJhdGlvbiIsImRwYUxvZ29VcmkiOiJodHRwOi8vd3d3LnRlc3RzcmNyZWdpc3RyYXRpb24uY29tIiwiZHBhUHJlc2VudGF0aW9uTmFtZSI6InRlc3QgU2hvcCB3ZWJzaXRlIFJlZ2lzdHJhdGlvbiIsImRwYVVyaSI6Imh0dHA6Ly93d3cudGVzdHNyY3JlZ2lzdHJhdGlvbi5jb20ifSwiZHBhVHJhbnNhY3Rpb25PcHRpb25zIjp7ImRwYUxvY2FsZSI6ImVuX1VTIiwiZHBhQWNjZXB0ZWRCaWxsaW5nQ291bnRyaWVzIjpbXSwiZHBhQWNjZXB0ZWRTaGlwcGluZ0NvdW50cmllcyI6W10sImRwYUJpbGxpbmdQcmVmZXJlbmNlIjoiQUxMIiwiZHBhU2hpcHBpbmdQcmVmZXJlbmNlIjoiQUxMIiwiY29uc3VtZXJOYW1lUmVxdWVzdGVkIjp0cnVlLCJjb25zdW1lckVtYWlsQWRkcmVzc1JlcXVlc3RlZCI6dHJ1ZSwiY29uc3VtZXJQaG9uZU51bWJlclJlcXVlc3RlZCI6dHJ1ZSwicmV2aWV3QWN0aW9uIjoiY29udGludWUiLCJ0aHJlZURzUHJlZmVyZW5jZSI6Ik5PTkUiLCJwYXltZW50T3B0aW9ucyI6W3siZHluYW1pY0RhdGFUeXBlIjoiRFlOQU1JQ19DQVJEX1NFQ1VSSVRZX0NPREUiLCJkcGFEeW5hbWljRGF0YVR0bE1pbnV0ZXMiOiIxNSJ9XX19fSwiR09PR0xFUEFZIjp7ImNsaWVudExpYnJhcnkiOiJodHRwczovL3BheS5nb29nbGUuY29tL2dwL3AvanMvcGF5LmpzIiwicGF5bWVudE9wdGlvbnMiOnsiZW52aXJvbm1lbnQiOiJURVNUIn0sInBheW1lbnREYXRhUmVxdWVzdCI6eyJhcGlWZXJzaW9uIjoyLCJhcGlWZXJzaW9uTWlub3IiOjAsIm1lcmNoYW50SW5mbyI6eyJtZXJjaGFudElkIjoiQkNSMkRONFQ3RERZQlRUViIsIm1lcmNoYW50TmFtZSI6IlVuaWZpZWQgQ2hlY2tvdXQgTWVyY2hhbnQifSwiYWxsb3dlZFBheW1lbnRNZXRob2RzIjpbeyJ0eXBlIjoiQ0FSRCIsInBhcmFtZXRlcnMiOnsiYWxsb3dlZEF1dGhNZXRob2RzIjpbIlBBTl9PTkxZIiwiQ1JZUFRPR1JBTV8zRFMiXSwiYWxsb3dlZENhcmROZXR3b3JrcyI6WyJWSVNBIiwiTUFTVEVSQ0FSRCIsIkFNRVgiXSwiYmlsbGluZ0FkZHJlc3NSZXF1aXJlZCI6dHJ1ZSwiYmlsbGluZ0FkZHJlc3NQYXJhbWV0ZXJzIjp7ImZvcm1hdCI6IkZVTEwiLCJwaG9uZU51bWJlclJlcXVpcmVkIjp0cnVlfX0sInRva2VuaXphdGlvblNwZWNpZmljYXRpb24iOnsidHlwZSI6IlBBWU1FTlRfR0FURVdBWSIsInBhcmFtZXRlcnMiOnsiZ2F0ZXdheSI6ImN5YmVyc291cmNlIiwiZ2F0ZXdheU1lcmNoYW50SWQiOiJwc19ocGEifX19XSwidHJhbnNhY3Rpb25JbmZvIjp7InRvdGFsUHJpY2VTdGF0dXMiOiJGSU5BTCIsInRvdGFsUHJpY2UiOiIxLjAxIiwiY291bnRyeUNvZGUiOiJVUyIsImN1cnJlbmN5Q29kZSI6IlVTRCJ9LCJlbWFpbFJlcXVpcmVkIjp0cnVlLCJzaGlwcGluZ0FkZHJlc3NSZXF1aXJlZCI6dHJ1ZSwic2hpcHBpbmdBZGRyZXNzUGFyYW1ldGVycyI6eyJwaG9uZU51bWJlclJlcXVpcmVkIjp0cnVlfX19LCJBUFBMRVBBWSI6eyJzZXNzaW9uUGF0aCI6Ii9mbGV4L3YyL2FwcGxlL3BheW1lbnQtc2Vzc2lvbnMiLCJtZXJjaGFudElkZW50aWZpZXIiOiJtZXJjaGFudC5jb20uY3liZXJzb3VyY2Uuc3RhZ2VmbGV4IiwiZGlzcGxheU5hbWUiOiJVQyBUZXN0In19LCJjYXB0dXJlTWFuZGF0ZSI6eyJiaWxsaW5nVHlwZSI6IkZVTEwiLCJyZXF1ZXN0RW1haWwiOnRydWUsInJlcXVlc3RQaG9uZSI6dHJ1ZSwicmVxdWVzdFNoaXBwaW5nIjp0cnVlLCJzaGlwVG9Db3VudHJpZXMiOltdLCJzaG93QWNjZXB0ZWROZXR3b3JrSWNvbnMiOnRydWV9LCJvcmRlckluZm9ybWF0aW9uIjp7ImFtb3VudERldGFpbHMiOnsidG90YWxBbW91bnQiOiIxLjAxIiwiY3VycmVuY3kiOiJVU0QifX0sInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly90aGUtdXAtZGVtby5hcHBzcG90LmNvbSJdLCJpZnJhbWVzIjp7Im1jZSI6Ii9tY2UvaWZyYW1lLmh0bWwiLCJidXR0b25zIjoiL2J1dHRvbmxpc3QvaWZyYW1lLmh0bWwiLCJzcmMiOiIvc2VjdXJlLXJlbW90ZS1jb21tZXJjZS9zcmMuaHRtbCIsImN0cCI6Ii9jdHAvY3RwLmh0bWwiLCJnb29nbGVwYXkiOiIvZ29vZ2xlcGF5L2dvb2dsZXBheS5odG1sIiwiYXBwbGVwYXkiOiIvYXBwbGVwYXkvYXBwbGVwYXkuaHRtbCIsInBhemUiOiIvcGF6ZS9wYXplLmh0bWwifSwiY2xpZW50VmVyc2lvbiI6IjAuMTkiLCJjb3VudHJ5IjoiVVMiLCJsb2NhbGUiOiJlbl9VUyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIl0sImNyIjoiNmM0dUcyemFXdVBvbkxLM0R2NEwxVlJpTFVOMkFVczY4QU84bVdaUTA0X1RNLVFDdDhNUDNTQklvcGQ2Y2NtOTdmSEo1QXViVzh6VFhJTW91TTRjQWFrbm80NktIVndGRFpxQ0tfWTVwMEVzRHJmdFVTREFrZ21KZ0pNbHJ2cnYzTkpFOWdzcldBMl8zdDJBR2hQbEtfMU9rZyIsInNlcnZpY2VPcmlnaW4iOiJodHRwczovL3N0YWdldXAuY3liZXJzb3VyY2UuY29tIiwiY2xpZW50TGlicmFyeSI6Imh0dHBzOi8vc3RhZ2V1cC5jeWJlcnNvdXJjZS5jb20vdXAvdjEvYXNzZXRzLzAuMTkuMC9TZWN1cmVBY2NlcHRhbmNlLmpzIiwibG9nZ2luZ1BhdGgiOiIvdXAvdjEvbG9nLWV2ZW50cyIsImFzc2V0c1BhdGgiOiIvdXAvdjEvYXNzZXRzLzAuMTkuMCIsImNsaWVudExpYnJhcnlJbnRlZ3JpdHkiOiJzaGEyNTYtWllDT2tucVh5bjRad3NyOFYwaE5OcjZaUitZYThJbHNkdFplTkhPbDJYVVx1MDAzZCJ9LCJ0eXBlIjoiZ2RhLTAuOS4wIn1dLCJpc3MiOiJGbGV4IEFQSSIsImV4cCI6MTcxMDk2NDc4MCwiaWF0IjoxNzEwOTYzODgwLCJqdGkiOiI4SWs4bHU2NEh3NmpDVDhsIn0.XWXmjiZZGyHWIhT1hbBnc2xfhcYczpBYxhTn4g9NMt2utMaPR8wWcZ8TYDXd8HRLBWZkktkXxFFetJ4Tc6dQ4irZ6KmalWItWEUJpjN-5sLC4Qr1gG1JOOH5_hK6n_1hnjcQeRUBg-MsCSRBE_MA6ROSZgyfc1_WwL0g1TQUiKN5SvaM_37ooimebPQfvYyXyR_6Zkn9fu51w6NF_Qj0wtuQP4J4P3cgyZzzOFNKuHOwi7ISmyW6BcQXQrec577SRBfcMhhC3PBxl5OrXua4qUJ_qYbplA8P4n6f2--onAYef3UXFHmc28eRiTEeN0l0P1Yj45CIotbuw36mZrnRPQ

Decrypted Capture Context Header

{
  "kid": "j4", 
  "alg": "RS256"
}

Decrypted Capture Context Body with Selected Fields

{ 
  "flx" : { 
    // filled with token metadata 
  }, 
  "ctx" : [ { 
    // filled with data related to your capture context request parameters 
    "data" : { 
      "clientLibrary" : "https://apitest.example.com/up/v1/assets/0.26.0/SecureAcceptance.js" 
    }, 
    "type" : "gda-0.9.0" 
  } ], 
  "iss" : "Flex API", 
  "exp" : "1710964780", 
  "iat" : "1710963880", 
  "jti" : "8Ik8lu64Hw6jCT8l" 
}

Validating the Capture Context

The capture context that you generate is a JSON Web Token (JWT) data object. The JWT is digitally signed using a public key and confirms the validity of the JWT and that it comes from Visa Acceptance Solutions. When you do not have a key in the JWT header, Visa Acceptance Solutions recommends that you follow cryptography best practices and validate the capture context signature.

To validate a JWT, you must obtain its public key. This public RSA key is in JSON Web Key (JWK) format. The public key is associated with the capture context on the Visa Acceptance Solutions domain.

To get the public key of a capture context from the header of the capture context itself, you must retrieve the key ID associated with the public key and then pass the key ID to the

/flex/v2/public-keys

endpoint:

From the header of the capture context, get the key ID (

kid

):

{
    "kid": "3g",
    "alg": "RS256"
}

Send a GET request to the

/flex/v2/public-keys

endpoint and include the key ID. For example:

Test:

GET https://apitest.visaacceptance.com/flex/v2/public-keys/{3g}

Production:

GET https://api.visaacceptance.com/flex/v2/public-keys/{3g}

Depending on the cryptographic method you use to validate the public key, you might need to convert the key to privacy-enhanced mail (PEM) format.

The resource returns the public key:

eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiI2bUFLNTNPNVpGTUk5Y3RobWZmd2doQUFFRGNqNU5QYzcxelErbm8reDN6WStLOTVWQ2c5bThmQWs4czlTRXBtT21zMmVhbEx5NkhHZ29oQ0JEWjVlN3ZUSGQ5YTR5a2tNRDlNVHhqK3ZoWXVDUmRDaDhVY1dwVUNZWlZnbTE1UXVFMkEiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbSIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsIm4iOiJyQmZwdDRjeGlkcVZwT0pmVTlJQXcwU1JCNUZqN0xMZjA4U0R0VmNyUjlaajA2bEYwTVc1aUpZb3F6R3ROdnBIMnFZbFN6LVRsSDdybVNTUEZIeTFJQ3BfZ0I3eURjQnJ0RWNEanpLeVNZSTVCVjNsNHh6Qk5CNzRJdnB2Smtqcnd3QVZvVU4wM1RaT3FVc0pfSy1jT0xpYzVXV0ZhQTEyOUthWFZrZFd3N3c3LVBLdnMwNmpjeGwyV05STUIzTS1ZQ0xOb3FCdkdCSk5oYy1uM1lBNU5hazB2NDdiYUswYWdHQXRfWEZ0ZGItZkphVUVUTW5WdW9fQmRhVm90d1NqUFNaOHFMOGkzWUdmemp2MURDTUM2WURZRzlmX0tqNzJjTi1OaG9BRURWUlZyTUtiZ3QyRDlwWkJ1d2gzZlNfS3VRclFWTVdPelRnT3AzT2s3UVFGZ1EiLCJraWQiOiIwOEJhWXMxbjdKTUhjSDh1bkcxc1NDUVdxN2VveWQ1ZyJ9fSwiY3R4IjpbeyJkYXRhIjp7InRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly93d3cudGVzdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbSJ9LCJ0eXBlIjoibWYtMC4xMS4wIn1dLCJpc3MiOiJGbGV4IEFQSSIsImV4cCI6MTYxNjc3OTA5MSwiaWF0IjoxNjE2Nzc4MTkxLCJqdGkiOiJ6SG1tZ25uaTVoN3ptdGY0In0.GvBzyw6JKl3b2PztHb9rZXawx2T817nYqu6goxpe4PsjqBY1qeTo19R-CP_DkJXov9hdJZgdlzlNmRY6yoiziSZnGJdpnZ-pCqIlC06qrpJVEDob3O_efR9L03Gz7F5JlLOiTXSj6nVwC5mRlcP032ytPDEx5TMI9Y0hmBadJYnhEMwQnn_paMm3wLh2v6rfTkaBqd8n6rPvCNrWMOwoMdoTeFxku-

Use this public RSA key to validate the capture context.

Parse the JWT capture context to get the

kid

from its header:

{
    "kid": "3g",
    "alg": "RS256"
}

Send a GET request to retrieve the public key from

/flex/v2/public-keys/3g

:

{
    "kty":"RSA",    
    "use":"enc",
    "kid":"3g",
    "n":"ir7Nl1Bj8G9rxr3co5v_JLkP3o9UxXZRX1LIZFZeckguEf7Gdt5kGFFfTsymKBesm3Pe
     8o1hwfkq7KmJZEZSuDbiJSZvFBZycK2pEeBjycahw9CqOweM7aKG2F_bhwVHrY4YdKsp
     _cSJe_ZMXFUqYmjk7D0p7clX6CmR1QgMl41Ajb7NHI23uOWL7PyfJQwP1X8HdunE6ZwK
     DNcavqxOW5VuW6nfsGvtygKQxjeHrI-gpyMXF0e_PeVpUIG0KVjmb5-em_Vd2SbyPNme
     nADGJGCmECYMgL5hEvnTuyAybwgVwuM9amyfFqIbRcrAIzclT4jQBeZFwkzZfQF7MgA6QQ",
     "e":"AQAB"
}

Payment Details API

This section contains the information you need to retrieve the non-sensitive data associated with a Unified Checkout transient token and the payment details API. This API can be used to retrieve personally identifiable information, such as the cardholder name and billing and shipping details, without retrieving payment credentials, which helps ease the PCI compliance burden.

There are two methods of authentication, and they are described in the

Getting Started with REST Developer Guide

:

Set Up a JSON Web Token Message

Set Up HTTP Signature Message

IMPORTANT

Visa Acceptance Solutions recommends that you dynamically parse the response for the fields that you are looking for when you integrate with Visa Acceptance Solutions APIs. Visa Acceptance Solutions may add additional fields in the future.

You must ensure that your integration can handle new fields that are returned in the response. Even though the underlying data structures do not change, you must also ensure that your integration can handle changes to the order in which the data is returned. Visa Acceptance Solutions uses semantic versioning practices, which enables you to retain backwards compatibility as new fields are introduced in minor version updates.

Endpoint

Production:

GET https://api.visaacceptance.com/up/v1/payment-details/{id}

Test:

GET https://apitest.visaacceptance.com/up/v1/payment-details/{id}

The

{id}

is the full JWT received from Unified Checkout as the result of capturing payment information. The transient token is a JWT object that you retrieved as part of a successful capture of payment information from a cardholder.

REST Example: Retrieving Transient Token Payment Details

Request

GET https://apitest.visaacceptance.com/up/v1/payment-details/{id}

Response to Successful Request

{
  "paymentInformation": {
    "card": {
      "expirationYear": "2024",
      "number": "XXXXXXXXXXXX1111",
      "expirationMonth": "05",
      "type": "001"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    },
    "billTo": {
      "lastName": "Lee",
      "country": "US",
      "firstName": "Tanya",
      "email": "[email protected]"
    },
    "shipTo": {
      "locality": "Small Town",
      "country": "US",
      "administrativeArea": "CA",
      "address1": "123 Main Street",
      "postalCode": "98765"
    }
  }
}

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
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

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

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"
        }
      }
    }
  }
}

`Unified Checkout` Configuration

This section contains information necessary to configure Unified Checkout in the Business Center:

Enable Digital Payments

Manage Permissions

Webhooks Support

Unified Checkout supports webhooks. You can use webhooks to obtain the complete response from the

completeMandate

call. To receive a webhook notification, you must first subscribe to the webhook.

For information on setting up a webhook, see the How to Set Up Webhook Subscriptions section of the Webhooks Developer Guide
.

IMPORTANT

Webhook payloads are encrypted. In order to receive a Unified Checkout webhook notification, you must upload your public key to the Visa Acceptance Solutions key management system.

`Unified Checkout` Webhook Events
Product ID	Event Types	Description
unifiedCheckout	uc.orders.transactionresults	Full payload response from the payment service call made by `Unified Checkout`

Example: Webhooks Request for Unified Checkout Events

{
    "organizationId": "ps_hpa",
    "webhookId": "2d55e648-d96c-d727-e063-3cb8d30a938e",
    "productId": "unifiedCheckout",
    "requestType": "NEW",
    "payload": {
        "details": {
            "_links": {
                "authReversal": {
                    "method": "POST",
                    "href": "/pts/v2/payments/7435188899356405003091/reversals"
                },
                "self": {
                    "method": "GET",
                    "href": "/pts/v2/payments/7435188899356405003091"
                },
                "capture": {
                    "method": "POST",
                    "href": "/pts/v2/payments/7435188899356405003091/captures"
                }
            },
            "clientReferenceInformation": {
                "code": "1743518889914",
                "transactionId": "123456789ABCDEFGHIJKLMNOPQRST1"
            },
            "consumerAuthenticationInformation": {
                "token": "Axj/7wSTkw/5TqVCHfNTABEg1auGjlgybQ3FmNXmxaSiXV63TywFRLq9bp5ekDpxBPjhk23GVpz0tI7gTk5MP+U6lQh3zUwA0TVW"
            },
            "id": "7435188899356405003091",
            "orderInformation": {
                "amountDetails": {
                    "authorizedAmount": "100.00",
                    "currency": "USD"
                }
            },
            "paymentAccountInformation": {
                "card": {
                    "type": "001"
                }
            },
            "paymentInformation": {
                "tokenizedCard": {
                    "type": "001"
                },
                "scheme": "VISA DEBIT",
                "bin": "411111",
                "accountType": "Visa Classic",
                "issuer": "CONOTOXIA SP. Z O.O",
                "card": {
                    "type": "001"
                },
                "binCountry": "PL"
            },
            "pointOfSaleInformation": {
                "terminalId": "092940"
            },
            "processorInformation": {
                "merchantNumber": "000000012345678",
                "approvalCode": "888888",
                "networkTransactionId": "123456789619999",
                "transactionId": "123456789619999",
                "responseCode": "100",
                "avs": {
                    "code": "X",
                    "codeRaw": "I1"
                }
            },
            "reconciliationId": "55849026C8YFWMER",
            "riskInformation": {
                "localTime": "7:48:10",
                "score": {
                    "result": "0",
                    "factorCodes": [
                        "B",
                        "Q",
                        "Y"
                    ],
                    "modelUsed": "default"
                },
                "infoCodes": {
                    "address": [
                        "INTL-SA",
                        "MM-A",
                        "MM-BIN",
                        "MM-C",
                        "MM-CO",
                        "MM-ST",
                        "MM-Z",
                        "UNV-ADDR"
                    ],
                    "phone": [
                        "RISK-PH",
                        "UNV-OC"
                    ],
                    "globalVelocity": [
                        "VELV-SA"
                    ],
                    "suspicious": [
                        "INTL-BIN",
                        "RISK-SD"
                    ],
                    "identityChange": [
                        "MORPH-B",
                        "MORPH-P",
                        "MORPH-S"
                    ]
                },
                "profile": {
                    "earlyDecision": "ACCEPT",
                    "name": "Rob Demo",
                    "selectorRule": "Rob"
                },
                "casePriority": "1"
            },
            "status": "AUTHORIZED",
            "submitTimeUtc": "2025-04-01T14:48:11Z"
        },
        "id": "7435188899356405003091",
        "message": "Request processed successfully.",
        "outcome": "AUTHORIZED",
        "status": "AUTHORIZED"
    },
    "retryNumber": 0,
    "eventType": "uc.orders.transactionresults",
    "eventDate": "2025-03-27T08:44:55",
    "transactionTraceId": "62dbbee0-c722-4ee0-b60c-1c2a62aff90e"
}

Enable Digital Payments

To enable digital payments on Unified Checkout, you must first register for each digital payment method that you would like enabled on your page. This enablement process sends the appropriate information to the digital payment systems and registers your page with each system.

This section contains information about enabling and managing digital payments on Unified Checkout in the Business Center:

Apple Pay

Enrolling in Apple Pay

Preparing a device for testing Apple Pay on Unified Checkout

Click to Pay

Enabling Click to Pay

Google Pay

Enrolling in Google Pay

Managing Google Pay authentication types

Enrolling in Apple Pay

Apple Pay is a digital payment service that enables users to make secure and convenient transactions using their Apple devices. Users can add their credit or debit cards to the Wallet app and use them to pay online or in apps in a safe and convenient consumer experience.

To enable Apple Pay you must first host a public certificate on your web page and then pass your merchant name and domain name to Apple. Apple crawls out to your web page to validate the presence of this certificate to ensure the web pages are properly vetted and registered with Apple.

Follow these steps to validate your domain and enroll in Apple Pay:

Navigate to

Payment Configuration > Unified Checkout

.

In the Apple Pay section, click Set Up
.

Follow the link to download the certificate.

Upload the apple-developer-merchantid-domain-association
certificate file to your web server at:

/.well-known/apple-developer-merchantid-domain-association

You must verify that the file is accessible through HTTPS. You can validate this by visiting

https://<your-domain>/.well-known/apple-developer-merchantid-domain-association

.

Click

Verify Domain

.

Enter the domain name where you are hosting Apple Pay. This must be the same domain to which you uploaded the public certificate.

Your domain is now verified for Apple Pay.

AFTER COMPLETING THE TASK

IMPORTANT

In order to run an end-to-end test of the Apple Pay service on Unified Checkout, you must perform additional setup steps. See Preparing a Device for Testing Apple Pay on Unified Checkout.

Preparing a Device for Testing Apple Pay on `Unified Checkout`

In order to run an end-to-end test of the Apple Pay service on Unified Checkout, you must prepare an Apple test device by loading Apple Pay test cards onto the device.

Follow these steps to prepare your Apple test device for end-to-end testing:

Make sure your Apple Developer account is configured for Apple Pay.

Register your Apple Pay test device with Apple.

Load Apple Pay test cards onto your Apple test device.

ADDITIONAL INFORMATION

The Apple Developer center provides the instructions in the Sandbox Testing page for Apple Pay:

Follow the steps described in

Create a Sandbox Tester Account

.

Follow the steps described in

Adding a Test Card Number

.

Enabling `Click to Pay`

Click to Pay is a digital payment solution that allows customers to pay with their preferred card network and issuer without entering their card details on every website. Customers can use Visa, Mastercard, and American Express cards to streamline their purchase experience. Click to Pay provides a fast, secure, and consistent checkout experience across devices and browsers.

Follow these steps to enable in Click to Pay on Unified Checkout:

Navigate to

Payment Configuration > Unified Checkout

.

In the Click to Pay section, click Set Up
.

Enter your business name and website URL.

Click

Submit

.

Contact your implementation contact

or technical account manager

to request that you be enabled for tokenization within Click to Pay. Your implementation contact

or technical account manager

will confirm that you were configured successfully and that you can now accept digital payments with Click to Pay.

Set Up Customer Authentication for Visa

Follow these steps to use the Business Center to enable customer authentication through

Click to Pay

. Authentication methods differ in each region and are dependent on the issuer, the cardholder device, and the

Click to Pay

configuration. These authentication methods are available:

3-D Secure

FIDO

Card verification value (CVV)

One-time password (OTP)

IMPORTANT

After you complete these steps, Visa determines which authentication method to use. When Visa determines that they will authenticate, they authenticate each

Click to Pay

transaction through the appropriate method. This may be a frictionless authentication or the customer may need to provide more information when required by the issuer.

Log in to the Business Center:

Test URL:

https://businesscentertest.visaacceptance.com/ebc2

Production URL:

https://businesscenter.visaacceptance.com/ebc2

If you are unable to access this page, contact your sales representative.

In the Business Center, go to the left navigation panel and choose Payment Configuration
> Unified Checkout
.

You must have

Click to Pay

enabled as a digital payment method in order to use this method of authentication. Click Manage
to view the digital payment methods that you have enabled.

If

Click to Pay

is not enabled, click On
next to

Click to Pay

.

Manage Available Digital Payments Solutions

Click Set up
under Value Added Solutions. The Value Added Solutions page appears.

Click Set up
to set up 3-D Secure. The 3DS page appears.

Enter the required information in the Merchant Details section. You must enter the information that is provided to you by

your acquirer or processor

.

Step Result

This completes the authentication setup for the entered acquirer merchant ID and BIN. If you do not know what these values are, you must contact

your acquirer

. Completing this information enables Visa Acceptance Solutions to send Visa the information that is required for authentication.

IMPORTANT

Charges for 3-D Secure may apply. You must speak with

your acquirer

for more information about the charges associated with 3-D Secure.

Enrolling in Google Pay

Google Pay is a digital payment product offered by Google through Chrome browsers and Android devices.

Follow these steps to enroll in Google Pay on Unified Checkout:

Navigate to

Payment Configuration > Unified Checkout

.

In the Google Pay section, click Set Up
.

Enter your business name.

Click

Submit

.

You can now accept digital payments with Google Pay.

AFTER COMPLETING THE TASK

IMPORTANT

When you enable Google Pay on Unified Checkout, you can specify an optional parameter that defines the types of credentials that Google Pay sends you. See Managing Google Pay Authentication Types.

Managing Google Pay Authentication Types

Additional controls are available for Google Pay on Unified Checkout. When you enable Google Pay on Unified Checkout, you can specify optional parameters that define the types of card authentication you receive from Google Pay.

To manage the types of credentials that Google Pay sends, use this expanded payment type object within the

allowedPaymentTypes

section of the sessions request:

{
  "type": "GOOGLEPAY",
  "options": { "allowedAuthMethods": "<authentication type>"
  }
}

The expanded payment type object has these parameters:

type

: Defines the type of payment option.

options

: Contains specific payment types parameters.

For Google Pay, use the new data element

allowedAuthMethods

within the

options

section of the payment types object to specify the authentication type you will receive from Google Pay. Possible values:

PAN_ONLY

: Google returns primary account number (PAN) values

CRYPTOGRAM_3DS

: Google returns fully authenticated network token values.

By default, Google sends both authentication types.

REST Example: Specify Only PAN Authentication Accepted from Google

This sessions request example specifies that Google Pay is to send only PAN values.

"allowedPaymentTypes": [
  "PANENTRY" {
    "type": "GOOGLEPAY",
    "options": {
      "allowedAuthMethods": "PAN_ONLY"
    }
  },
  "CLICKTOPAY",
  "PAZE"
]

REST Example: Simple Google Pay Request

This sessions request example specifies that Google Pay can send all authentication types.

"allowedPaymentTypes": [
  "PANENTRY",
  "GOOGLEPAY",
  "CLICKTOPAY",
  "PAZE",
  "CHECK"
]

Enrolling in Echeck/ACH Services

Unified Checkout can accept bank account payments using the eCheck product. To accept eCheck payments through Unified Checkout, you must have the eCheck processing service enabled. To request access to eCheck processing and enable eCheck, you must submit an application in the Business Center. Once your application is approved, you can accept eCheck payments.

For step-by-step instructions on enrolling and enabling eCheck, see the “Getting Started with the eCheck Service” section of the eCheck Merchant Guide
. If eCheck is not listed in the Available Products section in the Business Center, you must contact your portfolio owner to enable your account to apply for eCheck.

For more information, see the "Enabling the eCheck Service During Boarding” section of the eCheck Partner Guide
.

IMPORTANT

If you have a business account or a financial relationship with Bank of America, Wells Fargo, or Chase, and you would like them to process your transactions, you must contact our Sales or Support team for more information on our ACH product.

Manage Permissions

Portfolio administrators

can set permissions for new or existing Business Center user roles for Unified Checkout. Administrators retain full read and write permissions. They enable you to regulate access to specific pages and specify who can access, view, or amend digital products within Unified Checkout.

Portfolio administrators

must apply the appropriate user role permission for any existing or newly created Business Center user roles for Unified Checkout.

For information on managing permissions as a portfolio administrator, see Managing Permissions as a Portfolio Administrator.

If you are a transacting merchant, you might find that your permissions are restricted. If your permissions are restricted, a message appears indicating that you do not have access, or buttons might appear gray. To make changes to your digital products within Unified Checkout that have restricted permissions, contact

your portfolio administrator's customer support representative

.

For more information, see Managing Permissions as a Direct Merchant.

Managing Permissions as a Direct Merchant

Follow these steps to configure and manage user permissions in the Business Center for Unified Checkout as a direct merchant:

On the left navigation panel, navigate to

Account Management

.

Click

Roles

to display a list of your user roles.

Click the pencil icon next to the user role that you want to update.

Click

Payment Configuration Permission

.

Select the relevant permission for the specific user role you are editing. You can select from these Unified Checkout permissions:

Unified Checkout View

Unified Checkout Manage

IMPORTANT

If you are a transacting merchant without view permissions, Unified Checkout will still appear on the navigation bar, however, a no access
message appears when you access Unified Checkout.

If you are a transacting merchant with view permissions but not management permissions, you can access the Unified Checkout screens and view the different payment methods configurations, however, you cannot edit or enroll new products.

Managing Permissions as
a Portfolio Administrator

Follow these steps to configure and manage user permissions in the Business Center for Unified Checkout as a portfolio administrator:

On the left navigation panel, navigate to

Account Management

.

Click

Roles

to see a list of your user roles.

Click the pencil icon next to the user role that you want to update.

Click

Payment Configuration Permission

.

Select the relevant permission for the specific user role you are editing. You can choose from these Unified Checkout permissions:

Unified Checkout View

Unified Checkout Manage

Unified Checkout Portfolio View (available for portfolio users only)

Unified Checkout Portfolio Manage (available for portfolio users only)

IMPORTANT

If all permissions are left unselected, the user has restricted permission. A no access
message appears when the user tries to access the Unified Checkout digital product enablement pages. The user is advised to contact a customer representative.

If a portfolio user has view permissions and does not have a management role, they can access the Unified Checkout pages, but they cannot modify toggles for different digital payments.

Test Your `Unified Checkout` Configuration

This section contains information about testing your Unified Checkout configuration.

Test Payment Details

Use these test card numbers to test your Unified Checkout configuration.

Combine the BIN with the card number when sending to Unified Checkout.

`Unified Checkout` Test Cards

Test Card Numbers
Card Brand	BIN	Card Number	Expiration Date	CVV
Visa	411111	1111111111	12/2025	123
Mastercard	555555	5555554444	02/2026	265
American Express	378282	246310005	03/2026	7890
Cartes Bancaires	436000	0001000005	04/2040	123
Carnet	506221	0000000009	04/2024	123
China UnionPay	627988	6248094966	04/2040	123
Diners Club	305693	09025904	04/2040	123
Discover	644564	4564456445	04/2040	123
JCB	353011	13333 0000	04/2040	123
Maestro	675964	9826438453	04/2040	123
mada	446404	0000000007	04/2040	123
ELO	451416	0000000003	04/2040	123
JCrew	515997	1500000005	04/2040	123
EFTPOS	401795	000000000009	04/2040	123
Meeza	507808	3000000002	04/2040	123

Visa `Click to Pay` Test Cards

These Visa test cards can be added to your Click to Pay wallet. Replace the X in the card number with 0.

You can manage your Visa Click to Pay test cards and account here:

Production:
https://secure.checkout.visa.com

Test:
https://sandbox.secure.checkout.visa.com

To manage Visa test cards for customer authentication, contact your implementation consultant or technical account manager.

IMPORTANT

These test cards are not valid for testing in production. To test in production, you must leverage production credentials.

Visa Test Card Numbers
Card Number	Expiration Date	CVV
46229431231X2700	12/2026	938
46229431231X2718	12/2026	605
46229431231X2726	12/2026	579
46229431231X2734	12/2026	141
46229431231X2742	12/2026	279
46229431231X2759	12/2026	669

Mastercard `Click to Pay` Test Cards

Mastercard test cards can be added to your Click to Pay wallet. You must retrieve Mastercard test cards from their Click to Pay test page: #test-cards

Mastercard has different test cards for retrieving tokenized and non-tokenized data. Visa Acceptance Solutions recommends that you use these test cards as follows:

Test cards to retrieve PAN data: Use these cards when the customer is completing checkout as a one-time guest and does not have a Click to Pay account or want to create one.

Test cards to retrieve token data: Use these cards for tokenized Click to Pay transactions.

You can manage your Mastercard Click to Pay test cards and account here:

Live:
enroll

SBX:
enroll

To manage Mastercard test cards for customer authentication, contact your implementation consultant or technical account manager.

Echeck Test Values

These eCheck test values can be used to process a test eCheck transactions:

Routing number:
Set to 071923284

Account number:
Set to any supported value. For example, 1234567890.

Customer Authentication

When you enable customer authentication through

Click to Pay

, you give Visa Acceptance Solutions permission to send Visa the required authentication information for each transaction.

Click to Pay

authentication is only available for Visa branded cards that are tokenized with

Click to Pay

. If

Click to Pay

does not authenticate the transaction then you must authenticate it using another authentication method outside of

Click to Pay

, if required.

IMPORTANT

American Express or Mastercard card brands cannot be authenticated through

Click to Pay

. You must use another authentication method.

When the customer completes a transaction using a Visa card that is already stored in

Click to Pay

, authentication is managed with

Click to Pay

. When the customer checks out using manual card entry and does not save their card to

Click to Pay

, the transaction is not processed through

Click to Pay

and you must complete authentication based on your existing authentication method.

Visa Prerequisites

Before you can begin customer authentication using

Click to Pay

, you must meet these requirements:

The

allowPaymentTypes

field must include

CLICKTOPAY

in the capture context.

For more information, see Capture Context.

The transacting merchant ID that sends the transaction requests must be configured for tokenization with

Click to Pay

. You must contact your implementation consultant or technical account manager to configure tokenization with

Click to Pay

.

Set up Visa customer authentication in the Business Center. For more information, see Set Up Customer Authentication for Visa.

Authentication Flow

Payment Methods

This section describes the payment methods you can use in your Unified Checkout integration. After you successfully integrate one payment method, you can add another from the same category with minimal adjustments to your existing configuration.

Cards

Unified Checkout accepts several card types including global networks such as Visa, Mastercard, and American Express. Unified Checkout also accepts local schemes such as Cartes Bancaires in France, EFTPOS in Australia, and PayPak in Pakistan.

Card Support

Support for card brands varies based on the payment method for these services:

Payments

Decision Manager

Payer Authentication

This table shows which card types are accepted for each payment method and which region:

Card Brand by Region and Payment Method
Region	Card Brand	Manual Card Entry	Apple Pay	`Click to Pay`	Google Pay	Paze
Asia Pacific	China UnionPay
Asia Pacific	EFTPOS
Asia Pacific	JCB
CEMEA	mada
CEMEA	Meeza
CEMEA	PayPak
Europe	Cartes Bancaires
Global	American Express
Global	Diners Club
Global	Mastercard
Global	Visa
Global and Europe	Maestro
Latin America	Carnet
Latin America	ELO
US and Canada	Discover
US and Canada	JCrew

`Unified Checkout` Appendix

`Unified Checkout` UI

Completing a payment with Unified Checkout requires the customer to navigate through a sequence of interfaces. This section includes examples of the interfaces your customers can expect when completing a payment with these payment methods on Unified Checkout:

Apple Pay

Click to Pay

Google Pay

Manual payment entry

Payment with a bank account

Paze

Apple Pay UI

These screen captures show the sequence of events your customer can expect when completing a payment with Apple Pay.

`Click to Pay` UI

These screen captures show the sequence of events your customer can expect when completing a payment with Click to Pay.

Google Pay UI

These screen captures show the sequence of events your customer can expect when completing a payment with Google Pay.

Manual Payment Entry UI

These screen captures show the sequence of events your customer can expect when completing a payment by manually entering payment, shipping, and contact information.

Pay with Bank Account UI

These screen captures show the sequence of events your customer can expect when completing a payment with a bank account.

Pay with Bank Account Review and Confirm

Pay with Bank Account Review and Confirm Disclaimer

Paze UI

These screen captures show the sequence of events your customer can expect when completing a payment with Paze.

JSON Web Tokens

JSON Web Tokens (JWTs) are digitally signed JSON objects based on the open standard RFC 7519. These tokens provide a compact, self-contained method for securely transmitting information between parties. These tokens are signed with an RSA-encoded public/private key pair. The signature is calculated using the header and body, which enables the receiver to validate that the content has not been tampered with.

A JWT takes the form of a string, and consists of three parts separated by dots:

<Header>.<Payload>.<Signature>

The header and payload is Base64-encoded JSON
and contains these claims:

Header
: The algorithm and token type. For example:

{
  "kid": "zu",
  "alg": "RS256"
}

Payload
: The claims of what the token represents. For example:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Signature
: The signature is computed from the header and payload using a secret or private key.

IMPORTANT

When working with JWTs, Visa Acceptance Solutions recommends that you use a well- maintained JWT library to ensure proper decoding and parsing of the JWT.

IMPORTANT

When parsing the JWT’s JSON payload, you must ensure that you implement a robust solution for transversing JSON. Additional elements can be added to the JSON in future releases. Follow JSON parsing best practices to ensure that you can handle the addition of new data elements in the future.

`Unified Checkout` Examples

This section contains the information you need in order to integrate Unified Checkout within your e-commerce experience and use the

unifiedPayment.complete()

method.

`Unified Checkout` with Authorization

This section contains the capture context and JavaScript examples to integrate Unified Checkout into your e-commerce page. You can use these examples to collect your customer's payment information and process an authorization. You must initiate a capture request to move funds and complete the transaction.

For information on the capture context, see Capture Context API.

Example: `Unified Checkout` with Authorization

Capture Context Request

{
  "clientVersion": "0.26",
  "targetOrigins": [
    "https://yourCheckoutPage.com"
  ],
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "APPLEPAY",
    "CLICKTOPAY",
    "GOOGLEPAY",
    "PAZE"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    }
  },
  "completeMandate": {
    "type": "AUTH"
  }
}

JavaScript

<script type="text/javascript">
    const sidebar = true;
    const captureContext = document.getElementById("captureContext").value;
    const showArgs = {
      containers: { paymentSelection: "#buttonPaymentListContainer" }
    };
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        const completeResponse = await up.complete(tt);
    
        console.log(completeResponse); // merchant logic for handling complete response
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }

    // Call the function
    launchCheckout();
  </script>

`Unified Checkout` with Sale

This section contains the capture context and JavaScript examples to integrate Unified Checkout into your e-commerce page. You can use these examples to collect your customer's payment information and process a sale.

For information on the capture context, see Capture Context API.

Example: `Unified Checkout` with Sale

Capture Context Request

{
  "clientVersion": "0.26",
  "targetOrigins": [
    "https://yourCheckoutPage.com"
  ],
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "APPLEPAY",
    "CLICKTOPAY",
    "GOOGLEPAY",
    "PAZE"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    }
  },
  "completeMandate": {
    "type": " CAPTURE"
  }
}

JavaScript

<script type="text/javascript">
    const sidebar = true;
    const captureContext = document.getElementById("captureContext").value;
    const showArgs = {
      containers: { paymentSelection: "#buttonPaymentListContainer" }
    };
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        const completeResponse = await up.complete(tt);
    
        console.log(completeResponse); // merchant logic for handling complete response
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }

    // Call the function
    launchCheckout();
  </script>

`Unified Checkout` with Sale and `Decision Manager`

This section contains the capture context and JavaScript examples to integrate Unified Checkout into your e-commerce page. You can use these examples to collect your customer's payment information and process a sale while also invoking the Decision Manager fraud solution. Before the sale is initiated, Decision Manager is invoked for fraud screening.

For information on the capture context, see Capture Context API.

Example: `Unified Checkout` with Sale and `Decision Manager`

Capture Context Request

{
  "clientVersion": "0.26",
  "targetOrigins": [
    "https://yourCheckoutPage.com"
  ],
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "APPLEPAY",
    "CLICKTOPAY",
    "GOOGLEPAY",
    "PAZE"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    }
  },
  "completeMandate": {
    "type": " CAPTURE",
    "decisionManager": true
  }
}

JavaScript

<script type="text/javascript">
    const sidebar = true;
    const captureContext = document.getElementById("captureContext").value;
    const showArgs = {
      containers: { paymentSelection: "#buttonPaymentListContainer" }
    };
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        const completeResponse = await up.complete(tt);
    
        console.log(completeResponse); // merchant logic for handling complete response
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }

    // Call the function
    launchCheckout();
  </script>

`Unified Checkout` without Service Orchestration

This section contains the capture context and JavaScript examples to integrate Unified Checkout into your e-commerce page. You can use these examples to collect your customer's payment information. Payment processing and service orchestration are completed through the back end of the integrator.

For information on the capture context, see Capture Context API.

Example: `Unified Checkout` without Service Orchestration

Capture Context Request

{
  "clientVersion": "0.26",
  "targetOrigins": [
    "https://yourCheckoutPage.com"
  ],
  "allowedCardNetworks": [
    "VISA",
    "MASTERCARD",
    "AMEX"
  ],
  "allowedPaymentTypes": [
    "APPLEPAY",
    "CLICKTOPAY",
    "GOOGLEPAY",
    "PAZE"
  ],
  "country": "US",
  "locale": "en_US",
  "captureMandate": {
    "billingType": "FULL",
    "requestEmail": true,
    "requestPhone": true,
    "requestShipping": true,
    "shipToCountries": [
      "US",
      "GB"
    ],
    "showAcceptedNetworkIcons": true
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "21.00",
      "currency": "USD"
    }
  }
}

JavaScript

<script type="text/javascript">
    const sidebar = true;
    const captureContext = document.getElementById("captureContext").value;
    const showArgs = {
      containers: { paymentSelection: "#buttonPaymentListContainer" }
    };
    
    async function launchCheckout() {
      try {
        const accept = await Accept(captureContext);
        const up = await accept.unifiedPayments(sidebar);
        const tt = await up.show(showArgs);
        console.log(tt); // merchant logic for passing the Transient token to their backend for service orchestration
      } catch (error) {
        // merchant logic for handling issues
        console.error("something went wrong: " + error);
      }
    }
    // Call the function
    launchCheckout();
  </script>

Echeck Payment with a Transient Token

This section contains a request example for making a payment with an eCheck using a transient token. You must meet these requirements to make an eCheck payment with a transient token:

The

paymentType.name.value

field value must be set to

CHECK

in the transient token.

You must include the

paymentInformation.paymentType.name

field in your request and the value must be set to

CHECK

in your request.

Example: Echeck Payment with a Transient Token

Echeck Payment Request with a Transient Token

{
  "clientReferenceInformation" : {
    "code" : "tt-1745987284021"
  },
  "orderInformation" : {
    "amountDetails" : {
      "totalAmount" : "289.99",
      "currency" : "USD"
    }
  },
  "tokenInformation" : {
    "transientTokenJwt" : "eyJraWQiOiIwODV4cWN4TWdWRldxdFdnWXBPcElCcENTRGlzb0VkcCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJGbGV4LzA3IiwiZXhwIjoxNzQ1OTg4MTgzLCJ0eXBlIjoiZ2RhLTAuMTAuMCIsImlhdCI6MTc0NTk4NzI4MywianRpIjoiMUUxQ0VJSFVVMDVESTlaNTJWWUw0S1hJVUtSQkJTUFUzT0JGN05aNDA4MEFTNzdCWTZVNjY4MTFBQTU3N0E0QSIsImNvbnRlbnQiOnsib3JkZXJJbmZvcm1hdGlvbiI6eyJiaWxsVG8iOnsibGFzdE5hbWUiOnt9LCJmaXJzdE5hbWUiOnt9LCJjb3VudHJ5Ijp7fSwicGhvbmVOdW1iZXIiOnt9LCJhZGRyZXNzMSI6e30sInBvc3RhbENvZGUiOnt9LCJsb2NhbGl0eSI6e30sImJ1aWxkaW5nTnVtYmVyIjp7fSwiYWRtaW5pc3RyYXRpdmVBcmVhIjp7fSwiZW1haWwiOnt9fSwiYW1vdW50RGV0YWlscyI6eyJ0b3RhbEFtb3VudCI6e30sImN1cnJlbmN5Ijp7fX0sInNoaXBUbyI6eyJsYXN0TmFtZSI6e30sImZpcnN0TmFtZSI6e30sImNvdW50cnkiOnt9LCJhZGRyZXNzMSI6e30sInBvc3RhbENvZGUiOnt9LCJsb2NhbGl0eSI6e30sImJ1aWxkaW5nTnVtYmVyIjp7fSwiYWRtaW5pc3RyYXRpdmVBcmVhIjp7fX19LCJwYXltZW50SW5mb3JtYXRpb24iOnsiYmFuayI6eyJyb3V0aW5nTnVtYmVyIjp7fSwiYWNjb3VudCI6eyJudW1iZXIiOnt9LCJ0eXBlIjp7fX19LCJwYXltZW50VHlwZSI6eyJuYW1lIjp7InZhbHVlIjoiQ0hFQ0sifX19fX0.SmkkDRm9yTYIUnL2R-HslqKQe0CCqm4HVFiGP78WQAE4mMkjwkd6Gu9_T0AvEcuBOTaYQUVofXmILvxlj2T_Yg8hD41LFBof32UlVeo8Wf0qF28cEnTnAXJExDVbxsJnJYTEH9iNwl_8_BTerNy0FzFVcQXJ55jBfdbJ0IeEuG685Wkc2U7Xw_nIgooL544qYmlTGx0Myjf3JVF4WVpM55HfebzDubvbTMMabhC9tA-pWSZOoC_YQcQaipr9gT1CEAeYA39ODQiHhS7EsPKITdTUmmkWqWuZ_HqFS8i8wvKr-HJ1CY0xAhEp7TzeLAxWixuLS00tTDKFZgx7obqA6g"
  },
  "processingInformation" : {
    "bankTransferOptions" : {
      "secCode" : "WEB"
    }
  },
  "paymentInformation" : {
    "paymentType" : {
      "name" : "CHECK"
    }
  }
}

Supported Countries for Digital Payments

Apple Pay, Click to Pay, eCheck, Google Pay, and Paze are supported in different countries.

See these topics for the lists of the countries that support digital payments:

Supported Countries for Digital Payments A-D

Supported Countries for Digital Payments E-K

Supported Countries for Digital Payments L-R

Supported Countries for Digital Payments S-Z

Supported Countries for Digital Payments A-D

Supported Countries (A through D)
Country	Apple Pay	`Click to Pay`	eCheck	Google Pay
Afghanistan
Albania
Algeria
Andorra
Angola
Antigua and Barbuda
Argentina
Armenia
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgium
Brazil
Belize
Benin
Bhutan
Bolivia
Bosnia and Herzegovina
Botswana
Brunei Darussalam
Bulgaria
Burkina Faso
Burundi
Cambodia
Cameroon
Canada
Cape Verde
Central African Republic
Chad
Chile
China
Colombia
Comoros
Costa Rica
Côte d'Ivoire
Croatia
Cyprus
Czech Republic
Democratic Republic of the Congo
Denmark
Djibouti
Dominica
Dominican Republic

Supported Countries for Digital Payments E-K

Supported Countries (E through K)
Country	Apple Pay	`Click to Pay`	Google Pay
Ecuador
Egypt
El Salvador
Equatorial Guinea
Eritrea
Estonia
Eswatini
Ethiopia
Faroe Islands
Fiji
Finland
France
Gabon
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Guernsey
Grenada
Guatemala
Guinea
Guinea-Bissau
Guyana
Haiti
Honduras
Hong Kong
Hungary
Iceland
India
Indonesia
Iraq
Ireland
Isle of Man
Israel
Italy
Jamaica
Japan
Jersey
Jordan
Kazakhstan
Kenya
Kiribati
Kuwait
Kyrgyzstan

Supported Countries for Digital Payments L-R

Supported Countries (L through R)
Country	Apple Pay	`Click to Pay`	Google Pay
Laos
Latvia
Lebanon
Lesotho
Liberia
Libya
Liechtenstein
Lithuania
Luxembourg
Macau
Madagascar
Malawi
Malaysia
Maldives
Mali
Malta
Marshall Islands
Mauritania
Mauritius
Mexico
Micronesia, Federated States of
Moldova
Monaco
Mongolia
Montenegro
Morocco
Mozambique
Myanmar
Namibia
Nauru
Nepal
Netherlands
New Zealand
Nicaragua
Niger
Nigeria
North Macedonia
Norway
Oman
Pakistan
Palau
Palestinian Territories
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Poland
Portugal
Qatar
Republic of the Congo
Romania
Rwanda

Supported Countries for Digital Payments S-Z

Supported Countries (S through Z)
Country	Apple Pay	`Click to Pay`	eCheck	Google Pay	Paze
Saint Kitts and Nevis
Saint Lucia
Saint Vincent and the Grenadines
Samoa
San Marino
Sao Tome and Principe
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Singapore
Slovakia
Slovenia
Solomon Islands
Somalia
South Africa
Korea, Republic of (South)
South Sudan
Spain
Sri Lanka
Sudan
Suriname
Sweden
Switzerland
Switzerland -Italian
Taiwan
Tajikistan
Tanzania
Thailand
Timor-Leste
Togo
Tonga
Trinidad and Tobago
Tunisia
Turkey
Turkmenistan
Tuvalu
Uganda
Ukraine
United Arab Emirates
United Kingdom
United States
Uruguay
Uzbekistan
Vanuatu
Vatican City (Holy See)
Venezuela
Vietnam
Yemen
Zambia
Zimbabwe

Supported Locales

The locale field within the capture context request consists of an ISO 639 language code, an underscore (_), and an ISO 3166 region code. The locale controls the language in which the application is rendered. The following locales are supported:

ar_AE

bg_BG

ca_ES

cs_CZ

da_DK

de_AT

de_DE

el_GR

en_AU

en_CA

en_GB

en_IE

en_NZ

en_US

es_AR

es_CL

es_CO

es_ES

es_MX

es_PE

es_US

fi_FI

fr_CA

fr_FR

he_IL

hr_HR

hu_HU

id_ID

it_IT

ja_JP

km_KH

ko_KR

lo_LA

ms_MY

nb_NO

nl_NL

pl_PL

pt_BR

ro_RO

ru_RU

sk_SK

sl_SI

sv_SE

th_TH

tl_PH

tr_TR

vi_VN

zh_CN

zh_HK

zh_MO

zh_SG

zh_TW

Reason Codes

A Unified Checkout request response returns one of the following reason codes:

Reason Codes
Reason Code	Description
200	Successful response.
201	Capture context created.
400	Bad request. Possible reason values: CAPTURE_CONTEXT_EXPIRED CAPTURE_CONTEXT_INVALID CREATE_TOKEN_TIMEOUT CREATE_TOKEN_XHR_ERROR INVALID_APIKEY SDK_XHR_ERROR SHOW_LOAD_CONTAINER_SELECTOR SHOW_LOAD_INVALID_CONTAINER SHOW_PAYMENT_TIMEOUT SHOW_TOKEN_TIMEOUT SHOW_TOKEN_XHR_ERROR UNIFIEDPAYMENT_PAYMENT_PARAMITERS UNIFIEDPAYMENTS_VALIDATION_FIELDS UNIFIEDPAYMENTS_VALIDATION_PARAMS
404	The specified resource not found in the system.
500	Unexpected server error.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through

Visa Acceptance platform

. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.

Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.

Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.

Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.

Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.

DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE

Visa Platform Connect

ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT

Visa Platform Connect

ACQUIRER.

Unified Checkout Developer Guide

Recent Revisions to This Document

25.08.02

25.08.01

25.05.01

25.03.02

25.03.01

25.02.01

25.01.01

24.12.01

24.10.01

24.09.01

Introduction to Unified Checkout

Figure:

Unified Checkout Flow

Figure:

Enabling Unified Checkout in the Business Center

Figure:

Server-Side Set Up

Capture Context

Figure:

Client-Side Set Up

Loading the JavaScript Library and Invoking the Accept Function

JavaScript Example: Initializing the SDK

JavaScript Example: Displaying the Button List

JavaScript Example: Client-Defined Trigger for Click to Pay or PAN Entry

JavaScript Example: Processing a Payment

Complete Integration Examples

JavaScript Example: Setting Up with Full Sidebar

JavaScript Example: Setting Up with the Embedded Component

Transient Tokens

Transient Token Format

Example: Transient Token Format

Token Verification

Dual-Branded Cards

Authorizations with a Transient Token

Endpoint

Required Field for an Authorization with a Transient Token

REST Example: Requesting an Authorization with a Transient Token

Capture Context API

Features

Client Version History

Requesting the Capture Context

Endpoint

Required Fields for Requesting the Capture Context

REST Example: Requesting the Capture Context

Validating the Capture Context

Payment Details API

Endpoint

REST Example: Retrieving Transient Token Payment Details

JavaScript API Reference

Class: Accept

Accept

Methods

Class: AcceptError

AcceptError

Members

Class: UnifiedPayments

UnifiedPayments

Methods

Type Definitions

Unified Checkout Configuration

Webhooks Support

Enable Digital Payments

Enrolling in Apple Pay

AFTER COMPLETING THE TASK

Preparing a Device for Testing Apple Pay on Unified Checkout

ADDITIONAL INFORMATION

Enabling Click to Pay

Set Up Customer Authentication for Visa

Step Result

Enrolling in Google Pay

AFTER COMPLETING THE TASK

Managing Google Pay Authentication Types

Enrolling in Echeck/ACH Services

Manage Permissions

Managing Permissions as a Direct Merchant

Managing Permissions as a Portfolio Administrator

Test Your Unified Checkout Configuration

Test Payment Details

`Unified Checkout` Developer Guide

Introduction to `Unified Checkout`

`Unified Checkout` Flow

Enabling `Unified Checkout` in the `Business Center`

JavaScript Example: Client-Defined Trigger for `Click to Pay` or PAN Entry

`Unified Checkout` Configuration

Preparing a Device for Testing Apple Pay on `Unified Checkout`

Enabling `Click to Pay`

Managing Permissions as
a Portfolio Administrator

Test Your `Unified Checkout` Configuration

`Unified Checkout` Test Cards

Visa `Click to Pay` Test Cards

Mastercard `Click to Pay` Test Cards

`Unified Checkout` Appendix

`Unified Checkout` UI

`Click to Pay` UI

`Unified Checkout` Examples

`Unified Checkout` with Authorization

Example: `Unified Checkout` with Authorization

`Unified Checkout` with Sale

Example: `Unified Checkout` with Sale

`Unified Checkout` with Sale and `Decision Manager`

Example: `Unified Checkout` with Sale and `Decision Manager`

`Unified Checkout` without Service Orchestration

Example: `Unified Checkout` without Service Orchestration