On This Page
FILTER BY TAG
pilot

getCards()

Your
getCards()
 request must have this syntax:
getCards({
    required ConsumerIdentity consumerIdentity;
    conditional String validationData;
  })
pilot

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

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

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