Data Elements - Unified Click to Pay
Unified Click to Pay
Merchants and Payment Service Providers
Data Elements - Unified Click to Pay
All primitive and composite data elements are defined below. The request parameters and response attributes (returned if processing is successful) are provided in a single JSON object.
In the request parameters and response attributes tables for each SDK method, the column headed R/C/O in each table refers to whether the parameter/attribute is required, conditional or optional. The following notation is used:
- R = Required – always present.
- C = Conditional – present under certain conditions (as specified in the description).
- O = Optional – can be present.
Data Objects
The following section introduces the common data objects used across the APIs defined in the SDK API Specification. Each table defines a single data object.
Address
The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/
| Data Element | R/C/O | Description |
| addressId
Type: String
Universally Unique Identifier (UUID) | O | Reference identifier of the address in the SRC System. |
| name
Type: String
Max Length = 100 | O | Name of the consumer. |
| line1
Type: String
Max Length = 75 | C | Address line 1
Conditionality: Required if this is a shipping address in a valid format for the country. |
| line2
Type: String
Max Length = 75 | O | Address line 2. |
| line3
Type: String
Max Length = 75 | O | Address line 3. |
| city
Type: String
Max Length = 50 | C | Address city.
Conditionality: Required if this is a shipping address in a valid format for the country. |
| state
Type: String
Max 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
Max 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:
- US: must be 5-digit numeric value
- Canada: Must be 6-digit alphanumeric value. It is allowed to add an additional space character between 3rd and 4th digit.
- Australia: must be 4-digit numeric value
- Rest of the world: max 9 alphanumeric characters |
| countryCode
Type: String
ISO 3166-1 alpha-2 country code | R | Address country code. |
| createTime
Type: String (Numeric)
UTC time in Unix epoch format | O | Date and time the address was created. |
| lastUsedTime
Type: String (Numeric)
UTC time in Unix epoch format | O | Date and time the address was last used. |
AssuranceData
| Data Element | R/C/O | Description |
| verificationData
Type: List
See VerificationData | R | Set of verification data structures relating to different types of assurance. |
| eci
Type: String
Max Length = 2 | O | 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 |
AuthenticationMethod
| Data Element | R/C/O | Description |
| authenticationMethodType
Type: AuthenticationMethodType
See AuthenticationMethodType enum | R | SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not. |
| authenticationSubject
Type: AuthenticationSubject
See AuthenticationSubject enum | R | Authentication subject. |
| uriData
Type: UriData
See UriData | O | 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
Max Length = 255 | O | 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 | O | Attributes associated with the authentication method type. (See AuthenticationMethod Attributes JSON Values) |
AuthenticationPreferences
| Data Element | R/C/O | Description |
| authenticationMethods
Type: List
See AuthenticationMethod | O | The list of authentication methods and associated parameters populated by the SRCI:
1. in its preferred order; or
2. as instructed by the SRC system |
| supressChallenge
Type: Boolean | O | SRCI preference to indicate challenge suppression. |
| payloadRequested
Type: PayloadRequested
See PayloadRequested | O | Indicates whether the SRCI or Merchant prefers an authenticated or non-authenticated payload. |
Card
| Data Element | R/C/O | Description |
| primaryAccountNumber
Type: String (Numeric)
Min Length = 9
Max Length = 19 | R | The account number of the card to be enrolled and provisioned. |
| panExpirationMonth
Type: String (Numeric)
Length = 2 | C | Expiration month expressed as a two-digit month (MM).
Conditionality: Required when specified for the card (PAN). |
| panExpirationYear
Type: String (Numeric)
Length = 4 | C | Expiration year expressed as a four-digit calendar year (YYYY).
Conditionality: Required when specified for the card (PAN). |
| cardSecurityCode
Type: String (Numeric)
Length = 3 or 4 | C | Card security code.
Conditionality: Required when specified for the card (PAN). |
| cardholderFullName
Type: String
Max Length = 100 | C | Cardholder name.
Conditionality: Required when specified for the card (PAN). |
| cardholderFirstName
Type: String
Max Length = 50 | O | Cardholder first name. |
| cardholderLastName
Type: String
Max Length = 50 | O | Cardholder last name. |
| billingAddress
Type: Address
See Address | O | Billing address. |
| paymentAccountReference
Type: String
Max Length = 29 | O | A non-financial reference assigned to each unique PAN and used to link a payment account represented by that PAN to affiliated payment tokens. |
CheckoutPayloadResponse
| Data Element | R/C/O | Description |
| srciTransactionId
Type: String
Max Length = 255 | R | 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 | R | Masked card data. |
| shippingAddressZip
Type: String
Max Length = 16 | C | Zip or postal code of selected shipping address.
Conditionality: Required, depending on the dpaShippingPreference option in the dpaTransactionOptions structure.
- US: must be 5-digit numeric value
- Canada: Must be 6-digit alphanumeric value. It is allowed to add an additional space character between 3rd and 4th digit.
- Australia: must be 4-digit numeric value
- Rest of the world: max 9 alphanumeric characters |
| 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 | O | SRC System-specific data. |
| assuranceData
Type: AssuranceData
See AssuranceData | O | Assurance data related to the checkout flow. |
| encryptedPayload
Type: JWE
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. |
ComplianceResource
| Data Element | R/C/O | Description |
| complianceType
Type: ComplianceType
See ComplianceType enum | R | Compliance type. |
| uri
Type: String
Max Length = 1024 | R | Uniform Resource Identifier (URI), a valid web address or URL. |
| version
Type: String
Max Length = 10 | O | Version. |
| datePublished
Type: String
UTC time in Unix epoch format | O | Date resource was published. |
MaskedConsumer
| Data Element | R/C/O | Description |
| srcConsumerId
Type: String
Universally Unique Identifier (UUID) | O | 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
Max Length = 255 | O | Masked consumer email address.