On This Page
Unified Click to Pay Developer Guide
Unified Click to Pay
Developer GuideThis section describes how to use this guide and where to find further
information.
- Audience and Purpose
- This document is written for merchants and ISVs who want to enableUnified Click to Payso that they can accept payments on their e-commerce page.
- Conventions
- This statement is used in this document:IMPORTANTAnImportantstatement contains information essential to successfully completing a task or learning a concept.
- Customer Support
- For support information about any service, visit the Support Center:
Recent Revisions to This Document
26.02.01
Initial release.
Pilot Release
This document describes the pilot release of the
Unified Click to Pay
Developer
Guide.Introduction to Unified Click to Pay
Unified Click to Pay
Unified Click to Pay
, powered by Unified Checkout
, provides a
flexible integration that enables merchants to customize their checkout experience for
accepting Click to Pay
payments from Visa, Mastercard, and American
Express. The Unified Click to Pay
SDK has no UI and the UI must be configured by
the integrator. This enables merchants and partners to fully control the UI and
branding. Unified Click to Pay
offers advanced security and compliance and is PCI
4.0 compliant. Unified Click to Pay
consists of a server-side API and a client-side JavaScript
SDK. The server-side component authenticates your identity as the merchant and instructs
the system to act within your payment environment. The response contains a JWT that can
be used for the initialization of the client-side SDK and sets up the backend
configuration required to run the SDK.The client-side JavaScript SDK can be used to integrate with
Click to Pay
payments from Visa, Mastercard, and American Express
cards.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.Prerequisites
Before you call the capture context and load the SDK, you must complete these tasks:
Enabling Click to Pay
Click to Pay
To begin your integration, you must first enable
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
:- Log in to theBusiness Center:Production URL:If you are unable to access this page, contact your sales representative.
- Navigate toPayment Configuration >.Unified Checkout
- In the Click to Pay section, clickSet Up.
- Enter your business name and website URL.
- ClickSubmit.
- Contact your implementation contactor technical account managerto request that you be enabled for tokenization withinClick to Pay. Your implementation contactor technical account managerwill confirm that you were configured successfully and that you can now accept digital payments withClick to Pay.IMPORTANTClick to Payuses network tokenization for transactions. These network tokens are stored in the vault of the token requestor ID (TRID) for the card scheme.
Upload Your Encryption Key
After you enable
Click to Pay
, you must upload your public
encryption keys so that you can retrieve payment information from the Unified Click to Pay
checkout()
SDK method. This method retrieves all of the payment
data that is captured during the transaction. The payment data is encrypted to
ensure that the payment information is secure. You must generate an encryption key
pair to retrieve the encrypted payment information and upload the public encryption
key to the Visa Acceptance Platform
. Follow these steps to upload your encryption key to the
Visa Acceptance Platform
:- Log in to theBusiness Center:Production URL:If you are unable to access this page, contact your sales representative.
- In theBusiness Center, from the navigation panel chooseKey Management.
- Click+ Generate key.
- Under Alternate Key Types, chooseToken Management MLEand clickGenerate key.
- Enter your public key in Base64 format and clickCreate key.
Set Up Customer Authentication for Unified Click to Pay
Unified Click to Pay
After you enable
Click to Pay
and upload your encryption key, you must
set up customer authentication for Unified Click to Pay
. Follow these steps
to use the Business Center
to enable customer authentication through
Unified 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.- Log in to theBusiness Center:Production URL:If you are unable to access this page, contact your sales representative.
- In theBusiness Center, from the navigation panel choosePayment Configuration>Unified Checkout.You must haveClick to Payenabled as a digital payment method to use this method of authentication. ClickManageto view the digital payment methods that you have enabled.
IfClick to Payis not enabled, clickOnnext toClick to Pay.
- Enter the account details and clickUpdate.
- ClickSet upunder Value Added Solutions. The Value Added Solutions page appears.
- ClickSet upto set up3-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 byyour 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 contactyour acquirer. Completing this information enablesVisa Acceptance Solutionsto send Visa the information that is required for authentication.IMPORTANTCharges for3-D Securemay apply. You must speak withyour acquirerfor more information about the charges associated with3-D Secure.
Unified Click to Pay Customer Workflows
Unified Click to Pay
Customer WorkflowsThis section describes the flows within
Unified Click to Pay
. Unified Click to Pay
provides customers with a simple payment experience across
multiple payment networks. You can customize the user experience.The customer flow for calling the capture context and loading the SDK differs based on
the type of customer in
Click to Pay
:- The customer is a recognizedClick to Paycustomer.
- The customer is not recognized byUnified Click to Paybut is aClick to Paycustomer.
- The customer is a new user enrolling inClick to Pay.
Recognized Click to Pay Customer
Click to Pay
CustomerThis section provides an overview of the
Click to Pay
recognized
experience. This interaction occurs when a customer's device is recognized by the
Unified Click to Pay
.A customer's device is recognized under these conditions:
- When the customer has usedClick to Payon their device through anyClick to Paychannel.
- If the customer chose to have their device remembered during a previous transaction.
Figure:
Recognized
Click to Pay
Customer- Set up your server side by generating the capture context. For information about how to set up your server side, see Server-Side Set Up.
- Set up your client side by initiating theUnified Click to PayJavaScript SDK. For a recognized customer, you will load these functions from the SDK:
- initialize(capture context JWT)
- getCards(consumer identity - email)
- checkout(card details)
Unrecognized Click to Pay Customer
Click to Pay
CustomerThis section provides an overview of the
Unified Click to Pay
unrecognized
experience. This interaction occurs when a customer's device is not recognized by the
Unified Click to Pay
SDK. This condition occurs when the customer has a
Click to Pay
account but has not used it on their device
previously.Figure:
Unrecognized
Click to Pay
Customer- Set up your server side by generating the capture context. For information about how to set up your server side, see Server-Side Set Up.
- Set up your client side by initiating theUnified Click to PayJavaScript SDK. For an unrecognized customer, you will load these functions from the SDK:
- initialize(capture context JWT)
- getCards(consumer identity - email)
- getCards(validation data - otp)
- checkout(card details)
Guest Customer
This section provides an overview of the
Unified Click to Pay
guest flow. 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
.Figure:
Guest Customer
- Set up your server side by generating the capture context. For information about how to set up your server side, see Server-Side Set Up.
- Set up your client side by initiating theUnified Click to PayJavaScript SDK. For a guest customer, you will load these functions from the SDK:
- initialize(capture context JWT)
- getCards(consumer identity - email)
- checkout(card details)
Unified Click to Pay Integration
Unified Click to Pay
IntegrationThis section describes how to integrate and launch
Unified Click to Pay
on your
website and process a transaction for you. For information about the detailed
specifications of the APIs described in this section see API Specifications. To integrate Unified Click to Pay
into
your platform, you must follow these integration steps:- 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 theUnified Click to PayJavaScript library using the JWT response from the capture context request. For information on setting up the client side, see Client-Side Set Up.
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.Server-Side Set Up
This section contains the information you need to
set up your server. Initializing
Unified Click to Pay
within your webpage begins
with a server-to-server call to the sessions API. This step authenticates your merchant
credentials, and establishes how Unified Click to Pay
manages your capture
context configuration. This includes supported locales, currencies, and country
availability. The sessions API request contains parameters that define how Unified Click to Pay
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
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, in addition to allowed card networks and payment types. The capture
context, at a minimum, requires these elements:
- allowedCardNetworks
- amountDetails
- billingType
- country
- currency
- data.orderInformation.amountDetails.totalAmount
- data.orderInformation.amountDetails.currency
- locale
- totalAmount
- version
Capture Context Example
{ // -------- REQUIRED VALUES ---------- "data": { "orderInformation": { "amountDetails": { "totalAmount": "123.94", "currency": "USD" } } }, "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX" ], "billingType": "FULL", "country": "US", "locale": "en_US" }
Client-Side Set Up
This section contains the information you need to set up the client side. You use the
Unified Click to Pay
JavaScript library to add the payment interface to your
e-commerce site.Follow these steps to set up the client:
- Load the JavaScript library.
- Initialize the SDK with the JWT by passing the JWT as a parameter in the initialization method. For information JSON Web Tokens, see JSON Web Tokens.
After you initialize the SDK, you can use the unified SDK as a single integration across
multiple
Click to Pay
schemes.Get Started with Unified Click to Pay
Unified Click to Pay
This section describes the specifications for these
Unified Click to Pay
API
methods and their parameters:initialize()
This method initializes the application with the common state. The initialize method must
be called before any other methods.
JavaScript Example
window.onload = async function () { // Create a shorthand reference to the Unified Click to Pay SDK const uctp = window.UCTP; // fetch the JWT from Capture Context // Initialize the Unified Click to Pay SDK with your JWT received from capture context try { await uctp.initialize({ captureContext: captureContext //optionally, pass the dpaTransactionOptions here }); //Invoke getCards and other apis here onwards } catch (error) { console.error('Error initializing SDK:', error); } };
In this example,
captureContext
refers to the capture context
JWT.Syntax
Your
initialize()
request must have this syntax:initialize({ required CaptureContext <JWT> captureContext; optional DpaTransactionOptions dpaTransactionOptions; });
getCards()
getCards
encapsulates all your identity calls. Make the
getCards
with the email. For unrecognized user, you’d receive
PENDING_CONSUMER_IDV
. This would trigger an OTP generation. Make
the getCards
call again with the OTP. JavaScript Example
// Get cards sample request let consumerIdentity = { identityProvider: "SRC", identityValue: "[email protected]", identityType: "EMAIL_ADDRESS" }; let cards = await uctp.getCards({ consumerIdentity }); let { actionCode } = cards; switch (actionCode) { case 'SUCCESS': //handle getCards response in UI console.log('Handle getCards response in the UI ', cards); break; // If cards status is "PENDING_CONSUMER_IDV", call getCards again with validationData case 'PENDING_CONSUMER_IDV': const validationDataInput = { consumerIdentity, validationData: "654321"}; // Replace with your actual validation data cards = await uctp.getCards(validationDataInput); break; case 'ERROR': console.log('Handle error cases:'); break; default: console.log('No cards found >> ', cards.actionCode); break; }
Syntax
Your
getCards()
request must have this syntax:getCards({ required ConsumerIdentity consumerIdentity; conditional String validationData; })
checkout()
This method performs checkout using the specified Digital Card or PAN. If successful, the
response contains summary checkout information and, conditionally, an encrypted payload
signed by the SRC System containing PCI and/or PII data.
This method is called after the consumer has chosen a card for checkout from the card
list or when the consumer enrolls a new card.
To add a card, the partner or merchant should provide the encrypted Card object, instead
of ID of the digital card identifier, as an input parameter. The card will be enrolled
into the SRC system and used for checkout.
JavaScript Example
//sample checkoutParameters const checkoutParameters = { srcDigitalCardId: 'nE5xhI3jQcSis6Vf7IAH-A000000000000US', dpaTransactionOptions: { dpaBillingPreference: 'POSTAL_COUNTRY', dpaAcceptedBillingCountries: ['US', 'CA'], consumerNationalIdentifierRequested: false, merchantCategoryCode: '4829', merchantCountryCode: 'US', merchantOrderId: '8e15ce5c-58a3-4748-acab-71c67432dfa7', paymentOptions: [ { dpaDynamicDataTtlMinutes: 2, dynamicDataType: 'CARD_APPLICATION_CRYPTOGRAM_LONG_FORM' } ] }, payloadTypeIndicatorCheckout: 'FULL' }; // Call checkout const checkoutResponse = await uctp.checkout(checkoutParameters); // Log the checkout response console.log(checkoutResponse);
Syntax
Your
checkout()
request must have this syntax:checkout({ conditional String srcDigitalCardId; conditional JWE<Card> encryptedCard; optional Consumer consumer; optional DpaTransactionOptions dpaTransactionOptions; optional PayloadTypeIndicator payloadTypeIndicatorCheckout; conditional Window windowRef; conditional ComplianceSettings complianceSettings; optional AssuranceData assuranceData; })
initiateIdentityValidation()
This can be used to trigger resend the OTP.
JavaScript Example
await uctp.initiateIdentityValidation({ consumerIdentity });
Syntax
Your
initiateIdentityValidation()
request must have this
syntax:initiateIdentityValidation({ optional String requestedValidationChannelId })
unbindAppInstance()
This method unbinds a device identity (an application instance) from an SRC profile.
JavaScript Example
await uctp.unbindAppInstance();
Syntax
Your
unbindAppInstance()
request must have this syntax:unbindAppInstance()
API Specifications
This section describes the specifications for all
Unified Click to Pay
API
methods and their parameters.initialize()
dpaTransactionOptions
is an optional field in a
initialize()
request. You can include the
dpaTransactionOptions
field in the initialize()
request if your system supports it. You must consider this information if you include
the dpaTransactionOptions
field in your request:- You must include the transaction amount and currency in the backend of the request payload that is sent to/sessionsAPI. The values that are included in the request to the/sessionsAPI are used and any value included indpaTransactionOptionsare ignored.
- You must configure authentication fields in theBusiness Center. The values of these fields are retrieved from the merchant or partner profiles and not from thedpaTransactionOptionsfield.
initialize()
request must have this syntax:initialize({ required CaptureContext <JWT> captureContext; optional DpaTransactionOptions dpaTransactionOptions; });
Request Parameters
Your
initialize()
request can include these parameters:Request Parameters
Name | Required? | Description |
|---|---|---|
dpaTransactionOptions Type : DpaTransactionOptions | Optional | These options can override default transaction options configured during DPA Registration. |
captureContext Type : JWT | Required | Returned from the backend sessions call |
DpaTransactionOptions
Data Element | Required? | Description |
|---|---|---|
dpaAcceptedBillingCountries Type : List<String> | Optional | Billing restrictions. Payments from these countries are accepted. ISO 3166‑1 alpha‑2 country codes. ["US","CA","AU"] |
dpaBillingPreference Type : AddressPreference | Optional | Type of billing address required. Possible values:
|
dpaLocale Type : String | Optional | Merchant preferred locale in ISO 639‑1 and ISO 3166‑1 format. ["en_US", "fr_CA"] |
merchantCategoryCode Type : StringLength : 4 | Optional | Merchant category code. |
merchantCountryCode Type : String | Optional | Merchant country in ISO 3166‑1 alpha‑2 format. |
merchantName Type : String | Optional | Merchant name. |
merchantOrderId Type : String, UUID | Optional | DPA-generated order or invoice number. |
paymentOptions Type : List<PaymentOptions > | Optional | Dynamic Data requirements. |
recurringData Type : RecurringData | Optional | Recurring transaction data. |
PaymentOptions
Data Element | Required? | Description |
|---|---|---|
dpaDynamicDataTtlMinutes
Type : String (Numeric) | Optional | TTL of the dynamic data in minutes. |
dynamicDataType Type : DynamicDataType | Optional | Type of dynamic data required.
|
AuthenticationPreferences
Data Element | Required? | Description |
|---|---|---|
authenticationMethods Type : List<AuthenticationMethod> | Optional | List of authentication methods. |
payloadRequested Type : PayloadRequested | Optional | Indicates preferred payload type. |
supressChallenge Type : Boolean | Optional | SRCI preference to suppress challenges. |
AuthenticationMethod
AuthenticationMethod
Data Element | Required? | Description |
|---|---|---|
authenticationMethodType Type : AuthenticationMethodType | Required | Indicates whether C2P should perform managed
authentication. Possible values:
|
authenticationSubject Type : AuthenticationSubject | Required | Authentication subject. Possible values:
|
uriData Type : UriData | Optional | URI used to launch authentication. Relevant data is returned asynchronously. |
authenticationCredentialReference Type : StringMaximum Length : 255 | Optional | Reference returned by identity provider. |
methodAttributes Type : JSONObject | Optional | Method‑specific attributes. |
The content of the
methodAttributes
object depends on the
authenticationMethodType
field value and the method that is
requested. The methodAttributes
object is included within the
checkout response for the authentication flow or as part of the
AuthenticationMethod
object in the checkout authentication
request flow.If
authenticationMethodType
is any of the these values.- CSC_VALIDATION
- SMS_OTP
- EMAIL_OTP
- APP_AUTHENTICATON
- 3DS
authenticationMethodType | Data Element | Description |
|---|---|---|
CSC_VALIDATION | cardSecurityCode Type :
StringMaximum Length : 4 | Card security code. |
SMS_OTP | otpValue Type : StringMaximum Length : 16 | OTP value. |
EMAIL_OTP or
APP_AUTHENTICATON | stepUpIdentifier Type : String | Step-up identification. |
3DS | challengeIndicator Type : String | Challenge indicator value related to 3-D Secure
authentication.For SRC orchestrated 3-D Secure is
authentication method, SRCIs can specify the preference of
challenge indicator here. Please refer to EMV 3-D Secure specification for more details.IMPORTANT
If no preference provided, SRC will set up the
default value of 01 for 3-D Secure and 04 when followed by FIDO
registration.If value is set to 05 by the SRCI
then do not override the indicator to
03 though it is a FIDO compliant
device.Possible values:
|
UriData
Data Element | Required? | Description |
|---|---|---|
uri Type : StringMaximum Length : 2048 | Required | Specifies the URI for the given authentication method. |
uriType Type : UriType | Required | URI type. Possible values:
|
RecurringData
Data Element | Required? | Description |
|---|---|---|
recurringAmount Type : String (Numeric)Maximum Length : 48 | Required when recurringInd.AmountInd =
01 | Recurring amount in minor units of currency with all punctuation removed. For example, when the purchase amount is USD 123.45, these values are acceptable:
|
recurringCurrency Type : String | Required when recurringAmount is included. | Currency in which recurringAmount is expressed. Currency must be in ISO 4217 format. |
recurringDate Type : String (Numeric)Length : 8 | Required when recurringInd.frequencyInd =
01 | Effective date in YYYYMMDD format. |
recurringExpiry Type : String (Numeric)Length : 8 | Required when there is an end date. | Date after which no further authorizations occur, in YYYYMMDD format. |
recurringExponent Type : String (Numeric)Length : 1 | Required when recurringAmount is included. | Minor units of currency according to ISO 4217 (e.g., USD=2, JPY=0). |
recurringFrequency Type : StringMaximum Length : 4 | Required when recurringInd.frequencyInd =
01 | Minimum number of days between authorizations (1–9999). |
recurringInd Type : JSONObject | Required | Indicates recurring/instalment amount and frequency type. Possible values for amountInd :
Possible values for frequencyInd :
Example:
|
Handle Errors
An error response notifies the user that the action relating to the request
has failed. Use the
error.reason
field to determine how
to handle the error. Errors such as INVALID_PARAMETER
or
INVALID_REQUEST
are considered integration errors.Error reasons and messages appear in a standard error structure, which is
returned when the API request could nxot be handled. For programmatic
actions, you should only rely on the value in the
error.reason
field. Errors include a description in
the error.message
field.You can use this field to
understand the error. You can provide your own description based on the
value in the error.reason
field. In some cases, the
error.details.message
and
error.details.location
provide additional
information.Error Field | Type | Description |
|---|---|---|
error.details.location | String | The value of this field uses an XPATH expression to point to
the field that fails validation. |
error.details.message | String | The specific error associated with the field. |
error.message | String | Returned from the backend call |
error.reason | String | These options can be used to override transaction options for
the DPA that were configured during the DPA
Registration. |
This is an example error:
error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [ // Optional structure, used with input data validation error { // Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] }
Error Code | Description |
|---|---|
AUTH_ERROR | The server understands the request, but cannot
authenticate. |
INVALID_PARAMETER | The value provided for one or more request parameters is
considered invalid. This error is also generated in case of
a missing required field. Typically, this is an integration
error; whenever possible, should provide client-side
validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to
change the value. |
INVALID_REQUEST | The server could not interpret the request. Usually, these are the cases, when a data field has to be in
a particular format but is not. Examples include:
The message field may provide additional clarification of
what part or field of the request is considered
incorrect. Please, refer to the API specification for the structure,
format, and constraints on the API request. |
NOT_FOUND | The requested resource/business entity does not exist. The
resource might also be hidden for security reasons. |
RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time.
Intended for use with rate limiting schemes.
|
REQUEST_TIMEOUT | Request timeout. |
SERVER_ERROR | General server error. |
SERVICE_ERROR | An error occurred on the server. Either show a generic message, or retry the same request
again (it might succeed). |
UNKNOWN_ERROR | Unknown error. |
getCards()
Your
getCards()
request must have this syntax:getCards({ required ConsumerIdentity consumerIdentity; conditional String validationData; })
Request Parameters
Your
getCards()
request can include these parameters:Request Parameters
Field | Required? | Description |
|---|---|---|
consumerIdentity Type : ConsumerIdentity | Required | Primary verifiable consumer identity within an SRC profile (e.g. an email address). IMPORTANT
If an SRC system recognizes the user then
this identity can be ignored. |
validationData Type : String | Required when a prior call within the same transaction returns a field
value of PENDING_CONSUMER_IDV for the
actionCode field. | The validation data (e.g. the OTP value) entered by the user. IMPORTANT
When a merchant calls
getCards() for the first time and the
user is not recognized, Visa initiates identity validation
and returns a value of PENDING_CONSUMER_IDV
for the actionCode field. This field is
required the second time the merchant calls
getCards() after the OTP is
provided. |
ConsumerIdentity
Data Element | Required? | Description |
|---|---|---|
identityProvider Type : IdentityProvider | Optional | Entity or organization that collected and verified the identity. The default value is SRC . |
identityType Type : ConsumerIdentityType | Required | Type of consumer identity transmitted or collected. IMPORTANT
Only an email address is
supported.
|
identityValue Type : StringMaximum Length : 255 | Required | Consumer identity value used to locate profile information. This is not an SRC consumer reference identifier but a consumer‑provided value. IMPORTANT
Only an email address is
supported. |
SrcProfile
Data Element | Required? | Description |
|---|---|---|
maskedCards Type : List<MaskedCard > | Required | Masked card data associated with the SRC profile. May be empty. |
maskedConsumer Type : MaskedConsumer | Optional | Masked consumer data associated with the profile. |
MaskedCard
Data Element | Required? | Description |
|---|---|---|
srcDigitalCardId Type : StringUniversally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for checkout. |
panBin Type : String (Numeric)Maximum Length : (PAN Length -10) | Required | First significant digits of the PAN in unmasked form. |
panLastFour Type : String (Numeric)Length : 4 | Required | Last four digits of the PAN in unmasked form. |
panExpirationMonth Type : String (Numeric)Length : 2 | Required when specified for the PAN. | Expiration month (MM). |
panExpirationYear Type : String (Numeric)Length : 4 | Required when specified for the PAN. | Expiration year in YYYY format. |
tokenBinRange Type : String (Numeric)Maximum Length : (Payment token length -10) | Required when a payment token is used. | BIN range used for issuing payment tokens (unmasked). |
tokenLastFour Type : String (Numeric)Length : 4 | Required when a payment token is used. | Last four digits of the payment token (unmasked). |
digitalCardData Type : DigitalCardData | Required | Digital card information used in UI and acceptance environments. |
maskedCardholderFullName Type : StringMaximum Length : 100 | Optional | Masked full cardholder name. |
maskedCardholderFirstName Type : StringMaximum Length : 50 | Optional | Masked first name. |
maskedCardholderLastName Type : StringMaximum Length : 50 | Optional | Masked last name. |
paymentCardDescriptor Type : StringMaximum Length : 32 | Optional | Card brand descriptor. |
paymentCardType Type : StringMaximum Length : 32 | Optional | Card type. |
digitalCardFeatures Type : List<DigitalCardFeature > | Optional | Attributes related to digital card features for consumer display. |
countryCode Type : String | Optional | Issuer country code in ISO 3166‑1 alpha‑2 format. |
maskedBillingAddress Type : MaskedAddress | Optional | Masked billing address. |
dcf Type : Dcf | Optional | Digital Card Facilitator. Present when MaskedCard is used in Checkout or Get
Payload. |
paymentAccountReference Type : StringMaximum Length : 29 | Optional | Reference tying PAN to its associated tokens. |
dateOfCardCreated Type : String (Numeric)UTC Unix epoch | Required | Date the card was enrolled. |
dateOfCardLastUsed Type : String (Numeric)UTC Unix epoch | Optional | Date when card was last used. |
DigitalCardData
Data Element | Required? | Description |
|---|---|---|
status Type : DigitalCardStatus | Required | State of the digital card. Possible values:
|
presentationName Type : StringMaximum Length : 64 | Optional | Consumer-defined text to help recognize the card. |
descriptorName Type : StringMaximum Length : 64 | Required | System‑defined card description. |
artUri Type : StringMaximum Length : 1024 | Required | URI hosting the card image. |
artHeight Type : String (Numeric)Maximum Length : 4096 | Optional | Card art height in pixels. |
artWidth Type : String (Numeric)Maximum Length : 4096 | Optional | Card art width in . |
pendingEvents Type : List<CardPendingEvent > | Required when the status is PENDING . | Pending events. Possible values:
|
authenticationMethods List< AuthenticationMethod > | Optional | List of supported authentication methods. |
AuthenticationMethod
Data Element | Required? | Description |
|---|---|---|
authenticationMethodType Type : AuthenticationMethodType | Required | SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not. Possible
values:
|
authenticationSubject Type : AuthenticationSubject | Required | Authentication subject. Possible values:
|
uriData Type : UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then
AssuranceData ,
AuthenticationStatus ,
AuthenticationResult and any relevant
session ids should be provided back asynchronously when
authentication completes.It can be achieved by cross‑origin post message between the
windows (caller and authenticator). |
authenticationCredentialReference Type : StringMaximum Length : 255 | Optional | May be provided by the identity provider to qualify the nature of
the authentication method. |
methodAttributes Type : JSONObject | Optional | Attributes associated with the authentication method
type. |
The content of the
methodAttributes
object depends on the
authenticationMethodType
field value and the method that is
requested. The methodAttributes
object is included within the
checkout response for the authentication flow or as part of the
AuthenticationMethod
object in the checkout authentication
request flow.If
authenticationMethodType
is any of the these values.- CSC_VALIDATION
- SMS_OTP
- EMAIL_OTP
- APP_AUTHENTICATON
- 3DS
authenticationMethodType | Data Element | Description |
|---|---|---|
CSC_VALIDATION | cardSecurityCode Type :
StringMaximum Length : 4 | Card security code. |
SMS_OTP | otpValue Type : StringMaximum Length : 16 | OTP value. |
EMAIL_OTP or
APP_AUTHENTICATON | stepUpIdentifier Type : String | Step-up identification. |
3DS | challengeIndicator Type : String | Challenge indicator value related to 3-D Secure
authentication.For SRC orchestrated 3-D Secure is
authentication method, SRCIs can specify the preference of
challenge indicator here. Please refer to EMV 3-D Secure specification for more details.IMPORTANT
If no preference provided, SRC will set up the
default value of 01 for 3-D Secure and 04 when followed by FIDO
registration.If value is set to 05 by the SRCI
then do not override the indicator to
03 though it is a FIDO compliant
device.Possible values:
|
UriData
Data Element | Required? | Description |
|---|---|---|
uri Type : StringMaximum Length : 2048 | Required | Specifies the URI for the given authentication method. |
uriType Type : UriType | Required | URI type. Possible values:
|
DigitalCardFeature
Data Element | Required? | Description |
|---|---|---|
content Type : StringMaximum Length : 1024 | Required | Content of the digital card feature. |
contentType Type : DigitalCardFeatureContentType | Required | Content type of the digital card feature. Possible values:
|
style Type : StringMaximum Length : 1024 | Optional | URL of a CSS file defining style. |
width Type : String (Numeric) | Optional | Width of card feature. |
height Type : String (Numeric) | Optional | Height of card feature. |
MaskedAddress
The allowed characters for the address line 1, 2, and 3 are:
.',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
Data Element | Required? | Description |
|---|---|---|
addressId Type : StringUniversally Unique Identifier (UUID) | Required | Identifier used to point to the address. |
name Type : StringMaximum Length : 100 | Optional | Name of the individual receiving the delivered goods or service.
Only applicable for the shipping address. |
line1 Type : StringMaximum Length : 75 | Optional | Address line 1. |
line2 Type : StringMaximum Length : 75 | Optional | Address line 2. |
line3 Type : StringMaximum Length : 75 | Optional | Address line 3. |
city Type : StringMaximum Length : 50 | Optional | Address city. |
state Type : StringMaximum Length : 30 | Optional | Address state in ISO 3166‑2 format. |
countryCode Type : String | Optional | Address country code in ISO 3166‑1 alpha‑2 country code
format. |
zip Type : StringMaximum Length : 16 | Optional | Address zip/postal code. |
createTime Type : String (Numeric), UTC Unix epoch | Optional | Date and time the address was created. |
lastUsedTime Type : String (Numeric), UTC Unix epoch | Optional | Date and time the address was last used. |
Dcf
Data Element | Required? | Description |
|---|---|---|
applicationType Type : ApplicationType | Optional | Type of environment of the DCF. |
uri Type : StringMaximum Length : 1024 | Optional | DCF URI. |
logoUri Type : StringMaximum Length : 1024 | Optional | Logo image URI provided by DCF. |
name Type : StringMaximum Length : 60 | Optional | Legal name of the DCF. |
MaskedConsumer
Data Element | Required? | Description |
|---|---|---|
srcConsumerId Type : StringUniversally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. |
maskedConsumerIdentity Type : MaskedConsumerIdentity | Conditional | Masked value of the primary verifiable consumer identity. |
maskedEmailAddress Type : StringMaximum Length : 255 | Optional | Masked consumer email address. |
MaskedConsumerIdentity
Data Element | Required? | Description |
|---|---|---|
identityProvider Type : IdentityProvider | Optional | Entity or organization that collected and verified the identity. |
identityType Type : ConsumerIdentityType | Optional | Type of consumer identity transmitted or collected. |
maskedIdentityValue Type : StringMaximum Length : 255 | Required | Masked identity value. |
Response Attributes
Field | Required? | Description |
actionCode Type : ActionCode enum | Required | A code indicating the behavior to be handled by the SRC
Initiator. Values applicable:
|
profiles Type : List<SrcProfile > | Required | List of SRC profile(s) associated with each recognized consumer
identity. If actionCode is SUCCESS and no SRC profiles are recognized, Or If actionCode is PENDING_CONSUMER_IDV or ADD_CARD, then an empty list is returned. |
maskedValidationChannel Type : String | Conditional | Masked value of the channel (e.g. email) that the SRC System used
to deliver the validation data (e.g. OTP). Conditionality: Required when actionCode is
PENDING_CONSUMER_IDV. |
supportedValidationChannels Type : List<IdentityValidationChannel> | Conditional | List of additional channels that are supported and can be used to
perform identity validation. If returned by the SRC System, these choices may be presented to
the consumer. Conditionality: Optionally returned when actionCode is
PENDING_CONSUMER_IDV and returned by the SRC System. |
SrcProfile
Data Element | Required? | Description |
maskedCards Type : List<MaskedCard>See MaskedCard | Required | Masked card data associated with the SRC profile. May be an
empty list. |
maskedConsumer Type : MaskedConsumerSee MaskedConsumer | Optional | Masked consumer data associated with the SRC profile. |
MaskedCard
Data Element | Required? | Description |
srcDigitalCardId Type : StringUniversally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for
checkout. |
panBin Type : String (Numeric)Maximum Length : (PAN Length -10) | Required | First significant digits of the PAN included in an unmasked
form. |
panLastFour Type : String (Numeric)Length : 4 | Required | Last four digits of the PAN in an unmasked form. |
panExpirationMonth Type : String (Numeric)Length : 2 | C | Expiration month expressed as a two-digit month (MM) used for
presentation purposes. Conditionality: Required when specified for the card
(PAN). |
panExpirationYear Type : String (Numeric)Length : 4 | C | Expiration year expressed as four-digit calendar year (YYYY),
used for presentation purposes. Conditionality: Required when specified for the card
(PAN). |
tokenBinRange Type : String (Numeric)Maximum Length : (Payment Token Length -10) | C | Specific BIN range or subset of the BIN Range that has been
designated only for the purpose of issuing payment tokens in
an unmasked form. Conditionality: Required when a payment token is used. |
tokenLastFour Type : String (Numeric)Length : 4 | C | Last four digits of the payment token in an unmasked
form. Conditionality: Required when a payment token is used. |
digitalCardData Type : DigitalCardData See DigitalCardData | Required | Contains digital card information that is used in the
acceptance environment and user interface. It refers to the
actual PAN or payment token without disclosing either. |
maskedCardholderFullName Type : StringMaximum Length : 100 | Optional | Masked cardholder name. |
maskedCardholderFirstName Type : StringMaximum Length : 50 | Optional | Masked cardholder first name. |
maskedCardholderLastName Type : StringMaximum Length : 50 | Optional | Masked cardholder last name. |
paymentCardDescriptor Type : StringMaximum Length : 32 | Optional | Conveys the card brand defined within an SRC System. |
paymentCardType Type : StringMaximum Length : 32 | Optional | Conveys the card type. |
digitalCardFeatures Type : List<DigitalCardFeature >See DigitalCardFeature | Optional | Attributes related to the digital card features that should
be displayed to the consumer. |
countryCode Type : StringISO 3166-1 alpha 2 country code | Optional | Country code of issuance associated with the card issuer’s
BIN license. |
maskedBillingAddress Type : MaskedAddress See MaskedAddress | Optional | Masked billing address associated with the card. |
dcf Type : DcfSee Dcf | Optional | Digital Card Facilitator (DCF) associated with the card. It is present only when the MaskedCard is used in the
Checkout or Get Payload operation. |
paymentAccountReference Type : StringMaximum Length : 29 | Optional | A non-financial reference assigned to each unique PAN and
used to link a payment account represented by that PAN to
affiliated payment tokens. |
dateOfCardCreated Type : String (Numeric)UTC time in Unix epoch format | Required | Date when card was enrolled into the SRC System. |
dateOfCardLastUsed Type : String (Numeric)UTC time in Unix epoch format | Optional | Date when card was last used for an SRC transaction. |
DigitalCardData
Data Element | Required? | Description |
status Type : DigitalCardStatusSee DigitalCardStatus enum | Required | State of the digital card. |
presentationName Type : StringMaximum Length : 64 | Optional | Presentation text created by the consumer to enable
recognition of the PAN. This value is defined by the consumer
(e.g. nickname). |
descriptorName Type : StringMaximum Length : 64 | Required | Presentation text defined by the SRC System that describes
the PAN presented as a digital card. |
artUri Type : StringMaximum Length : 1024 | Required | URI that hosts the card art image to be used for presentation
purposes. Can be provided by SRC Issuer (SRCPI). |
artHeight Type : String (Numeric)Maximum Length : 4096 | Optional | Height of the card art in pixels. |
artWidth Type : String (Numeric)Maximum Length : 4096 | Optional | Width of the card art in pixels. |
pendingEvents Type : List<CardPendingEvent>See CardPendingEvent enum | C | Set of events that are pending completion. Conditionality: Required when the value of status is set to
PENDING. |
authenticationMethods List<AuthenticationMethod> See AuthenticationMethod | Optional | List of available authentication methods. May be provided when SRC System identifies a need to perform
verification. |
DigitalCardStatus
Enumeration Name | Possible Values |
DigitalCardStatus | ACTIVE SUSPENDED EXPIRED PENDING CANCELLED |
CardPendingEvent
Enumeration Name | Possible Values |
CardPendingEvent | PENDING_AVS PENDING_CSC PENDING_CONSUMER_IDV PENDING_ CARDHOLDER_AUTHENTICATION |
AuthenticationMethod
Data Element | Required? | Description |
authenticationMethodType Type : AuthenticationMethodTypeSee AuthenticationMethodType enum | Required | SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not. |
authenticationSubject Type : AuthenticationSubjectSee AuthenticationSubject enum | Required | Authentication subject. |
uriData Type : UriDataSee UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then
AssuranceData, AuthenticationStatus, AuthenticationResult and
any relevant session ids should be provided back asynchronously
when authentication completes. It can be achieved by cross origin post message between the
windows i.e. the caller and the authenticator. |
authenticationCredentialReference Type : StringMaximum Length : 255 | Optional | May be provided by the identity provider once an authentication
is initiated to qualify the nature of the authentication method
(e.g. for SMS_OTP, this may include the masked mobile number
"***-***-1234", which can be displayed to the consumer to aid method
selection). |
methodAttributes Type : JSONObject | Optional | Attributes associated with the authentication method type. (See
AuthenticationMethod Attributes JSON Values) |
AuthenticationMethod MethodAttributes JSON Values
The contents of methodAttributes depends on the value of authenticationMethodType and
on the API operation / SDK method being called.
The methodAttributes is included as follows:
Within the Checkout response for authenticate flow.
As part of AuthenticationMethod within the Checkout request for authenticate
flow.
If authenticationMethodType is any of the following.
CSC_VALIDATION
Data Element | Description |
cardSecurityCode Type : String, Length : 3 or 4 | Card Security Code. |
If authenticationMethodType is any of the following.
SMS_OTP
EMAIL_OTP
Data Element | Description |
otpValue Type : String, Maximum Length : 16 | OTP value. |
stepUpIdentifier Type : String | Step-up identification. |
If authenticationMethodType is any of the following.
APP_AUTHENTICATON
Data Element | Description |
stepUpIdentifier Type : String | Step-up identification. |
If authenticationMethodType is any of the following.
3DS
Data Element | Description |
challengeIndicator Type : String | Challenge indicator value related to 3DS authentication. For SRC orchestrated 3DS is authentication method, SRCIs can
specify the preference of challenge indicator here. Please refer
to EMV 3DS specification for more details. Note: If no preference provided, SRC will set up the default
value of 01 for 3DS and 04 when followed by FIDO
registration. If value is set to 05 by the SRCI then do not override the
indicator to 03 though it is a FIDO compliant device. Possible Values are: 01 - No preference 02 - No challenge requested 03 - Challenge requested (3DS Requestor Preference) 04 - Challenge requested (Mandate) 05 - No challenge requested (transactional risk analysis is
already performed) 06 - No challenge requested (Data share only) 07 - No challenge requested (strong consumer authentication is
already performed) 08 - No challenge requested (utilize trust list exemption if no
challenge required) 09 - Challenge requested (trust list prompt requested if
challenge required) |
AuthenticationMethodType
Enumeration Name | Possible Values |
AuthenticationMethodType | CSC_VALIDATION EMAIL_OTP SMS_OTP APP_AUTHENTICATION 3DS |
AuthenticationSubject
Enumeration Name | Possible Values |
AuthenticationSubject | CARD CARDHOLDER CONSUMER |
UriData
Data Element | Required? | Description |
uri Type : StringMaximum Length : 2048 | Required | Specifies the URI for the given authentication method. |
uriType Type : UriTypeSee UriType enum | Required | URI type. |
UriType
Enumeration Name | Possible Values |
UriType | APP_URI WEB_URI |
DigitalCardFeature
Data Element | Required? | Description |
content Type : StringMaximum Length : 1024 | Required | Content of the digital card feature. The value is specific for
the 'contentType’. |
contentType Type : DigitalCardFeatureContentTypeSee DigitalCardFeatureContentType enum | Required | Type of the content of the digital card feature. |
style Type : StringMaximum Length : 1024 | Optional | URL of a CSS style sheet that describes how to present the card
feature. |
width Type : String (Numeric) | Optional | Width to be applied to display of card feature. |
height Type : String (Numeric) |
DigitalCardFeatureContentType
Enumeration Name | Possible Values |
DigitalCardFeatureContentType | TEXT_STRING IMAGE_URL CONTENT_URL LINK_URL |
MaskedAddress
The allowed characters for the address line 1, 2, and 3 are:
.',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
Data Element | Required? | Description |
addressId Type : StringUniversally Unique Identifier (UUID) | Required | Identifier used to point to the address. |
name Type : StringMaximum Length : 100 | Optional | Name of the individual receiving the delivered goods or service.
Only applicable for the shipping address. |
line1 Type : StringMaximum Length : 75 | Optional | Address line 1. |
line2 Type : StringMaximum Length : 75 | Optional | Address line 2. |
line3 Type : StringMaximum Length : 75 | Optional | Address line 3. |
city Type : StringMaximum Length : 50 | O | Address city. |
state Type : StringMaximum Length : 30 | Optional | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO
3166-1 alpha 2 country code, followed by an alphanumeric string
of 3 characters representing the state or sub-division. |
countryCode Type : StringISO 3166-1 alpha 2 country code | Optional | Address country code. |
zip Type : StringMaximum Length : 16 | Optional | Address zip/postal code. |
createTime Type : String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was created. |
lastUsedTime Type : String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was last used. |
Dcf
Data Element | Required? | Description |
applicationType Type : ApplicationTypeSee ApplicationType enum | Optional | Type of the environment of the DCF. |
uri Type : StringMaximum Length : 1024 | Optional | DCF URI as provided by DCF. |
logoUri Type : StringMaximum Length : 1024 | Optional | Logo image URI provided by the DCF to support
presentation. |
name Type : StringMaximum Length : 60 | Optional | Legal Name of DCF onboarded to the SRC System. |
MaskedConsumer
Data Element | Required? | Description |
srcConsumerId Type : StringUniversally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. Note: Optionally may be returned in Get Payload operation. |
maskedConsumerIdentity Type : MaskedConsumerIdentitySee MaskedConsumerIdentity | C | Masked value of the primary verifiable consumer identity within
an SRC profile (e.g. an email address or a mobile phone
number). Conditionality: Returned in Get Payload operation. |
maskedEmailAddress Type : StringMaximum Length : 255 | Optional | Masked consumer email address. |
MaskedConsumerIdentity
Data Element | Required? | Description |
identityProvider Type : IdentityProviderSee IdentityProvider enum | Optional | Entity or organization that collected and verifies the
identity. The default value is SRC. |
identityType Type : ConsumerIdentityTypeSee ConsumerIdentityType enum | Optional | Type of consumer identity transmitted or collected. |
maskedIdentityValue Type : StringMaximum Length : 255 | Required | Masked consumer identifier value. For example, masked email
address or masked mobile phone number. |
Handle Errors
An error response notifies the user that the action relating to the request has
failed. Use the
error.reason
field to determine how to handle the
error. Errors such as INVALID_PARAMETER
or
INVALID_REQUEST
are considered integration errors.Error reasons and messages appear in a standard error structure, which is returned
when the API request could not be handled. For programmatic actions, you should only
rely on the value in the
error.reason
field. Errors include a
description in the error.message
field.You can use this field to
understand the error. You can provide your own description based on the value in the
error.reason
field. In some cases, the
error.details.message
and
error.details.location
provide additional information.Error Field | Type | Description |
|---|---|---|
error.details.location | String | The value of this field uses an XPATH expression to point to
the field that fails validation. |
error.details.message | String | The specific error associated with the field. |
error.message | String | Returned from the backend call |
error.reason | String | These options can be used to override transaction options for
the DPA that were configured during the DPA
Registration. |
This is an example error:
error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] }
Error Code | Description |
|---|---|
ACCT_FRAUD | The user account was locked or disabled. |
ACCT_INACCESSIBLE | The user account exists but is not currently
accessible. |
AUTH_ERROR | The server understands the request, but cannot
authenticate. |
AUTH_INVALID | Invalid federated id token. |
CONSUMER_ID_FORMAT_INVALID | Invalid consumer identity. |
CONSUMER_ID_FORMAT_UNSUPPORTED | Unsupported consumer identity type. |
CONSUMER_ID_MISSING | The consumerIdentity parameter is
missing. |
INVALID_PARAMETER | The value provided for one or more request parameters is
considered invalid. This error is also generated in case of
a missing required field. Typically, this is an integration
error; whenever possible, should provide client-side
validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to
change the value. |
INVALID_REQUEST | The server could not interpret the request. Usually, these are the cases, when a data field has to be in
a particular format but is not. Examples include:
The message field may provide additional clarification of
what part or field of the request is considered
incorrect. Please, refer to the API specification for the structure,
format, and constraints on the API request. |
NOT_FOUND | The requested resource/business entity does not exist. The
resource might also be hidden for security reasons. |
OTP_SEND_FAILED | The OTP could not be sent to the recipient. |
RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time.
Intended for use with rate limiting schemes.
|
REQUEST_TIMEOUT | Request timeout. |
RETRIES_EXCEEDED | The limit for the number of retries exceeded. |
SERVER_ERROR | General server error. |
SERVICE_ERROR | An error occurred on the server. Either show a generic message, or retry the same request
again (it might succeed). |
UNKNOWN_ERROR | Unknown error. |
VALIDATION_DATA_EXPIRED | The validationData is expired. |
VALIDATION_DATA_INVALID | The supplied validationData is
invalid. |
VALIDATION_DATA_MISSING | The validationData parameter is
missing. |
checkout()
dpaTransactionOptions
is an optional field in a
checkout()
request. You can include the
dpaTransactionOptions
field in the checkout()
request if your system supports it. You must consider this information if you include
the dpaTransactionOptions
field in your request:- You must include the transaction amount and currency in the backend of the request payload that is sent to/sessionsAPI. The values that are included in the request to the/sessionsAPI are used and any value included indpaTransactionOptionsare ignored.
- You must configure authentication fields in theBusiness Center. The values of these fields are retrieved from the merchant or partner profiles and not from thedpaTransactionOptionsfield.
Your
checkout()
request must have this syntax:checkout({ conditional String srcDigitalCardId; conditional JWE<Card> encryptedCard; optional Consumer consumer; optional DpaTransactionOptions dpaTransactionOptions; optional PayloadTypeIndicator payloadTypeIndicatorCheckout; conditional Window windowRef; conditional ComplianceSettings complianceSettings; optional AssuranceData assuranceData; })
Request Parameters
Your
checkout()
request can include these parameters:Request Parameters
Field | Required? | Description |
|---|---|---|
srcDigitalCardId Type : String | Required for checkout when a card is selected from a candidate
list. | A reference identifier of the card to be used for checkout. IMPORTANT
If
srcDigitalCardId and
encryptedCard both are provided
then srcDigitalCardId takes
precedence. |
encryptedCard Type : JWE | Required for a combined flow where this card is being enrolled during
checkout. | The card being enrolled with the SRC System. IMPORTANT
If srcDigitalCardId
and encryptedCard both are provided then
srcDigitalCardId takes
precedence. |
consumer Type : Consumer | Optional | Consumer identity or profile information collected by an SRCi. |
complianceSettings Type : ComplianceSettings | Conditional | The consumer’s compliance settings. |
assuranceData Type : AssuranceData | Optional | Assurance data supplied to support risk management. |
dpaTransactionOptions Type : DpaTransactionOptions | Optional | Options to override DPA‑registered transaction settings. |
transactionAmount Type : TransactionAmount | Optional | |
paymentOptions Type : List<PaymentOptions > | Optional | |
payloadTypeIndicatorCheckout Type : PayloadTypeIndicator enum | Optional | Indicates the scope of encrypted payload in the response. Possible values:
|
windowRef Type : Window | Conditional | Reference to a browsing context (iframe, popup, etc.). |
Card
Data Element | Required? | Description |
|---|---|---|
primaryAccountNumber Type : String (Numeric)Minimum Length : 9Maximum Length : 19 | Required | The account number of the card. |
panExpirationMonth Type : String (Numeric)Length : 2 | Conditional | Expiration month in MM format. |
panExpirationYear Type : String (Numeric)Length : 4 | Conditional | Expiration year in YYYY format. |
cardSecurityCode Type : String (Numeric)Maximum Length : 4 | Conditional | Card security code. |
cardholderFullName Type : StringMaximum Length : 100 | Conditional | Cardholder name. |
cardholderFirstName Type : StringMaximum Length : 50 | Optional | Cardholder first name. |
cardholderLastName Type : StringMaximum Length : 50 | Optional | Cardholder last name. |
billingAddress Type : Address | Optional | Billing address. |
paymentAccountReference Type : StringMaximum Length : 29 | Optional | Reference linking PAN to tokens. |
BillingAddress
Data Element | Required? | Description |
|---|---|---|
billingAddress Type : Address | Conditional | Billing address associated with the card. |
Address
The allowed characters for the address line 1, 2, and 3 are:
.',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
Data Element | Required? | Description |
|---|---|---|
addressId Type : StringUniversally Unique Identifier (UUID) | Optional | Reference identifier of the address in the SRC System. |
name Type : StringMaximum Length : 100 | Optional | Name of the consumer. |
line1 Type : StringMaximum Length : 75 | Required if this is a shipping address. | Address line 1 |
line2 Type : StringMaximum Length : 75 | Optional | Address line 2. |
line3 Type : StringMaximum Length : 75 | Optional | Address line 3. |
city Type : StringMaximum Length : 50 | Required if this is a shipping address. | Address city. |
state Type : StringMaximum Length : 30 | Required if this is a shipping address. | Address state. |
zip Type : StringMaximum Length : 16 | Required if applicable for that country. | Address zip/postal code. |
countryCode Type : String | Required | Address country code in ISO 3166‑1 alpha‑2 country code format. |
createTime Type : String (Numeric) | Optional | Date and time the address was created in UTC Unix epoch format. |
lastUsedTime Type : String (Numeric) | Optional | Date and time the address was last used in UTC Unix epoch format. |
Consumer
Data Element | Required? | Description |
|---|---|---|
consumerIdentity Type : ConsumerIdentity | Required | Primary verifiable consumer identity. |
firstName Type : StringMaximum Length : 50 | Optional | Consumer-provided first name. |
lastName Type : StringMaximum Length : 50 | Optional | Consumer-provided last name. |
fullName Type : StringMaximum Length : 100 | Conditional | Consumer-provided full name. |
emailAddress Type : StringMaximum Length : 255 | Optional | Consumer email address. |
mobileNumber Type : PhoneNumber | Conditional | Consumer mobile number. |
nationalIdentifier Type : StringMaximum Length : 20 | Optional | National identifier. |
countryCode Type : String | Optional | Country code associated with the consumer in ISO 3166‑1 alpha‑2
format. |
locale Type : String | Optional | Consumer locale. |
ConsumerIdentity
Data Element | Required? | Description |
|---|---|---|
identityProvider Type : IdentityProvider | Optional | Entity or organization that verified the identity. Possible value:
|
identityType Type : ConsumerIdentityType | Required | Type of consumer identity. Possible values:
|
identityValue Type : StringMaximum Length : 255 | Required | Consumer identity value. |
PhoneNumber
Data Element | Required? | Description |
|---|---|---|
countryCode Type : StringMinimum Length : 1Maximum Length : 4 | Required | Phone number country code per ITU in international calling
code format. |
phoneNumber Type : StringMinimum Length : 4Maximum Length : 14 | Required | Phone number without country code. |
ComplianceSettings
Data Element | Required? | Description |
|---|---|---|
complianceResources Type :
List<ComplianceResource > | Required | One or more compliance resources. |
ComplianceResource
Data Element | Required? | Description |
|---|---|---|
complianceType Type : ComplianceType | Required | Compliance type. Possible values:
|
uri Type : StringMaximum Length : 1024 | Required | URI or URL. |
version Type : StringMaximum Length : 10 | Optional | Version. |
datePublished Type : String | Optional | Date published in UTC Unix epoch. |
AssuranceData
Data Element | Required? | Description |
|---|---|---|
verificationData Type : List<VerificationData > | Required | Verification data structures. |
eci Type : StringMaximum Length : 2 | Optional | E-commerce authentication indicator. |
Response Attributes
Response Attributes
Field | Required? | Description |
actionCode Type : ActionCode enum | Required | A code indicating the behavior to be handled by the SRC
Initiator. Values applicable: SUCCESS ERROR |
checkoutResponse Type : JWS <CheckoutPayloadResponse> | C | Signed checkout response. Conditionality: Required when the actionCode is set to
SUCCESS. encryptedPayload will be not present within the checkoutResponse
when: payloadTypeIndicatorCheckout is set to SUMMARY. |
bindingStatus Type : BindingStatus enum | Optional | Status of the binding/unbinding request. The value BIND indicates that the consumer has chosen to be
“remembered” on the consumer device. |
ActionCode
Enumeration Name | Possible Values |
ActionCode | SUCCESS PENDING_CONSUMER_IDV PENDING_AUTHENTICATION CHANGE_CARD ADD_CARD CANCEL ERROR |
CheckoutPayloadResponse
Data Element | Required? | Description |
srciTransactionId Type : StringMaximum Length : 255 | Required | A unique identifier generated by Visa SRCi. |
maskedConsumer Type : MaskedConsumerSee MaskedConsumer | C | Masked consumer data associated with the SRC profile. Conditionality: Required for the Checkout and Get Payload
operations if the associated SRC profile contains consumer
data. |
maskedCard Type : MaskedCardSee MaskedCard | Required | Masked card data. |
shippingAddressZip Type : StringMaximum Length : 16 | C | Zip or postal code of selected shipping address. Conditionality: Required, depending on the dpaShippingPreference
option in the dpaTransactionOptions structure. |
shippingAddressCountryCode Type : StringISO 3166-1 alpha-2 country code | C | Country code of selected shipping address. Conditionality: Required, depending on the dpaShippingPreference
option in the dpaTransactionOptions structure. |
customOutputData Type : JSONObject | Optional | SRC System-specific data. |
assuranceData Type : AssuranceDataSee AssuranceData | Optional | Assurance data related to the checkout flow. |
encryptedPayload Type : JWE<Payload>See Payload | C | SRC Payload. Encrypted for the specific recipient. Conditionality: encryptedPayload will be not present when: payloadTypeIndicatorCheckout is set to SUMMARY or actionCode in checkout operation response is set to
PENDING_AUTHENTICATION. |
MaskedConsumer
Data Element | Required? | Description |
srcConsumerId Type : StringUniversally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. Note: Optionally may be returned in Get Payload operation. |
maskedConsumerIdentity Type : MaskedConsumerIdentitySee MaskedConsumerIdentity | C | Masked value of the primary verifiable consumer identity within
an SRC profile (e.g. an email address or a mobile phone
number). Conditionality: Returned in Get Payload operation. |
maskedEmailAddress Type : StringMaximum Length : 255 | Optional | Masked consumer email address. |
MaskedConsumerIdentity
Data Element | Required? | Description |
identityProvider Type : IdentityProviderSee IdentityProvider enum | Optional | Entity or organization that collected and verifies the
identity. The default value is SRC. |
identityType Type : ConsumerIdentityTypeSee ConsumerIdentityType enum | Optional | Type of consumer identity transmitted or collected. |
maskedIdentityValue Type : StringMaximum Length : 255 | Required | Masked consumer identifier value. For example, masked email
address or masked mobile phone number. |
ConsumerIdentityType
Enumeration Name | Possible Values |
ConsumerIdentityType | EMAIL_ADDRESS MOBILE_PHONE_NUMBER |
MaskedCard
Data Element | Required? | Description |
srcDigitalCardId Type : StringUniversally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for
checkout. |
panBin Type : String (Numeric)Maximum Length : (PAN Length -10) | Required | First significant digits of the PAN included in an unmasked
form. |
panLastFour Type : String (Numeric)Length : 4 | Required | Last four digits of the PAN in an unmasked form. |
panExpirationMonth Type : String (Numeric)Length : 2 | C | Expiration month expressed as a two-digit month (MM) used for
presentation purposes. Conditionality: Required when specified for the card
(PAN). |
panExpirationYear Type : String (Numeric)Length : 4 | C | Expiration year expressed as four-digit calendar year (YYYY),
used for presentation purposes. Conditionality: Required when specified for the card
(PAN). |
tokenBinRange Type : String (Numeric)Maximum Length : (Payment Token Length -10) | C | Specific BIN range or subset of the BIN Range that has been
designated only for the purpose of issuing payment tokens in
an unmasked form. Conditionality: Required when a payment token is used. |
tokenLastFour Type : String (Numeric)Length : 4 | C | Last four digits of the payment token in an unmasked
form. Conditionality: Required when a payment token is used. |
digitalCardData Type : DigitalCardDataSee DigitalCardData | Required | Contains digital card information that is used in the
acceptance environment and user interface. It refers to the
actual PAN or payment token without disclosing either. |
maskedCardholderFullName Type : StringMaximum Length : 100 | Optional | Masked cardholder name. |
maskedCardholderFirstName Type : StringMaximum Length : 50 | Optional | Masked cardholder first name. |
maskedCardholderLastName Type : StringMaximum Length : 50 | Optional | Masked cardholder last name. |
paymentCardDescriptor Type : StringMaximum Length : 32 | Optional | Conveys the card brand defined within an SRC System. |
paymentCardType Type : StringMaximum Length : 32 | Optional | Conveys the card type. |
digitalCardFeatures Type : List<DigitalCardFeature>See DigitalCardFeature | Optional | Attributes related to the digital card features that should
be displayed to the consumer. |
countryCode Type : StringISO 3166-1 alpha 2 country code | Optional | Country code of issuance associated with the card issuer’s
BIN license. |
maskedBillingAddress Type : MaskedAddressSee MaskedAddress | Optional | Masked billing address associated with the card. |
dcf Type : DcfSee Dcf | Optional | Digital Card Facilitator (DCF) associated with the card. It is present only when the MaskedCard is used in the
Checkout or Get Payload operation. |
paymentAccountReference Type : StringMaximum Length : 29 | Optional | A non-financial reference assigned to each unique PAN and
used to link a payment account represented by that PAN to
affiliated payment tokens. |
dateOfCardCreated Type : String (Numeric)UTC time in Unix epoch format | Required | Date when card was enrolled into the SRC System. |
dateOfCardLastUsed Type : String (Numeric)UTC time in Unix epoch format |
DigitalCardData
Data Element | Required? | Description |
status Type : DigitalCardStatusSee DigitalCardStatus enum | Required | State of the digital card. |
presentationName Type : StringMaximum Length : 64 | Optional | Presentation text created by the consumer to enable recognition
of the PAN. This value is defined by the consumer (e.g.
nickname). |
descriptorName Type : StringMaximum Length : 64 | Required | Presentation text defined by the SRC System that describes the
PAN presented as a digital card. |
artUri Type : StringMaximum Length : 1024 | Required | URI that hosts the card art image to be used for presentation
purposes. Can be provided by SRC Issuer (SRCPI). |
artHeight Type : String (Numeric)Maximum Length : 4096 | Optional | Height of the card art in pixels. |
artWidth Type : String (Numeric)Maximum Length : 4096 | Optional | Width of the card art in pixels. |
pendingEvents Type : List<CardPendingEvent>See CardPendingEvent enum | C | Set of events that are pending completion. Conditionality: Required when the value of status is set to
PENDING. |
authenticationMethods List<AuthenticationMethod> See AuthenticationMethod | Optional | List of available authentication methods. May be provided when SRC System identifies a need to perform
verification. |
DigitalCardStatus
Enumeration Name | Possible Values |
DigitalCardStatus | ACTIVE SUSPENDED EXPIRED PENDING CANCELLED |
CardPendingEvent
Enumeration Name | Possible Values |
CardPendingEvent | PENDING_AVS PENDING_CSC PENDING_CONSUMER_IDV PENDING_ CARDHOLDER_AUTHENTICATION |
AuthenticationMethod
Data Element | Required? | Description |
authenticationMethodType Type : AuthenticationMethodTypeSee AuthenticationMethodType enum | Required | SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not. |
authenticationSubject Type : AuthenticationSubjectSee AuthenticationSubject enum | Required | Authentication subject. |
uriData Type : UriDataSee UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then
AssuranceData, AuthenticationStatus, AuthenticationResult and
any relevant session ids should be provided back asynchronously
when authentication completes. It can be achieved by cross origin post message between the
windows i.e. the caller and the authenticator. |
authenticationCredentialReference Type : StringMaximum Length : 255 | Optional | May be provided by the identity provider once an authentication
is initiated to qualify the nature of the authentication method
(e.g. for SMS_OTP, this may include the masked mobile number
"***-***-1234", which can be displayed to the consumer to aid method
selection). |
methodAttributes Type : JSONObject | Optional | Attributes associated with the authentication method type. (See
AuthenticationMethod Attributes JSON Values) |
AuthenticationMethod MethodAttributes JSON Values
The contents of methodAttributes depends on the value of authenticationMethodType and
on the API operation / SDK method being called.
The methodAttributes is included as follows:
Within the Checkout response for authenticate flow.
As part of AuthenticationMethod within the Checkout request for authenticate
flow.
If authenticationMethodType is any of the following.
CSC_VALIDATION
Data Element | Description |
cardSecurityCode Type : String, Length : 3 or 4 | Card Security Code. |
If authenticationMethodType is any of the following.
SMS_OTP
EMAIL_OTP
Data Element | Description |
otpValue Type : String, Maximum Length : 16 | OTP value. |
stepUpIdentifier Type : String | Step-up identification. |
If authenticationMethodType is any of the following.
APP_AUTHENTICATON
Data Element | Description |
stepUpIdentifier Type : String | Step-up identification. |
If authenticationMethodType is any of the following.
3DS
Data Element | Description |
challengeIndicator Type : String | Challenge indicator value related to 3DS authentication. For SRC orchestrated 3DS is authentication method, SRCIs can
specify the preference of challenge indicator here. Please refer
to EMV 3DS specification for more details. Note: If no preference provided, SRC will set up the default
value of 01 for 3DS and 04 when followed by FIDO
registration. If value is set to 05 by the SRCI then do not override the
indicator to 03 though it is a FIDO compliant device. Possible Values are: 01 - No preference 02 - No challenge requested 03 - Challenge requested (3DS Requestor Preference) 04 - Challenge requested (Mandate) 05 - No challenge requested (transactional risk analysis is
already performed) 06 - No challenge requested (Data share only) 07 - No challenge requested (strong consumer authentication is
already performed) 08 - No challenge requested (utilize trust list exemption if no
challenge required) 09 - Challenge requested (trust list prompt requested if
challenge required) |
AuthenticationMethodType
Enumeration Name | Possible Values |
AuthenticationMethodType | CSC_VALIDATION EMAIL_OTP SMS_OTP APP_AUTHENTICATION 3DS |
AuthenticationSubject
Enumeration Name | Possible Values |
AuthenticationSubject | CARD CARDHOLDER CONSUMER |
UriData
Data Element | Required? | Description |
uri Type : StringMaximum Length : 2048 | Required | Specifies the URI for the given authentication method. |
uriType Type : UriTypeSee UriType enum | Required | URI type. |
UriType
Enumeration Name | Possible Values |
UriType | APP_URI WEB_URI |
DigitalCardFeature
Data Element | Required? | Description |
content Type : StringMaximum Length : 1024 | Required | Content of the digital card feature. The value is specific for
the 'contentType’. |
contentType Type : DigitalCardFeatureContentTypeSee DigitalCardFeatureContentType enum | Required | Type of the content of the digital card feature. |
style Type : StringMaximum Length : 1024 | Optional | URL of a CSS style sheet that describes how to present the card
feature. |
width Type : String (Numeric) | Optional | Width to be applied to display of card feature. |
height Type : String (Numeric) | Optional | Height to be applied to display of card feature. |
DigitalCardFeatureContentType
Enumeration Name | Possible Values |
DigitalCardFeatureContentType | TEXT_STRING IMAGE_URL CONTENT_URL LINK_URL |
MaskedAddress
The allowed characters for the address line 1, 2, and 3 are:
.',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
Data Element | Required? | Description |
addressId Type : StringUniversally Unique Identifier (UUID) | Required | Identifier used to point to the address. |
name Type : StringMaximum Length : 100 | Optional | Name of the individual receiving the delivered goods or service.
Only applicable for the shipping address. |
line1 Type : StringMaximum Length : 75 | Optional | Address line 1. |
line2 Type : StringMaximum Length : 75 | Optional | Address line 2. |
line3 Type : StringMaximum Length : 75 | Optional | Address line 3. |
city Type : StringMaximum Length : 50 | O | Address city. |
state Type : StringMaximum Length : 30 | Optional | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO
3166-1 alpha 2 country code, followed by an alphanumeric string
of 3 characters representing the state or sub-division. |
countryCode Type : StringISO 3166-1 alpha 2 country code | Optional | Address country code. |
zip Type : StringMaximum Length : 16 | Optional | Address zip/postal code. |
createTime Type : String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was created. |
lastUsedTime Type : String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was last used. |
Dcf
Data Element | Required? | Description |
applicationType Type : ApplicationTypeSee ApplicationType enum | Optional | Type of the environment of the DCF. |
uri Type : StringMaximum Length : 1024 | Optional | DCF URI as provided by DCF. |
logoUri Type : StringMaximum Length : 1024 | Optional | Logo image URI provided by the DCF to support
presentation. |
name Type : StringMaximum Length : 60 | Optional | Legal Name of DCF onboarded to the SRC System. |
ApplicationType
Enumeration Name | Possible Values |
ApplicationType | IOT_DEVICE MOBILE_APP WEB_BROWSER OTHER |
AssuranceData
Data Element | Required? | Description |
verificationData Type : List<VerificationData>See VerificationData | Required | Set of verification data structures relating to different types
of assurance. |
eci Type : StringMaximum Length : 2 | Optional | If present, a value indicating the result of the authentication
performed or attempted during a transaction. Use this value in
the e-commerce authorization message to VisaNet. It is one of the following values: 05 – Successful authentication 06 – Authentication attempted 07 – Authentication not performed |
VerificationData
Data Element | Required? | Description |
verificationType Type : VerificationTypeSee VerificationType enum | Required | Type of the verification data. |
verificationEntity Type : String (Numeric)Length : 2 | Required | Entity performing the verification. See VerificationData Values |
verificationEvents Type : List<String (Numeric)>Array of two digit codes | Optional | Event where the verification occurred. See VerificationData Values |
verificationMethod Type : String (Numeric)Length : 2 | Required | Method of the verification. See VerificationData Values |
verificationResults Type : String (Numeric)Length : 2 | Required | Result of the verification. See VerificationData Values |
verificationTimestamp Type : String (Numeric)UTC time in Unix epoch format | Required | Date and time when the verification was conducted. |
methodResults Type : JSONObject | Optional | Attributes associated with the authentication method (See
AuthenticationMethod MethodResults JSON Values). |
VerificationData Values
Verification Type | Verification Entity | Verification Event | Verification Method | Verification Results |
CARDHOLDER | Entity performing or initiating Cardholder authentication. Valid
values are: 01 SRC Initiator 02 SRC System (Not supported) 03 SRCPI 04 DCF (Not supported) 05 DPA (Not supported) 06– 20 EMVCo future use (Not supported) 21 – 99 SRC System specific (Not supported) | Event where the verification occurred. Possible Values are: 01 Payment transaction 02 Add card/Card enrollment 03 SRC Profile Access 04 Account Verification 05 – 20 EMVCo future use (Not supported) 21 – 99 SRC System specific (Not supported) | Card Issuer verification of the Cardholder. Possible Values are: 01 Use of an EMV 3-D Secure ACS (Not supported) 02 App based authentication 03 Federated login systems (Not supported) 04 A shared secret between the Card Issuer and the Cardholder
such as One Time Passcode (OTP), activation code 05 No authentication (Not supported) 06 Proprietary method of authentication (Not supported) 07 FIDO2 (Not supported) 08 SPC (Not supported) 09 – 20 EMVCo future use (Not supported) 21 – 99 SRC System specific (See below) 21 – Visa Token Service step–up: Device binding 22 – Visa Token Service step–up: Cardholder verification | Indicates whether the Cardholder was verified or not, and what
the results are when verified. Possible Values are: 01 Verified 02 Not Verified 03 Not performed 04 Not required 05 – 20 EMVCo future use (Not supported) 21 – 99 SRC System specific (See below) 21 – Not allowed |
AuthenticationMethod MethodResults JSON Values
The methodResults is part of VerficationData which is part of AssuranceData, which is
returned in the Checkout/Authenticate response.
Within methodResults, threeDsData may contain data such as tranStatus and
tranStatusReason when 3DS is completed.
Data Element | Description |
transStatus Type : String | Whether a transaction qualifies as an authenticated transaction
(for 3DS authentication). Format: It is one of the following string values: "Y" "R" "C" "N" "U" "A" "D" "I" |
dsTransId Type : String, UUID | ID assigned by the DS to identify the transaction (for 3DS
authentication). |
acsTransId Type : String, UUID | ID assigned by the ACS to identify the transaction (for 3DS
authentication). |
Payload
Data Element | Required? | Description |
card Type : CardSee Card | C | Card data associated with the PAN used for the purchase. Conditionality: Required when the: value of the relevant data element of type PayloadTypeIndicator
was set to FULL; and SRC System determines that a PAN-based payload must be
returned. A card is required if a token is not present. Card and token are
mutually exclusive. |
token Type : PaymentTokenSee PaymentToken | C | Payment Token data associated with the PAN used for the
purchase. Conditionality: Required when the: Value of the relevant data element of type PayloadTypeIndicator
was set to FULL; and SRC System determines that a payment token-based payload must be
returned. A token is required if a card is not present. Card and token are
mutually exclusive. |
shippingAddress Type : AddressSee Address | C | Shipping address as required for the delivery of the
goods/services being purchased. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Identified shipping address is available in the SRC Profile;
and Shipping address was requested (based on
dpaShippingPreference) |
consumerEmailAddress Type : StringMaximum Length : 255 | C | Consumer-provided email address. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Email address is available in the SRC profile; and Email address was requested (consumerEmailAddressRequested set to
true) |
consumerFirstName Type : String, Maximum Length : 50 | C | Consumer-provided first name. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Consumer first name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to
true) |
consumerLastName Type : StringMaximum Length : 50 | C | Consumer-provided last name. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Consumer last name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to
true) |
consumerFullName Type : StringMaximum Length : 100 | C | Consumer-provided name. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Consumer name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to
true) |
consumerMobileNumber Type : PhoneNumberSee Phonenumber | C | Consumer-provided mobile number. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Consumer mobile number is available in the SRC profile; and Consumer mobile number is requested (consumerPhoneNumberRequested
set to true) |
consumerNationalIdentifier Type : StringMaximum Length : 20 | Optional | Consumer national identifier as available in SRC profile. |
dynamicData Type : List<DynamicData>See DynamicData | Required | Dynamic data, generated using the dynamicDataType preference
indicated in paymentOptions. |
billingAddress Type : AddressSee Address | C | Billing address associated with the card used for the
purchase. Conditionality: Required when: The value of the relevant data element of type
PayloadTypeIndicator was set to FULL; and Billing address is available in the SRC profile; and Billing address was requested (based on dpaBillingPreference or
statically derived using the default configured during DPA
Registration) |
PaymentToken
Data Element | Required? | Description |
paymentToken Type : StringISO/IEC 7812 format | Required | The tokenized payment instrument. |
tokenExpirationMonth Type : String (Numeric)Length : 2 | Required | Expiration month expressed as a two-digit month (MM). |
tokenExpirationYear Type : String (Numeric)Length : 4 | C | Expiration year expressed as a four-digit calendar year
(YYYY). |
cardholderFullName Type : StringMaximum Length : 100 | Optional | Cardholder name. |
cardholderFirstName Type : StringMaximum Length : 50 | Optional | Cardholder first name. |
cardholderLastName Type : StringMaximum Length : 50 | Optional | Cardholder last name. |
paymentAccountReference Type : StringMaximum Length : 29 | Optional | A non-financial reference assigned to each unique PAN and
used to link a payment account represented by that PAN to
affiliated payment tokens. |
Address
The allowed characters for the address line 1, 2, and 3 are:
.',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
Data Element | Required? | Description |
addressId Type : StringUniversally Unique Identifier (UUID) | Optional | Reference identifier of the address in the SRC System. |
name Type : StringMaximum Length : 100 | Optional | Name of the consumer. |
line1 Type : StringMaximum Length : 75 | C | Address line 1 Conditionality: Required if this is a shipping address in a
valid format for the country. |
line2 Type : StringMaximum Length : 75 | Optional | Address line 2. |
line3 Type : StringMaximum Length : 75 | Optional | Address line 3. |
city Type : StringMaximum Length : 50 | C | Address city. Conditionality: Required if this is a shipping address in a
valid format for the country. |
state Type : StringMaximum Length : 30 | C | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO
3166-1 alpha 2 country code, followed by an alphanumeric string
of 3 characters representing the state or sub-division Conditionality: Required if this is a shipping address in a
valid format for the country. |
zip Type : StringMaximum Length : 16 | C | Address zip/postal code. Conditionality: Required if this is a shipping address in a
valid format for the country and has a postal code or zip
code. |
countryCode Type : StringISO 3166-1 alpha-2 country code | Required | Address country code. |
createTime Type : String (Numeric)UTC time in Unix epoch format | Optional | Date and time the address was created. |
lastUsedTime Type : String (Numeric)UTC time in Unix epoch format | Optional | Date and time the address was last used. |
PhoneNumber
Data Element | Required? | Description |
countryCode Type : StringMin Length : 1Maximum Length : 4 (International calling code format) | Required | Phone number country code as defined by the International
Telecommunication Union. |
phoneNumber Type : StringMin Length : 4Maximum Length : 14 | Required | Phone number without country code. |
DynamicDataType
Enumeration Name | Possible Values |
DynamicDataType | CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM CARD_APPLICATION_CRYPTOGRAM_LONG_FORM DYNAMIC_CARD_SECURITY_CODE CARDHOLDER_AUTHENTICATION_CRYPTOGRAM NONE |
BindingStatus
Enumeration Name | Possible Values |
BindingStatus | BIND UNBIND |
Handle Errors
An error response notifies the user that the action relating to the request has
failed. Use the
error.reason
field to determine how to handle the
error. Errors such as INVALID_PARAMETER
or
INVALID_REQUEST
are considered integration errors.Error reasons and messages appear in a standard error structure, which is returned
when the API request could not be handled. For programmatic actions, you should only
rely on the value in the
error.reason
field. Errors include a
description in the error.message
field.You can use this field to
understand the error. You can provide your own description based on the value in the
error.reason
field. In some cases, the
error.details.message
and
error.details.location
provide additional information.Error Field | Type | Description |
|---|---|---|
error.details.location | String | The value of this field uses an XPATH expression to point to
the field that fails validation. |
error.details.message | String | The specific error associated with the field. |
error.message | String | Returned from the backend call |
error.reason | String | These options can be used to override transaction options for
the DPA that were configured during the DPA
Registration. |
This is an example error:
error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] }
Error Code | Description |
|---|---|
ACCT_INACCESSIBLE | The user account exists but is not currently
accessible. |
AUTH_ERROR | The server understands the request, but cannot
authenticate. |
AUTH_INVALID | Invalid federated id token. |
AUTHENTICATION_METHOD_NOT_SUPPORTED | The supplied authentication method is not supported. |
BILLING_ADDRESS_REQUIRED | The billing address must be provided. |
CARD_ADD_FAILED | Unable to add the card. |
CARD_EXP_INVALID | Invalid card expiry date. |
CARD_INVALID | Invalid primaryAccountNumber
parameter. |
CARD_MISSING | The srcDigitalCardId or
encryptedCard parameter is required but
is missing. |
CARD_NOT_RECOGNIZED | The provided srcDigitalCardId is not
recognized. |
CARD_NOT_RECOGNIZED | The provided srcDigitalCardId is not
recognized. |
CARD_SECURITY_CODE_MISSING | Card Security Code (CSC) must be supplied in the
encryptedCard parameter. |
INVALID_PARAMETER | The value provided for one or more request parameters is
considered invalid. This error is also generated in case of
a missing required field. Typically, this is an integration
error; whenever possible, should provide client-side
validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to
change the value. |
INVALID_REQUEST | The server could not interpret the request. Usually, these are the cases, when a data field has to be in
a particular format but is not. Examples include:
The message field may provide additional clarification of
what part or field of the request is considered
incorrect. Please, refer to the API specification for the structure,
format, and constraints on the API request. |
NOT_FOUND | The requested resource/business entity does not exist. The
resource might also be hidden for security reasons. |
OTP_SEND_FAILED | The OTP could not be sent to the recipient. |
RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time.
Intended for use with rate limiting schemes.
|
REQUEST_TIMEOUT | Request timeout. |
RETRIES_EXCEEDED | The limit for the number of retries exceeded. |
SERVER_ERROR | General server error. |
SERVICE_ERROR | An error occurred on the server. Either show a generic message, or retry the same request
again (it might succeed). |
TERMS_AND_CONDITIONS_ NOT_ACCEPTED | Terms and conditions not accepted. |
UNABLE_TO_CONNECT | Unable to connect to or launch card experience. |
UNKNOWN_ERROR | Unknown error. |
VALIDATION_DATA_EXPIRED | The validationData is expired. |
VALIDATION_DATA_INVALID | The supplied validationData is
invalid. |
VALIDATION_DATA_MISSING | The validationData parameter is
missing. |
initiateIdentityValidation()
Your
initiateIdentityValidation()
request must have this
syntax:initiateIdentityValidation({ optional String requestedValidationChannelId })
Request Parameters
Your
initiateIdentityValidation()
request can include these
parameters:Request Parameters
Field | Required? | Description |
|---|---|---|
requestedValidationChannelId Type : String | Optional | Identifier of the channel over which the identity validation
should be initiated. |
Response Attributes
Field | Required? | Description |
|---|---|---|
maskedValidationChannel Type : String | Required | Masked value of the channel (e.g. email) that the SRC
System used to deliver the validation data (e.g.
OTP) Example: "sen*****@mailinator.com" |
Handle Errors
An error response notifies the user that the action relating to the request has
failed. Use the
error.reason
field to determine how to handle the
error. Errors such as INVALID_PARAMETER
or
INVALID_REQUEST
are considered integration errors.Error reasons and messages appear in a standard error structure, which is returned
when the API request could not be handled. For programmatic actions, you should only
rely on the value in the
error.reason
field. Errors include a
description in the error.message
field.You can use this field to
understand the error. You can provide your own description based on the value in the
error.reason
field. In some cases, the
error.details.message
and
error.details.location
provide additional information.Error Field | Type | Description |
|---|---|---|
error.details.location | String | The value of this field uses an XPATH expression to point to
the field that fails validation. |
error.details.message | String | The specific error associated with the field. |
error.message | String | Returned from the backend call |
error.reason | String | These options can be used to override transaction options for
the DPA that were configured during the DPA
Registration. |
This is an example error:
error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] }
Error Code | Description |
|---|---|
AUTH_ERROR | The server understands the request, but cannot
authenticate. |
INVALID_PARAMETER | The value provided for one or more request parameters is
considered invalid. This error is also generated in case of
a missing required field. Typically, this is an integration
error; whenever possible, should provide client-side
validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to
change the value. |
INVALID_REQUEST | The server could not interpret the request. Usually, these are the cases, when a data field has to be in
a particular format but is not. Examples include:
The message field may provide additional clarification of
what part or field of the request is considered
incorrect. Please, refer to the API specification for the structure,
format, and constraints on the API request. |
NOT_FOUND | The requested resource/business entity does not exist. The
resource might also be hidden for security reasons. |
RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time.
Intended for use with rate limiting schemes.
|
REQUEST_TIMEOUT | Request timeout. |
SERVER_ERROR | General server error. |
SERVICE_ERROR | An error occurred on the server. Either show a generic message, or retry the same request
again (it might succeed). |
UNKNOWN_ERROR | Unknown error. |
unbindAppInstance()
Your
unbindAppInstance()
request must have this syntax:unbindAppInstance()
Handle Errors
An error response notifies the user that the action relating to the request has
failed. Use the
error.reason
field to determine how to handle the
error. Errors such as INVALID_PARAMETER
or
INVALID_REQUEST
are considered integration errors.Error reasons and messages appear in a standard error structure, which is returned
when the API request could not be handled. For programmatic actions, you should only
rely on the value in the
error.reason
field. Errors include a
description in the error.message
field.You can use this field to
understand the error. You can provide your own description based on the value in the
error.reason
field. In some cases, the
error.details.message
and
error.details.location
provide additional information.Error Field | Type | Description |
|---|---|---|
error.details.location | String | The value of this field uses an XPATH expression to point to
the field that fails validation. |
error.details.message | String | The specific error associated with the field. |
error.message | String | Returned from the backend call |
error.reason | String | These options can be used to override transaction options for
the DPA that were configured during the DPA
Registration. |
This is an example error:
error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] }
Error Code | Description |
|---|---|
AUTH_ERROR | The server understands the request, but cannot
authenticate. |
INVALID_PARAMETER | The value provided for one or more request parameters is
considered invalid. This error is also generated in case of
a missing required field. Typically, this is an integration
error; whenever possible, should provide client-side
validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to
change the value. |
INVALID_REQUEST | The server could not interpret the request. Usually, these are the cases, when a data field has to be in
a particular format but is not. Examples include:
The message field may provide additional clarification of
what part or field of the request is considered
incorrect. Please, refer to the API specification for the structure,
format, and constraints on the API request. |
NOT_FOUND | The requested resource/business entity does not exist. The
resource might also be hidden for security reasons. |
RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time.
Intended for use with rate limiting schemes.
|
REQUEST_TIMEOUT | Request timeout. |
SERVER_ERROR | General server error. |
SERVICE_ERROR | An error occurred on the server. Either show a generic message, or retry the same request
again (it might succeed). |
UNKNOWN_ERROR | Unknown error. |
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.