Unified Click to Pay
Developer Guide

This section describes how to use this guide and where to find further information.
Audience and Purpose
This document is written for merchants and ISVs who want to enable
Unified Click to Pay
so that they can accept payments on their e-commerce page.
Conventions
This statement is used in this document:
IMPORTANT
An
Important
statement 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
, 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

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
:
  1. Log in to the
    Business Center
    :
    If you are unable to access this page, contact your sales representative.
  2. Navigate to
    Payment Configuration >
    Unified Checkout
    .
  3. In the Click to Pay section, click
    Set Up
    .
  4. Enter your business name and website URL.
  5. Click
    Submit
    .
  6. Contact your implementation contact
    or technical account manager
    to request that you be enabled for tokenization within
    Click to Pay
    . Your implementation contact
    or technical account manager
    will confirm that you were configured successfully and that you can now accept digital payments with
    Click to Pay
    .
    IMPORTANT
    Click to Pay
    uses network tokenization for transactions. These network tokens are stored in the vault of the token requestor ID (TRID) for the card scheme.

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
:
  1. Log in to the
    Business Center
    :
    If you are unable to access this page, contact your sales representative.
  2. In the
    Business Center
    , from the navigation panel choose
    Key Management
    .
  3. Click
    + Generate key
    .
  4. Under Alternate Key Types, choose
    Token Management MLE
    and click
    Generate key
    .
  5. Enter your public key in Base64 format and click
    Create key
    .

Set Up Customer Authentication for
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.
  1. Log in to the
    Business Center
    :
    If you are unable to access this page, contact your sales representative.
  2. In the
    Business Center
    , from the navigation panel choose
    Payment Configuration
    >
    Unified Checkout
    .
    You must have
    Click to Pay
    enabled as a digital payment method to use this method of authentication. Click
    Manage
    to view the digital payment methods that you have enabled.
    Manage Unified Checkout Digital Payments Solutions
    If
    Click to Pay
    is not enabled, click
    On
    next to
    Click to Pay
    .
    Manage Available Digital Payments Solutions
  3. Enter the account details and click
    Update
    .
  4. Click
    Set up
    under Value Added Solutions. The Value Added Solutions page appears.
    Value Added Solutions Page
  5. Click
    Set up
    to set up
    3-D Secure
    . The 3DS page appears.
  6. Enter the required information in the Merchant Details section. You must enter the information that is provided to you by
    your acquirer or processor
    .

    Step Result

    This completes the authentication setup for the entered acquirer merchant ID and BIN. If you do not know what these values are, you must contact
    your acquirer
    . Completing this information enables
    Visa Acceptance Solutions
    to send Visa the information that is required for authentication.
    IMPORTANT
    Charges for
    3-D Secure
    may apply. You must speak with
    your acquirer
    for more information about the charges associated with
    3-D Secure
    .

Unified Click to Pay
Customer Workflows

This 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 recognized
    Click to Pay
    customer.
  • The customer is not recognized by
    Unified Click to Pay
    but is a
    Click to Pay
    customer.
  • The customer is a new user enrolling in
    Click to Pay
    .

Recognized
Click to Pay
Customer

This 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 used
    Click to Pay
    on their device through any
    Click to Pay
    channel.
  • If the customer chose to have their device remembered during a previous transaction.

Figure:

Recognized
Click to Pay
Customer
  1. 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.
  2. Set up your client side by initiating the
    Unified Click to Pay
    JavaScript SDK. For a recognized customer, you will load these functions from the SDK:
    • initialize(capture context JWT)
    • getCards(consumer identity - email)
    • checkout(card details)
    For information about setting up the client side, see Client-Side Set Up.

Unrecognized
Click to Pay
Customer

This 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
  1. 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.
  2. Set up your client side by initiating the
    Unified Click to Pay
    JavaScript 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)
    For information about setting up the client side, see Client-Side Set Up.

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
  1. 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.
  2. Set up your client side by initiating the
    Unified Click to Pay
    JavaScript SDK. For a guest customer, you will load these functions from the SDK:
    • initialize(capture context JWT)
    • getCards(consumer identity - email)
    • checkout(card details)
    For information about setting up the client side, see Client-Side Set Up.

Unified Click to Pay
Integration

This 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:
  1. 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.
  2. You invoke the
    Unified Click to Pay
    JavaScript 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:
  1. Load the JavaScript library.
  2. 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

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]", identity
Type
: "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, dynamicData
Type
: '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
    /sessions
    API. The values that are included in the request to the
    /sessions
    API are used and any value included in
    dpaTransactionOptions
    are ignored.
  • You must configure authentication fields in the
    Business Center
    . The values of these fields are retrieved from the merchant or partner profiles and not from the
    dpaTransactionOptions
    field.
Your
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:
  • FULL
  • NONE
  • POSTAL_COUNTRY
dpaLocale
Type
: String
Optional
Merchant preferred locale in ISO 639‑1 and ISO 3166‑1 format.
["en_US", "fr_CA"]
merchantCategoryCode
Type
: String
Length
: 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.
  • CARD_APPLICATION_CRYPTOGRAM_LONG_FORM
  • CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM
  • CARDHOLDER_AUTHENTICATION_CRYPTOGRAM
  • DYNAMIC_CARD_SECURITY_CODE
  • NONE

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

Data Element
Required?
Description
authenticationMethodType
Type
:
AuthenticationMethodType
Required
Indicates whether C2P should perform managed authentication.
Possible values:
  • 3DS
  • APP_AUTHENTICATION
  • CSC_VALIDATION
  • EMAIL_OTP
  • SMS_OTP
authenticationSubject
Type
:
AuthenticationSubject
Required
Authentication subject.
Possible values:
  • CARD
  • CARDHOLDER
  • CONSUMER
uriData
Type
:
UriData
Optional
URI used to launch authentication.
Relevant data is returned asynchronously.
authenticationCredentialReference
Type
: String
Maximum 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
: String
Maximum Length
: 4
Card security code.
SMS_OTP
otpValue
Type
: String
Maximum 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:
  • 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)

UriData

Data Element
Required?
Description
uri
Type
: String
Maximum Length
: 2048
Required
Specifies the URI for the given authentication method.
uriType
Type
:
UriType
Required
URI type.
Possible values:
  • APP_URI
  • WEB_URI

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:
  • 12345
  • 012345
  • 0012345
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
: String
Maximum 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
:
  • 01
    : Fixed
  • 02
    : Variable
Possible values for
frequencyInd
:
  • 01
    : Fixed frequency
  • 02
    : Variable/unknown frequency
Example:
{ "recurringInd": { "amountInd": "01", "frequencyInd": "02" } }

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 Response Fields
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 Codes
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:
  • Base64 decoding failed
  • The field is not in a particular format.
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.
  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:
    Retry delay in milliseconds = (2 ^
    n
    ) * 1000 +
    randomDelayMs
    , where n is your retry count, such as 0, 1, 2, 3, …, and
    random- DelayMs
    is random delay in milliseconds, such as an integer between 0 and 1,000.
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.
Possible values:
  • EMAIL_ADDRESS
  • MOBILE_PHONE_NUMBER
identityValue
Type
: String
Maximum 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
: String
Universally 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
: String
Maximum Length
: 100
Optional
Masked full cardholder name.
maskedCardholderFirstName
Type
: String
Maximum Length
: 50
Optional
Masked first name.
maskedCardholderLastName
Type
: String
Maximum Length
: 50
Optional
Masked last name.
paymentCardDescriptor
Type
: String
Maximum Length
: 32
Optional
Card brand descriptor.
paymentCardType
Type
: String
Maximum 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
: String
Maximum 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:
  • ACTIVE
  • CANCELLED
  • EXPIRED
  • PENDING
  • SUSPENDED
presentationName
Type
: String
Maximum Length
: 64
Optional
Consumer-defined text to help recognize the card.
descriptorName
Type
: String
Maximum Length
: 64
Required
System‑defined card description.
artUri
Type
: String
Maximum 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:
  • PENDING_AVS
  • PENDING_CSC
  • PENDING_CONSUMER_IDV
  • PENDING_ CARDHOLDER_AUTHENTICATION
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:
  • 3DS
  • APP_AUTHENTICATION
  • CSC_VALIDATION
  • EMAIL_OTP
  • SMS_OTP
authenticationSubject
Type
:
AuthenticationSubject
Required
Authentication subject.
Possible values:
  • CARD
  • CARDHOLDER
  • CONSUMER
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
: String
Maximum 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
: String
Maximum Length
: 4
Card security code.
SMS_OTP
otpValue
Type
: String
Maximum 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:
  • 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)

UriData

Data Element
Required?
Description
uri
Type
: String
Maximum Length
: 2048
Required
Specifies the URI for the given authentication method.
uriType
Type
:
UriType
Required
URI type.
Possible values:
  • APP_URI
  • WEB_URI

DigitalCardFeature

Data Element
Required?
Description
content
Type
: String
Maximum Length
: 1024
Required
Content of the digital card feature.
contentType
Type
:
DigitalCardFeatureContentType
Required
Content type of the digital card feature.
Possible values:
  • CONTENT_URL
  • IMAGE_URL
  • LINK_URL
  • TEXT_STRING
style
Type
: String
Maximum 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
: String
Universally Unique Identifier (UUID)
Required
Identifier used to point to the address.
name
Type
: String
Maximum Length
: 100
Optional
Name of the individual receiving the delivered goods or service. Only applicable for the shipping address.
line1
Type
: String
Maximum Length
: 75
Optional
Address line 1.
line2
Type
: String
Maximum Length
: 75
Optional
Address line 2.
line3
Type
: String
Maximum Length
: 75
Optional
Address line 3.
city
Type
: String
Maximum Length
: 50
Optional
Address city.
state
Type
: String
Maximum 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
: String
Maximum 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
: String
Maximum Length
: 1024
Optional
DCF URI.
logoUri
Type
: String
Maximum Length
: 1024
Optional
Logo image URI provided by DCF.
name
Type
: String
Maximum Length
: 60
Optional
Legal name of the DCF.

MaskedConsumer

Data Element
Required?
Description
srcConsumerId
Type
: String
Universally 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
: String
Maximum 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
: String
Maximum 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:
  • SUCCESS
  • PENDING_CONSUMER_IDV
  • ADD_CARD
  • ERROR
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
: MaskedConsumer
See MaskedConsumer
Optional
Masked consumer data associated with the SRC profile.

MaskedCard

Data Element
Required?
Description
srcDigitalCardId
Type
: String
Universally 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
: String
Maximum Length
: 100
Optional
Masked cardholder name.
maskedCardholderFirstName
Type
: String
Maximum Length
: 50
Optional
Masked cardholder first name.
maskedCardholderLastName
Type
: String
Maximum Length
: 50
Optional
Masked cardholder last name.
paymentCardDescriptor
Type
: String
Maximum Length
: 32
Optional
Conveys the card brand defined within an SRC System.
paymentCardType
Type
: String
Maximum 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
: String
ISO 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
: Dcf
See
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
: String
Maximum 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
: DigitalCardStatus
See DigitalCardStatus enum
Required
State of the digital card.
presentationName
Type
: String
Maximum 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
: String
Maximum Length
: 64
Required
Presentation text defined by the SRC System that describes the PAN presented as a digital card.
artUri
Type
: String
Maximum 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
: AuthenticationMethodType
See AuthenticationMethodType enum
Required
SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not.
authenticationSubject
Type
: AuthenticationSubject
See AuthenticationSubject enum
Required
Authentication subject.
uriData
Type
: UriData
See 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
: String
Maximum 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
: String
Maximum Length
: 2048
Required
Specifies the URI for the given authentication method.
uriType
Type
: UriType
See UriType enum
Required
URI type.

UriType

Enumeration Name
Possible Values
UriType
APP_URI
WEB_URI

DigitalCardFeature

Data Element
Required?
Description
content
Type
: String
Maximum Length
: 1024
Required
Content of the digital card feature. The value is specific for the 'contentType’.
contentType
Type
: DigitalCardFeatureContentType
See DigitalCardFeatureContentType enum
Required
Type of the content of the digital card feature.
style
Type
: String
Maximum 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
: String
Universally Unique Identifier (UUID)
Required
Identifier used to point to the address.
name
Type
: String
Maximum Length
: 100
Optional
Name of the individual receiving the delivered goods or service. Only applicable for the shipping address.
line1
Type
: String
Maximum Length
: 75
Optional
Address line 1.
line2
Type
: String
Maximum Length
: 75
Optional
Address line 2.
line3
Type
: String
Maximum Length
: 75
Optional
Address line 3.
city
Type
: String
Maximum Length
: 50
O
Address city.
state
Type
: String
Maximum 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
: String
ISO 3166-1 alpha 2 country code
Optional
Address country code.
zip
Type
: String
Maximum 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
: ApplicationType
See ApplicationType enum
Optional
Type of the environment of the DCF.
uri
Type
: String
Maximum Length
: 1024
Optional
DCF URI as provided by DCF.
logoUri
Type
: String
Maximum Length
: 1024
Optional
Logo image URI provided by the DCF to support presentation.
name
Type
: String
Maximum Length
: 60
Optional
Legal Name of DCF onboarded to the SRC System.

MaskedConsumer

Data Element
Required?
Description
srcConsumerId
Type
: String
Universally Unique Identifier (UUID)
Optional
Reference identifier generated by the SRC System.
Note: Optionally may be returned in Get Payload operation.
maskedConsumerIdentity
Type
: MaskedConsumerIdentity
See 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
: String
Maximum Length
: 255
Optional
Masked consumer email address.

MaskedConsumerIdentity

Data Element
Required?
Description
identityProvider
Type
: IdentityProvider
See IdentityProvider enum
Optional
Entity or organization that collected and verifies the identity.
The default value is SRC.
identityType
Type
: ConsumerIdentityType
See ConsumerIdentityType enum
Optional
Type of consumer identity transmitted or collected.
maskedIdentityValue
Type
: String
Maximum 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 Response Fields
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 Codes
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:
  • Base64 decoding failed
  • The field is not in a particular format.
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.
  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:
    Retry delay in milliseconds = (2 ^
    n
    ) * 1000 +
    randomDelayMs
    , where n is your retry count, such as 0, 1, 2, 3, …, and
    random- DelayMs
    is random delay in milliseconds, such as an integer between 0 and 1,000.
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
    /sessions
    API. The values that are included in the request to the
    /sessions
    API are used and any value included in
    dpaTransactionOptions
    are ignored.
  • You must configure authentication fields in the
    Business Center
    . The values of these fields are retrieved from the merchant or partner profiles and not from the
    dpaTransactionOptions
    field.
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

Request Parameters and Descriptions
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:
  • FULL
  • SUMMARY
windowRef
Type
:
Window
Conditional
Reference to a browsing context (iframe, popup, etc.).

Card

Data Element
Required?
Description
primaryAccountNumber
Type
: String (Numeric)
Minimum Length
: 9
Maximum 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
: String
Maximum Length
: 100
Conditional
Cardholder name.
cardholderFirstName
Type
: String
Maximum Length
: 50
Optional
Cardholder first name.
cardholderLastName
Type
: String
Maximum Length
: 50
Optional
Cardholder last name.
billingAddress
Type
: Address
Optional
Billing address.
paymentAccountReference
Type
: String
Maximum 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
: String
Universally Unique Identifier (UUID)
Optional
Reference identifier of the address in the SRC System.
name
Type
: String
Maximum Length
: 100
Optional
Name of the consumer.
line1
Type
: String
Maximum Length
: 75
Required if this is a shipping address.
Address line 1
line2
Type
: String
Maximum Length
: 75
Optional
Address line 2.
line3
Type
: String
Maximum Length
: 75
Optional
Address line 3.
city
Type
: String
Maximum Length
: 50
Required if this is a shipping address.
Address city.
state
Type
: String
Maximum Length
: 30
Required if this is a shipping address.
Address state.
zip
Type
: String
Maximum 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
: String
Maximum Length
: 50
Optional
Consumer-provided first name.
lastName
Type
: String
Maximum Length
: 50
Optional
Consumer-provided last name.
fullName
Type
: String
Maximum Length
: 100
Conditional
Consumer-provided full name.
emailAddress
Type
: String
Maximum Length
: 255
Optional
Consumer email address.
mobileNumber
Type
:
PhoneNumber
Conditional
Consumer mobile number.
nationalIdentifier
Type
: String
Maximum 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:
  • SRC
identityType
Type
:
ConsumerIdentityType
Required
Type of consumer identity.
Possible values:
  • EMAIL_ADDRESS
  • MOBILE_PHONE_NUMBER
identityValue
Type
: String
Maximum Length
: 255
Required
Consumer identity value.

PhoneNumber

Data Element
Required?
Description
countryCode
Type
: String
Minimum Length
: 1
Maximum Length
: 4
Required
Phone number country code per ITU in international calling code format.
phoneNumber
Type
: String
Minimum Length
: 4
Maximum 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:
  • PRIVACY_POLICY
  • REMEMBER_ME
  • TERMS_AND_CONDITIONS
uri
Type
: String
Maximum Length
: 1024
Required
URI or URL.
version
Type
: String
Maximum 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
: String
Maximum 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
: String
Maximum Length
: 255
Required
A unique identifier generated by Visa SRCi.
maskedConsumer
Type
: MaskedConsumer
See 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
: MaskedCard
See MaskedCard
Required
Masked card data.
shippingAddressZip
Type
: String
Maximum Length
: 16
C
Zip or postal code of selected shipping address.
Conditionality: Required, depending on the dpaShippingPreference option in the dpaTransactionOptions structure.
shippingAddressCountryCode
Type
: String
ISO 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
: AssuranceData
See 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
: String
Universally Unique Identifier (UUID)
Optional
Reference identifier generated by the SRC System.
Note: Optionally may be returned in Get Payload operation.
maskedConsumerIdentity
Type
: MaskedConsumerIdentity
See 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
: String
Maximum Length
: 255
Optional
Masked consumer email address.

MaskedConsumerIdentity

Data Element
Required?
Description
identityProvider
Type
: IdentityProvider
See IdentityProvider enum
Optional
Entity or organization that collected and verifies the identity.
The default value is SRC.
identityType
Type
: ConsumerIdentityType
See ConsumerIdentityType enum
Optional
Type of consumer identity transmitted or collected.
maskedIdentityValue
Type
: String
Maximum 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
: String
Universally 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
: String
Maximum Length
: 100
Optional
Masked cardholder name.
maskedCardholderFirstName
Type
: String
Maximum Length
: 50
Optional
Masked cardholder first name.
maskedCardholderLastName
Type
: String
Maximum Length
: 50
Optional
Masked cardholder last name.
paymentCardDescriptor
Type
: String
Maximum Length
: 32
Optional
Conveys the card brand defined within an SRC System.
paymentCardType
Type
: String
Maximum 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
: String
ISO 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
: Dcf
See 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
: String
Maximum 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
: DigitalCardStatus
See DigitalCardStatus enum
Required
State of the digital card.
presentationName
Type
: String
Maximum 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
: String
Maximum Length
: 64
Required
Presentation text defined by the SRC System that describes the PAN presented as a digital card.
artUri
Type
: String
Maximum 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
: AuthenticationMethodType
See AuthenticationMethodType enum
Required
SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not.
authenticationSubject
Type
: AuthenticationSubject
See AuthenticationSubject enum
Required
Authentication subject.
uriData
Type
: UriData
See 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
: String
Maximum 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
: String
Maximum Length
: 2048
Required
Specifies the URI for the given authentication method.
uriType
Type
: UriType
See UriType enum
Required
URI type.

UriType

Enumeration Name
Possible Values
UriType
APP_URI
WEB_URI

DigitalCardFeature

Data Element
Required?
Description
content
Type
: String
Maximum Length
: 1024
Required
Content of the digital card feature. The value is specific for the 'contentType’.
contentType
Type
: DigitalCardFeatureContentType
See DigitalCardFeatureContentType enum
Required
Type of the content of the digital card feature.
style
Type
: String
Maximum 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
: String
Universally Unique Identifier (UUID)
Required
Identifier used to point to the address.
name
Type
: String
Maximum Length
: 100
Optional
Name of the individual receiving the delivered goods or service. Only applicable for the shipping address.
line1
Type
: String
Maximum Length
: 75
Optional
Address line 1.
line2
Type
: String
Maximum Length
: 75
Optional
Address line 2.
line3
Type
: String
Maximum Length
: 75
Optional
Address line 3.
city
Type
: String
Maximum Length
: 50
O
Address city.
state
Type
: String
Maximum 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
: String
ISO 3166-1 alpha 2 country code
Optional
Address country code.
zip
Type
: String
Maximum 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
: ApplicationType
See ApplicationType enum
Optional
Type of the environment of the DCF.
uri
Type
: String
Maximum Length
: 1024
Optional
DCF URI as provided by DCF.
logoUri
Type
: String
Maximum Length
: 1024
Optional
Logo image URI provided by the DCF to support presentation.
name
Type
: String
Maximum 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
: String
Maximum 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
: VerificationType
See 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
: Card
See 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
: PaymentToken
See 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
: Address
See 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
: String
Maximum 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
: String
Maximum 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
: String
Maximum 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
: PhoneNumber
See 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
: String
Maximum 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
: Address
See 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
: String
ISO/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
: String
Maximum Length
: 100
Optional
Cardholder name.
cardholderFirstName
Type
: String
Maximum Length
: 50
Optional
Cardholder first name.
cardholderLastName
Type
: String
Maximum Length
: 50
Optional
Cardholder last name.
paymentAccountReference
Type
: String
Maximum 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
: String
Universally Unique Identifier (UUID)
Optional
Reference identifier of the address in the SRC System.
name
Type
: String
Maximum Length
: 100
Optional
Name of the consumer.
line1
Type
: String
Maximum Length
: 75
C
Address line 1
Conditionality: Required if this is a shipping address in a valid format for the country.
line2
Type
: String
Maximum Length
: 75
Optional
Address line 2.
line3
Type
: String
Maximum Length
: 75
Optional
Address line 3.
city
Type
: String
Maximum Length
: 50
C
Address city.
Conditionality: Required if this is a shipping address in a valid format for the country.
state
Type
: String
Maximum 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
: String
Maximum 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
: String
ISO 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
: String
Min
Length
: 1
Maximum Length
: 4
(International calling code format)
Required
Phone number country code as defined by the International Telecommunication Union.
phoneNumber
Type
: String
Min
Length
: 4
Maximum 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 Response Fields
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 Codes
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:
  • Base64 decoding failed
  • The field is not in a particular format.
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.
  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:
    Retry delay in milliseconds = (2 ^
    n
    ) * 1000 +
    randomDelayMs
    , where n is your retry count, such as 0, 1, 2, 3, …, and
    random- DelayMs
    is random delay in milliseconds, such as an integer between 0 and 1,000.
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 Response Fields
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 Codes
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:
  • Base64 decoding failed
  • The field is not in a particular format.
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.
  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:
    Retry delay in milliseconds = (2 ^
    n
    ) * 1000 +
    randomDelayMs
    , where n is your retry count, such as 0, 1, 2, 3, …, and
    random- DelayMs
    is random delay in milliseconds, such as an integer between 0 and 1,000.
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 Response Fields
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 Codes
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:
  • Base64 decoding failed
  • The field is not in a particular format.
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.
  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:
    Retry delay in milliseconds = (2 ^
    n
    ) * 1000 +
    randomDelayMs
    , where n is your retry count, such as 0, 1, 2, 3, …, and
    random- DelayMs
    is random delay in milliseconds, such as an integer between 0 and 1,000.
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.