pilot Request Parameters {#uctp-java-getcards} ======================================== 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. |