Updated the list of supported countries to include Bulgaria, Greece, Japan, Romania,
Slovenia, Thailand, and Vietnam. See Supported Countries for Click to Pay.
Updated the capture context request sections to include the most recent client version
and allowed payment types. See Capture Context and Capture Context API.
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.
Introduction to
the
Click to Pay Drop-In UI
The
Click to Pay Drop-In UI
powered by
Unified Checkout
provides an interface for easy acceptance of
Click to Pay
payments from Visa, Mastercard, and American Express cards.
The
Click to Pay Drop-In UI
handles manual card entry
for the non-
Click to Pay
payment schemes called out in this guide.
Throughout this guide we refer to both
Click to Pay Drop-In UI
and
Unified Checkout
.
Click to Pay Drop-In UI
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 used 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 into your e-commerce
page.
The provided JavaScript library enables you to place a payment application within your
e-commerce environment. This embedded component offers
Click to Pay
and card entry to your customers.
Whether a customer uses a stored
Click to Pay
card or enters their
payment information manually,
the
Click to Pay Drop-In UI
handles all user interactions and provides a
response to your e-commerce system. All UI / UX must follow the UI/UX guidelines. For
information about configuring your UI/UX, see Click to Pay UI Examples.
The
Click to Pay Drop-In UI
enables a portfolio to
receive an encrypted payload and send a request to the API to retrieve the payment
details. The format of the decrypted payment details are determined by the transaction
type. The details are either a network token and cryptogram or the PAN, expiration
details, and card verification value (CVV).
The figure below shows the
Click to Pay Drop-In UI
for a recognized user.
Figure:
Embedded Component
IMPORTANT
Each request that you send to
Visa Acceptance Solutions
requires header information. For information about constructing the headers for your
request, see the
is designed to provide customers with a
friction-free payment experience across many payment experiences. The user experience
has been optimized for mobile use and performs equally well on mobile and desktop
devices.
Click to Pay
recognizes customers as follows:
The customer is a recognized
Click to Pay
customer.
The customer is not recognized but is a
Click to Pay
customer.
The customer is a guest at checkout.
These workflows show you the pages a customer encounters based on their status:
recognized
experience. This interaction occurs when a customer’s device is recognized by the
Click to Pay Drop-In UI
.
A customer's device is recognized under these conditions:
When the customer has used
Click to Pay
on their device
through any
Click to Pay
channel.
If the customer chose to have their device remembered during a previous
transaction or when they enter their one-time password (OTP).
The cardholder is presented with their stored
Click to Pay
cards
in the UI when they are on a recognized device:
Figure:
Recognized
Click to Pay
Customer UI
Unrecognized
Click to Pay
Customer
This section provides an overview of the
Click to Pay Drop-In UI
unrecognized
experience. This interaction occurs when a customer's device is not recognized by the
Click to Pay Drop-In UI
. This condition occurs when the customer has a
Click to Pay
account but has not opted to have their details
stored on the device. In this flow, the customer receives an OTP on their registered
mobile device or their email address.
When the cardholder has a
Click to Pay
account but is not on a
registered device, they receive a one-time password to their registered email address
and phone number to authenticate their identity before their stored
Click to Pay
credentials are shown:
Figure:
Unrecognized
Click to Pay
Customer on a Recognized Device
UI
Guest Customer
This section provides an overview of the
Click to Pay Drop-In UI
guest
experience. This interaction occurs when the customer has not created a
Click to Pay
account, or their issuer has not provisioned their card into
Click to Pay
.
In the guest experience,
Click to Pay Drop-In UI
captures the PAN details and the
cardholder chooses to create a
Click to Pay
account or to check out
as a guest. In both cases, the payment credentials are available for processing
transactions using your payment gateway.
When the cardholder does not have a
Click to Pay
account, they can
provide a new email address to perform a new lookup or they can choose to enter their
card details manually. The cardholder can make a one-time payment or complete the
payment and choose to create a
Click to Pay
account for future use:
Figure:
Guest UI
Click to Pay Drop-In UI
Flow
To integrate the
Click to Pay Drop-In UI
into your platform, you must follow
several integration steps. This section gives a high-level overview of how to
integrate and launch
Click to Pay Drop-In UI
on your webpage and process a
transaction. You can find the detailed specifications of the APIs later in this
document.
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 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 use the response from
the
Click to Pay Drop-In UI
to retrieve
payment credentials for payment processing or other steps.
This figure illustrates the system's payment flow.
Figure:
Click to Pay
Payment Flow
For more information on the specific APIs referenced, see these topics:
This section contains the information you need to set up your server. Initializing
Click to Pay Drop-In UI
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 the
Click to Pay Drop-In UI
performs.
The server-side component provides this information:
A transaction-specific public key that 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 interaction methods.
The functions are compiled in a JSON Web Token (JWT) object referred to as the
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
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
Use the
targetOrigins
and the
allowedPaymentTypes
fields to define the target origin and the accepted digital payment methods in your capture
context. For example:
This diagram shows how elements of the capture context request appear in the card entry
form.
Figure:
Anatomy of a Manual Card Entry Form
For more information on requesting the capture context, see Capture Context API.
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 integrate with your e-commerce
website. 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 integrate the payment acceptance page with your webpage or add it as a
sidebar.
The
Unified Checkout
JavaScript library supports
Click to Pay
and manual card entry payment methods.
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.
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
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 display
CLICKTOPAY
or
PANENTRY
as allowed
payment types, you can load the UI without displaying the
Unified Checkout
checkout button. You can do this by creating a trigger
that defines what event 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. This is required.
The container for the payment screen. It is required when you are in
embedded mode.
IMPORTANT
You can create a trigger only for
CLICKTOPAY
or
PANENTRY
payment
methods.
// 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);
})
Adding the Payment Application and Payment Acceptance
After you initialize the
Unified Checkout
object, you can add the payment
application and payment acceptance pages to your webpage. You can attach the
Unified Checkout
embedded tool and payment acceptance pages to any named
element within your HTML. Typically, they are attached to explicit named
<div>
components that are replaced with
Click to Pay Drop-In UI
iframes
.
IMPORTANT
If you do not specify a location for the payment acceptance page, it
is placed in the sidebar.
JavaScript Example: Setting Up with Full Sidebar
var authForm = document.getElementById("authForm");
var transientToken = document.getElementById("transientToken");
var cc = document.getElementById("captureContext").value;
var showArgs = {
containers: {
paymentSelection: "#buttonPaymentListContainer"
}
};
Accept(cc)
.then(function(accept) {
return accept.unifiedPayments();
})
.then(function(up) {
return up.show(showArgs);
})
.then(function(tt) {
transientToken.value = tt;
authForm.submit();
});
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.
var authForm = document.getElementById("authForm");
var transientToken = document.getElementById("transientToken");
var cc = document.getElementById("captureContext").value;
var showArgs = {
containers: {
paymentSelection: "#buttonPaymentListContainer",
paymentScreen: "#embeddedPaymentContainer"
}
};
Accept(cc)
.then(function(accept) {
// Gets the UC instance (e.g. what card brands I requested, any address information I pre-filled etc.)
return accept.unifiedPayments();
})
.then(function(up) {
// Display the UC instance
return up.show(showArgs);
})
.then(function(tt) {
// Return transient token from UC's UI to our app
transientToken.value = tt;
authForm.submit();
}).catch(function(error) {
//merchant logic for handling issues
alert("something went wrong");
});
Capture Context API
This section contains the information you need to request the capture context using the
capture context API.
The capture context request contains all of the merchant-specific parameters that tell the
frontend JavaScript library how to behave 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 elements:
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.
Click to Pay
supports American Express, Mastercard, and Visa.
The
Click to Pay Drop-In UI
manually captures the other card types that are
listed in the capture context request. This enables you to process the payment through
the chosen gateway but the cardholder is not able to enroll these cards in
Click to Pay
.
These card networks are available for card entry:
American Express
Carnet
Cartes Bancaires
China UnionPay
Diners Club
Discover
EFTPOS
ELO
Jaywan
JCB
JCrew
KCP
mada
Maestro
Mastercard
Meeza
PayPak
UATP
Visa
To support dual-branded or co-badged cards, you must list your supported card types
values for the
allowedCardNetworks
field based on your preference
for processing card numbers. For example, if a card is dual-branded as Visa and EFTPOS
and EFTPOS is listed first, the card type is set to EFTPOS 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.
When a Cartes Bancaires dual-branded card is entered in the
Click to Pay Drop-In UI
, the
Click to Pay Drop-In UI
provides a radio
selector button to enable the cardholder to select which scheme they want to use to
process the payment. The radio selector defaults to the card scheme that appears first
in the
allowedCardNetworks
field.
IMPORTANT
Some card types, such as KCP and UATP, do not have security
codes (CVV or CVN). If you include only card types that do not have security codes
in the
allowedCardNetworks
field,
Unified Checkout
does not display the security code field in the UI.
If you include card types
that do not have security codes and cards types that do have security codes in the
allowedCardNetworks
field,
Unified Checkout
displays the security code field in the UI. The field is disabled in the UI when
the cardholder enters a card number for a card type with no security
code.
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:
6 digits
8 digits
no prefix at all
IMPORTANT
When you request the card number prefix for a
Click to Pay
tokenized credential, 6 digits are returned.
Click to Pay
does not return 8 digits.
To specify your preferred
card number prefix length, include or exclude the
transientTokenResponseOptions.includeCardPrefix
field in the
capture context
/sessions
request.
If you want to receive a 6-digit card number prefix in the response
Do not
include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context
/sessions
request.
This example shows how a 6-digit card number prefix
If you want to receive an 8-digit card number prefix in the response
Include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context request, and set the value to
true
.
IMPORTANT
Per PCI DSS
requirements, this requirement applies only to card numbers
longer than 15 digits and for Discover, JCB, Mastercard,
UnionPay, and Visa brands.
If the card type entered is not part of these brands, a
6-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 8-digit card
number prefix is returned.
digital payment methods
that you want to accept in the capture context.
Use the
allowedPaymentTypes
field to define the payment type. The
Click to Pay Drop-In UI
accepts these payment types:
CLICKTOPAY
PANENTRY
IMPORTANT
When you include
CLICKTOPAY
,
PANENTRY
XXX.
IMPORTANT
When integrating with
Visa Acceptance Solutions
APIs,
Visa Acceptance Solutions
recommends that you dynamically
parse the response for the fields that you are looking for. Additional fields may be added
in the future.
You must ensure that your integration can handle new fields that are
returned in the response. While the underlying data structures will 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
This section includes information on the features that are supported in
Click to Pay
.
Save Card
This feature enables you to display an option in the
Unified Checkout
UI for the cardholder to save their payment
details for future use.
IMPORTANT
This feature is available
only for card credentials that are manually entered during checkout.
If
Click to Pay
is an available payment method,
do
not
select
Save this card with
Click to Pay
.
When the customer selects the checkbox 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
when the cardholder selects the option to save
their
card:
"captureMandate": {
"requestSaveCard": 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 and 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.
Mobile as Identity for
Click to Pay
Click to Pay
supports mobile numbers as way to identify
a user. This enables cardholders to use their mobile number instead of their
email address in certain markets for Visa and Mastercard transactions.
When the
requestEmail
field is set to
false
and the
requestPhone
field is
set to
true
, the cardholder is identified using the
provided mobile number. When the
requestEmail
field is
set to
true
and the
requestPhone
field
is set to
false
, the cardholder is identified using the
provided email address. When the
requestEmail
field is
set to
true
and the
requestPhone
field
is also set to
true
, the cardholder is identified using the
provided email address first and then the mobile number if there is no
match.
Removal of Confirm and Continue Screen
When
showConfirmstionStep
is set to
false
, you can remove the final summary confirmation
screens from the checkout experience. When the UI displays cardholder data,
the cardholder can review and, if necessary, edit their payment details
before checkout is complete.
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. This is available when you set the
billingType
field to
PARTIAL
or
FULL
in the capture context. This ensures that the
customer's billing country can be validated in the UI.
Click to Pay
enrollment pre-check is available in
these countries:
loads, the payment buttons
displayed are based on what you include in the
allowedPaymentTypes
object in the capture context.
You can customize the text on the payment buttons by setting the
buttonType
field object in the capture context to one
of these values:
ADD_CARD
CARD_PAYMENT
CHECKOUT_AND_CONTINUE
DEBIT_CREDIT
DONATE
PAY
PAY_WITH_CARD
SUBSCRIBE_WITH_CARD
If you do not include the
buttonType
field in your
request, the payment button text defaults to
Checkout with card
.
For example:
]
Features Available in Brazil
These features are available only in Brazil:
Combo Cards
A combo card is a single card that functions as both a debit and a credit
card.
Click to Pay
enables the cardholder to choose
whether to pay for a transaction using a debit or credit card. The
cardholder can select the card type that they want to use when checking out
with Visa cards. While in the card details section of the payment form, the
cardholder is prompted to decide if they would like to pay using a debit or
credit card. Credit is selected as the default option.
IMPORTANT
Combo cards are applicable only for issuers that
are located in Brazil.
To enable combo cards during checkout, you must include the
comboCard
field in
your capture context request and set the field value to
true
:
"captureMandate": {
"comboCard": 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
Click to Pay
and for all cards that are already stored in
Click to Pay
. If you do not want to offer combo
card at checkout, do not include the
comboCard
field
in your capture context request.
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
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": // taken dynamically from response ,
"clientLibraryIntegrity": //taken dynamically from response: "sha256-cQ1t6GQcN5El4ml1H10eaSV+TuS/hFryblLLl9s/xjY="
},
"type": "gda-0.10.0"
}
],
"iss": "Flex API",
"exp": 1765827144,
"iat": 1765826244,
"jti": "k7oy3rhyKnLr44pf"
}
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 response to a successful customer interaction with the
Unified Checkout
is a transient token. This is returned in the response from the
unifiedPayments.show()
function. The transient token is a reference
to the payment data collected on your behalf. Transient tokens enable secure card
payments without risking exposure to sensitive payment information. The transient token
is a short-term token with a duration of 15 minutes.
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 Base64URL-encoded JSON string and contains various
claims. For more information, see JSON Web Tokens.
The empty field values in the transient token indicate
which fields were captured by the application without exposing you to
personally identifiable information directly.
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.
and enables you to determine if
the payload is fully authenticated. When
cardholderAuthenticationStatus
is set to
true
, the payload is fully authenticated. When
cardholderAuthenticationStatus
is set to
false
, the transaction is not authenticated.
If you
are using
Unified Checkout
with
unifiedPayment.complete()
and
consumerAuthentication
is set to
true
in
the complete mandate request, then
Payer Authentication
is called
automatically if it is available for the selected payment method and card
network. If you use a transient token to request follow-on services directly,
the value of this field indicates if the transaction has been
authenticated.
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.
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.
and enables you to determine if the payload is fully
authenticated. When
cardholderAuthenticationStatus
is set to
true
, the payload is fully authenticated. When
cardholderAuthenticationStatus
is set to
false
, the transaction is not authenticated.
If you are using
Unified Checkout
with
unifiedPayment.complete()
and
consumerAuthentication
is set to
true
in the
complete mandate request, then
Payer Authentication
is called automatically
if it is available for the selected payment method and card network. If you use a
transient token to request follow-on services directly, the value of this field
indicates if the transaction has been authenticated.
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:
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.
Based on the previous example, if the card number 403550XXXXXXXXXX is entered, the
payment network for payment processing is Visa.
During the transaction, the card type is populated with the first network in the list,
and the
detectedCardTypes
field returned in the transient token
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.
If you include Cartes Bancaires as a supported dual-branded card
type,
Unified Checkout
displays a radio button with Visa and Mastercard
options at checkout. This enables the customer to select which payment scheme they want
to use to process the payment. The radio button defaults to the card type that you
specify in the capture context request, but the payment is processed using the option
that the customer selects during checkout.
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
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.
Required Field for Retrieving Transient Token Payment Details
Your payment credentials request must include this field:
This section contains the information you need to retrieve the full payment credentials
collected by the
Unified Checkout
tool using the payment credentials API.
The payment information is returned in a redundantly signed and encrypted payment
object. It uses the JSON Web Tokens (JWTs) as the data standard for communicating this
sensitive data.
IMPORTANT
Payment information returned by the
payment-credentials
endpoint will contain Personal Identifiable
Information (PII). Retrieving this sensitive information requires your system to comply
with PCI security standards. For more information on PCI security standards, see: https://www.pcisecuritystandards.org/
The response is returned using a JWE data object that is encrypted with your public key
created during the
To decrypt the JWE response, use your private key created during the
Unified Checkout
tool's integration. The decrypted content is a JWS data
object containing a JSON payload. This payload can be validated with the
Unified Checkout
public signature key.
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.
Returned Credentials
A payment account number (PAN) or network token is returned on your request depending
on your payment method and
Click to Pay
account status:
Payment Credentials Returned by Card Type and
Click to Pay
Account Status
Click to Pay
Account Status
American Express
Mastercard
Visa
New card not saved in
Click to Pay
PAN
PAN
PAN
New card saved in
Click to Pay
PAN
Network Token
Network Token
Existing card stored in
Click to Pay
PAN
Network Token
Network Token
When you retrieve PAN information from the Payment Credentials API, the
response includes the PAN, card expiration date, and the card verification value
(CVV). When you retrieve network token information, the response includes the
network token and network token cryptogram.
IMPORTANT
Visa and Mastercard always attempt to provision a network
token. A PAN is returned when a network token is not provisioned before checkout
or when the cardholder did not request to enroll the card in
Click to Pay
.
Network tokens are generated in the wallet of
the
Click to Pay
token requestor ID (TRID). When tokenization is
successful, Visa can also complete authentication during the
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.
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.
platform by
invoking the Payment Credentials API. This API retrieves all of the data captured by
Unified Checkout
. This information is transmitted in an encrypted
format to ensure the security of the payment information while in transit.
You must generate an encryption key pair to retrieve this encrypted payment information,
and the public encryption key must uploaded to the
Unified Checkout
system.
Generate a Public Private Key Pair
You must generate a public-private key pair to upload to the
Unified Checkout
system. The public key is uploaded to the
Unified Checkout
platform and
is used to encrypt sensitive information in transit. The private key is used to decrypt
the sensitive payment information on your server. Only the private key can properly
decrypt the payment information.
IMPORTANT
You must secure your private decryption key. This key must never be
exposed to any external systems or it will risk the integrity of the secure
channel.
Unified Checkout
accepts only keys that meet these requirements:
Only RSA keys are supported. Elliptical curves are not supported.
The minimum accepted RSA key size is 2048 bits.
RSA keys must be in JWK format. More information on JWK format is available
here:
. This process sends the appropriate
information to the digital payment systems and registers your page with each system.
Enable
Click to Pay
for
Unified Checkout
in the
Business Center
.
Click to Pay
is listed as an available
digital payment method offered by
Unified Checkout
.
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
.
IMPORTANT
Click to Pay
uses network
tokenization for transactions. These network tokens are stored in the vault
of the token requestor ID (TRID) for the card scheme.
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
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
. 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. This is
available only through Visa.
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
.
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
.
Authentication Methods
Visa Acceptance Solutions
recommends that you review the response in the transient
token and compare it with the information below in order to determine the authentication
status.
For more information about transient
tokens, see Transient Tokens.
This table
describes the possible authentication results and the associated
To manage Mastercard test cards for customer authentication, contact your
implementation consultant or technical account manager.
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:
: 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.
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
CHECKOUT_ERROR
CLICK_TO_PAY_SDK_LOAD_ERROR
COMPLETE_AUTHENTICATION_CANCELED
COMPLETE_AUTHENTICATION_FAILED
COMPLETE_ERROR
COMPLETE_IN_PROGRESS
COMPLETE_NOT_ALLOWED
COMPLETE_TRANSACTION_CANCELLED
COMPLETE_TRANSACTION_FAILED
COMPLETE_VALIDATION_ERROR
CREATE_TOKEN_TIMEOUT
CREATE_TOKEN_XHR_ERROR
ENCRYPT_CARD_FOR_SRC_ENROLMENT_ERROR
GOOGLEPAY_CHECKOUT_ERROR
INVALID_APIKEY
LAUNCH_SRC_CHECKOUT_ERROR
SDK_XHR_ERROR
SHOW_LOAD_CONTAINER_SELECTOR
SHOW_LOAD_ERROR
SHOW_LOAD_INVALID_CONTAINER
SHOW_LOAD_SIDEBAR_OPTIONS
SHOW_PAYMENT_TIMEOUT
SHOW_PAYMENT_UNAVAILABLE
SHOW_TOKEN_TIMEOUT
SHOW_TOKEN_XHR_ERROR
TOKENIZATION_ERROR
TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED
UNIFIED_PAYMENTS_ALREADY_SHOWN
UNIFIED_PAYMENTS_PAYMENT_PARAMETERS
UNIFIED_PAYMENTS_VALIDATION_FIELDS
UNIFIED_PAYMENTS_VALIDATION_PARAMS
404
The specified resource not found in the
system.
500
Unexpected server error.
Supported Countries for
Click to Pay
Click to Pay
is supported in these countries:
Argentina
Australia
Austria
Brazil
Bulgaria
Canada
China
Colombia
Costa Rica
Czech Republic
Denmark
Dominican Republic
Ecuador
El Salvador
Finland
France
Germany
Greece
Honduras
Hong Kong
Hungary
Indonesia
Ireland
Italy
Japan
Jordan
Kuwait
Malaysia
Mexico
Netherlands
New Zealand
Nicaragua
Norway
Panama
Paraguay
Peru
Poland
Qatar
Romania
Saudi Arabia
Singapore
Slovakia
Slovenia
South Africa
Spain
Sweden
Switzerland
Thailand
Ukraine
United Arab Emirates
United Kingdom
United States
Uruguay
Vietnam
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_PK
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
ur_PK
vi_VN
zh_CN
zh_HK
zh_MO
zh_SG
zh_TW
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.
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
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.
Click to Pay
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. 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.
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, but you are using the complete mandate with the
consumerAuthentication
field set to
true
,
authentication is attempted as part of this request. When you do not use the complete
mandate, you must check the result of the
cardholderAuthenticationStatus
field in the transient token and
reqeust
Payer Authentication
directly when it is required.
IMPORTANT
American Express and Mastercard card brands cannot be
authenticated through
Click to Pay
customer authentication.
Visa Prerequisites
Before you can begin customer authentication using
as allowed
payment types, you can load the UI without displaying the
Unified Checkout
checkout button. You can do this by creating a trigger
that defines what event 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. This is required.
The container for the payment screen. It is required when you are in
embedded mode.
IMPORTANT
You can create a trigger only for
CLICKTOPAY
or
PANENTRY
payment
methods.
// 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);
})
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
cardholderAuthenticationStatus
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.
0.30
Complete mandate enhancement to support
Payer Authentication
for
Google Pay and
Click to Pay
.
Support for Pakistan locales (en_PK and ur_PK).
New look and feel of
Unified Checkout
in line with EMVCO best
practices.
0.31
Addition of the
data
object of the
orderInformation
field object and pass-through
fields.
Support for
tokenCreate
in the complete mandate.
Support of pass-through fields, including challenge codes and data only, for
Payer Authentication
.
Support for Jaywan as an
allowedCardNetwork
.
Updated the payment details response to return detected card types. Multiple
card types are shown when more than one card type is detected.
0.32
Support for KCP and UATP in the
allowedCardNetwork
field.
A radio button in the UI for Cartes Bancaires
dual-branded cards.
0.33
Support for mobile as identity for
Click to Pay
accounts.
Japanese language translation updates.
UX captures billing and shipping information when they are not included in
the capture context.
0.34
Iframes are used instead of pop-ups to reduce pop-up blocking and
streamlining mobile deployment.
Additional BIN range for Jaywan card types.
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
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
Browser Support
Unified Checkout
supports these browser versions:
Safari 16
Firefox 121
Google Chrome/Chium-based browsers 118
Microsoft Edge 118
Capture Context Example
Use the
targetOrigins
and the
allowedPaymentTypes
fields to define the target origin and
the accepted digital payment methods in your capture context. Use the
completeMandate
to orchestrate follow-on services such as
Payments,
This diagram shows how elements of the capture context request appear in the card entry
form.
Figure:
Anatomy of a Manual Card Entry Form
Payment Credentials API
This section contains the information you need to retrieve the full payment credentials collected by the
Unified Checkout
tool using the payment credentials API. The payment information is returned in a redundantly signed and encrypted payment object. It uses the JSON Web Tokens (JWTs) as the data standard for communicating this sensitive data.
IMPORTANT
Payment information returned by the
payment-credentials
endpoint will contain Personal Identifiable Information (PII). Retrieving this sensitive information requires your system to comply with PCI security standards. For more information on PCI security standards, see: https://www.pcisecuritystandards.org/
The response is returned using a JWE data object that is encrypted with your public key created during the
To decrypt the JWE response, use your private key created during the
Unified Checkout
tool's integration. The decrypted content is a JWS data object containing a JSON payload. This payload can be validated with the
Unified Checkout
public signature key.
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.
Returned Credentials
A payment account number (PAN) or network token is returned on your request depending on
your payment method and
Click to Pay
account status:
Payment Credentials Returned by Card Type and
Click to Pay
Account Status
Click to Pay
Account Status
American Express
Mastercard
Visa
New card not saved in
Click to Pay
PAN
PAN
PAN
New card saved in
Click to Pay
PAN
Network Token
Network Token
Existing card stored in
Click to Pay
PAN
Network Token
Network Token
When you retrieve PAN information from the Payment Credentials API, the response
includes the PAN, card expiration date, and the card verification value (CVV). When you
retrieve network token information, the response includes the network token and network
token cryptogram.
IMPORTANT
Visa and Mastercard always attempt to provision a network token.
When a network token is not provisioned, the default payment method is the PAN. When there
is a PAN transaction, the PAN is not stored in the consumers wallet and it is treated as a
single transaction.
Network tokens are generated in the wallet of the
Click to Pay
token requestor ID (TRID). When tokenization is successful, Visa
attempts to complete authentication during the
You must meet these requirements for tokenization to be successfully configured for your
merchant ID (MID):
Click to Pay
is enabled as a digital payment in the
Business Center
.
The transacting MID is configured for tokenization with
Click to Pay
. Contact your Implementation Consultant or Technical Account Manager to configure
tokenization with
Click to Pay
.
The
allowedPaymentTypes
field value is set to
CLICKTOPAY
in the capture context. For information on the capture
context, see Capture Context API.
Endpoint
Production:
GET
https://api.visaacceptance.com
/flex/v2/payment-credentials/
{ReferenceID}
Test:
GET
https://apitest.visaacceptance.com
/flex/v2/payment-credentials/
{ReferenceID}
The
{ReferenceID}
is the reference ID returned in the
id
field when you created the
payment credentials.
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:
This section includes examples of the interfaces that your customers can expect when
completing a payment with
Click to Pay
.
Completing a payment with
Unified Checkout
requires the customer to
navigate through a sequence of interfaces:
Figure:
Click to Pay
UI
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.
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:
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.
Based on the previous example, if the card number 403550XXXXXXXXXX is entered, the
payment network for payment processing is Visa.
During the transaction, the card type is populated with the first network in the list,
and the
detectedCardTypes
field returned in the transient token 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.
If you include Cartes Bancaires as a supported dual-branded card type,
Unified Checkout
displays a radio button with Visa and Mastercard options at
checkout. This enables the customer to select which payment scheme they want to use to
process the payment. The radio button defaults to the card type that you specify in the
capture context request, but the payment is processed using the option selected by the
customer during checkout.
Set Up Customer Authentication for Visa
Click to Pay
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. This is
available only through Visa.
field object. These fields are used only for payouts:
Recipient Information Fields
Field
Type
Required?
Example
recipientInformation.accountId
String
Conditional
acc0123567
recipientInformation.accountType
String
Conditional
01
recipientInformation.administrativeArea
String
No
GB
recipientInformation.country
String
Conditional
GB
recipientInformation.dateOfBirth
String
No
19900101
recipientInformation.firstName
String
Conditional
John
recipientInformation.lastName
String
Conditional
Buyer
recipientInformation.middleName
String
No
A
recipientInformation.postalCode
String
No
12345
Merchant Defined Information Fields
This table contains information about the
merchantDefinedInformation[]
field array:
Merchant Defined Information Fields
Field
Type
Required?
Example
merchantDefinedInformation[].key
String
Required when
merchantDefinedInformation[].value
is
included in the request.
customer_id
merchantDefinedInformation[].value
String
Required when
merchantDefinedInformation[].key
is included in the request.
12345
Device Information Fields
This table contains information about the
deviceInformation
field
object:
Merchant Defined Information Fields
Field
Type
Required?
deviceInformation.ipAddress
String
No
Payment Information Fields
This table contains information about the
paymentInformation
field
object:
Merchant Defined Information Fields
Field
Type
Required?
Example
paymentInformation.card.typeSelectionIndicator
Enum
No
0
Allowed Payment Types Variations
This table describes the possible values for the
allowedPaymentTypes
field object:
Payment Types Variations
Payment Type
Value
Additional Requirements in Capture Context
Details
Manual card entry
PANENTRY
Basic card entry.
Click to Pay
CLICKTOPAY
or
object {
"type":"CLICKTOPAY","options":{...} }
Include email in for autolookup.
Auto‑check enrollment available is available through
options.autoCheckEnrollment
.
Apple Pay
APPLEPAY
Google Pay
GOOGLEPAY
Paze
PAZE
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_PK
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
ur_PK
vi_VN
zh_CN
zh_HK
zh_MO
zh_SG
zh_TW
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.
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. Transient 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 API for the
customer payment data that is collected.
Test Payment Details
Use these test card numbers to test your
Unified Checkout
configuration.
Combine the BIN with the card number when sending to
JavaScript flow within your payment
page without requiring the cardholder to select a card payment option. This example
shows a recognized user payment flow where the cardholder's information is shown
automatically next to the other payment methods hosted within your payment page. For
information about customizing how to trigger
payment button as a separate
payment method from the card payment button. If you do this, the cardholder is not
prompted with their
Click to Pay
cards and must manually enter
their payment details. They will also not have the option to store their card within
Click to Pay
for future use.
These examples show multiple card payment options and
Click to Pay
in a UI:
Figure:
Multiple Card Payment Options in UI Example 1
Figure:
Multiple Card Payment Options in UI Example 2
Figure:
Multiple Card Payment Options in UI Example 3
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
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.
Click to Pay
UI Guidelines
The UI that is built in
Unified Checkout
for
Click to Pay
is built based on the EMV
Click to Pay
XC Guidelines V1.1.
Unified Checkout
has simplified the integration of the UI. The only UI
work that you must complete is the placement of the payment option.
IMPORTANT
You must include
Click to Pay
as one of the
presented payment methods and not as a separate payment method.
Unified Checkout
captures all card details that are manually entered by the
cardholder. This enables the cardholder to enroll in
Click to Pay
and removes the requirement for the cardholder to manually enter their card details the
next time they check out.
Unified Checkout
provides a standard payment label in the
Unified Checkout
JavaScript that is loaded in your checkout page. One of these
scenarios occurs when the cardholder selects the button:
The cardholder is recognized.
The cardholder is not recognized but has a
Click to Pay
account.
The cardholder does not have a
Click to Pay
account.
You can also trigger the
Unified Checkout
flow using a custom button. If
you are using your own custom button, your payment button or widget must display the
Your implementation consultant will ask you for a mock-up of your
payment flow for confirmation that it is compliant with the
Click to Pay
UI design standards.
Recognized
Click to Pay
Customer
The cardholder is presented with their stored
Click to Pay
cards
in the UI when they are on a recognized device:
Figure:
Recognized
Click to Pay
Customer UI
Unrecognized
Click to Pay
Customer
When the cardholder has a
Click to Pay
account but is not on a
registered device, they receive a one-time password to their registered email
address and phone number to authenticate their identity before their stored
Click to Pay
credentials are shown:
Figure:
Unrecognized
Click to Pay
Customer on a Recognized
Device UI
No
Click to Pay
Account
When the cardholder does not have a
Click to Pay
account, they
can provide a new email address to perform a new lookup or they can choose to enter
their card details manually. The cardholder can make a one-time payment or complete
the payment and choose to create a
Click to Pay
account for
future use:
Figure:
No
Click to Pay
Account UI
Test Authentication
Use this table to determine how to test your authentication method.
A Google device must be used with biometric authentication for
Google authentication.
A user authenticates themselves on a Google device with a
tokenized Google Pay credential – the returned payload from Google
will be Authenticated
Google Pay
Payer Authentication
through
Unified Checkout
Authorization and
Payer Authentication
You must use a device, such as a web browser, that does not
authenticate the cardholder as part of the authorization
process.
Google will return an un-authenticated payload to Unified
Checkout . Unified Checkout will step in and process Authentication
via Payer Authentication when the Complete Mandate function is used
with consumerAuthentication
IfClick to Payis not enabled, clickOnnext toClick to Pay.
