On This Page
FILTER BY TAG
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.
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.
RELATED TO THIS PAGE