On This Page
FILTER BY TAG
pilot

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.
The
checkout()
 method uses three types of keys:
  • JWT validation keys
    : The checkout response from
    vsdk.checkout()
     is a signed JWT with the payment credentials. The response must be verified server-side by retrieving the RSA public key from
    https://api.cybersource.com
    /flex/v2/public-keys
     using the
    kid
     from the header of each JWT.
    Cybersource
     recommends that you do not skip this step, as this verification exposes the integration to payload tampering. For information about JWT validation keys, see JWT Validation Keys.
  • Client-side PAN encryption keys
    : When you add a card to
    Unified Click to Pay
    , the customer manually enters their card details in the UI. The raw PAN must be JWE-encrypted in the browser before it is passed to
    checkout(encryptedCard)
    . The encryption key is a per-network RSA JWK from the
    /sessions
     API response from
    paymentConfigurations.[SRCVISA|SRCMASTERCARD|SRCAMEX].panEncryptionKey
    . The encyrypted key is selected using the PAN's BIN range. For information about client-side PAN encryption keys, see Client-Side PAN Encryption Keys.
  • Token Management MLE keys
    : The
    checkout()
     response can include PCI/PII data that is in the
    encryptedPayload
     field. This data is encrypted by
    Cybersource
     using the merchant's RSA public key uploaded to the
    Cybersource
    Business Center
    . The merchant decrypts it server-side using their corresponding private key. For information about Token Management MLE keys, see Token Management MLE Keys.
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;
 })
pilot

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&lt;
PaymentOptions
&gt;
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&lt;
ComplianceResource
&gt;
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&lt;
VerificationData
&gt;
Required
Verification data structures.
eci
Type
: String
Maximum Length
: 2
Optional
E-commerce authentication indicator.
pilot

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 &lt;CheckoutPayloadResponse&gt;
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&lt;Payload&gt;
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&lt;DigitalCardFeature&gt;
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&lt;CardPendingEvent&gt;
See CardPendingEvent enum
C
Set of events that are pending completion.
Conditionality: Required when the value of status is set to PENDING.
authenticationMethods
List&lt;AuthenticationMethod&gt;
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&lt;VerificationData&gt;
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&lt;String (Numeric)&gt;
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&lt;DynamicData&gt;
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
pilot

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.
RELATED TO THIS PAGE