pilot checkout() {#uctp-api-specs-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](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-jwt-keys.md ""). * **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](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-pan-enc-keys.md ""). * **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](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-tms-mle-keys.md ""). {#uctp-api-specs-checkout_ul_off_3gy_x3c} 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 {#uctp-java-checkout} ======================================== Your checkout() request can include these parameters: Request Parameters ------------------ | 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\<PaymentOptions\> | 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.). | [Request Parameters and Descriptions] 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\<ComplianceResource\> | 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\<VerificationData\> | Required | Verification data structures. | | eci **Type**: String **Maximum Length**: 2 | Optional | E-commerce authentication indicator. | pilot Response Attributes {#uctp-java-checkout-response} ================================================== ****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 \<CheckoutPayloadResponse\> | 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\<Payload\> 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\<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 | | | 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) | 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\<VerificationData\> 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\<String (Numeric)\> 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\<DynamicData\> 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 {#uctp-checkout-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 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. | [Error Response Fields] 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 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. | [Error Codes]