Authentication and Authorization via Snap*
3-D Secure 2.0 is a protocol that was developed in compliance with the PSD2 mandate to make online payments more secure through advanced cardholder verification. The first step in the process is to authenticate the cardholder inline of transaction processing. The full flow is offered to integrators who wish to perform both Authentication protocol through Snap* as well as use Snap* front-ends for Authorization. These updates will be supported for the eService and TRON front-ends.
Snap offers integration to the Browser and Application flows for the protocol.
Documentation on implementing this feature can be found here: 3-D Secure 2.0 Full Feature Integration Guide (Last updated: 28 September 2022).
API Reference
**Last updated: 29 March 2021
Request
Required | Parameter | Description | Data Type | Browser/App | Path |
---|---|---|---|---|---|
Optional on a 3DS 2.0 Request | AddressMatch | Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same. | Bool | Both | TransactionCustomerData/ AddressMatch |
Optional on a 3DS 2.0 Request | Expire | Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder. | String | Both | BankcardTenderData/ CardData/ Expire |
Required on a 3DS 2.0 Request | PAN | Account number that will be used in the authorisation request for payment transactions.
May be represented by |
String | Both | BankcardTenderData/ CardData/ PAN |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | City | The city of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ CityTransactionCustomerData/ BillingData/ InternationalAddress/ City |
Conditional – Required on a 3DS 2.0 Request if available and StateProvince is set | CountryCode | The country of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ CountryCodeTransactionCustomerData/ BillingData/ InternationalAddress/ CountryCode |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street1 | First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ Street1TransactionCustomerData/ BillingData/ InternationalAddress/ Street1 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street2 | Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ Street2TransactionCustomerData/ BillingData/ InternationalAddress/ Street2 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street3 | Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ Street3TransactionCustomerData/ BillingData/ InternationalAddress/ Street3 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | PostalCode | ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. | String | Both | TransactionCustomerData/ BillingData/ Address/ PostalCodeTransactionCustomerData/ BillingData/ InternationalAddress/ PostalCode |
Conditional – Required on a 3DS 2.0 Request if available for this country and is not restricted by regional mandate | StateProvince | The state or province of the Cardholder billing address associated with the card used for this purchase. | String – max 3 characters, should be the country subdivision code defined in ISO 3166-2. | Both | TransactionCustomerData/ BillingData/ Address/ StateProvinceTransactionCustomerData/ BillingData/ InternationalAddress/ StateProvince |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. | String | Both | TransactionCustomerData/ BillingData/ |
|
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Phone | The home phone number provided by the Cardholder. | String – Formatted as “CountryCode-Subscriber” with a hypen separating the country code and the subscriber. Like: 1-1234567890 | Both | TransactionCustomerData/ BillingData/ Phone |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | MobilePhone | The mobile phone number provided by the Cardholder. | String – Formatted as “CountryCode-Subscriber” with a hypen separating the country code and the subscriber. Like: 1-1234567890 | Both | TransactionCustomerData/ BillingData/ MobilePhone |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | CardholderName | Name of the Cardholder. | String | Both | BankcardTenderData/ CardData/ CardholderName |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | City | City portion of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ CityTransactionCustomerData/ ShippingData/ InternationalAddress/ City |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | CountryCode | Country of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ CountryCodeTransactionCustomerData/ ShippingData/ InternationalAddress/ CountryCode |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street1 | First line of the street address or equivalent local portion of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ Street1TransactionCustomerData/ ShippingData/ InternationalAddress/ Street1 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street2 | Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ Street2TransactionCustomerData/ ShippingData/ InternationalAddress/ Street2 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | Street3 | Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ Street3TransactionCustomerData/ ShippingData/ InternationalAddress/ Street3 |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | PostalCode | The ZIP or other postal code of the shipping address requested by the Cardholder. | String | Both | TransactionCustomerData/ ShippingData/ Address/ PostalCodeTransactionCustomerData/ ShippingData/ InternationalAddress/ PostalCode |
Conditional – Required on a 3DS 2.0 Request if available for this country and is not restricted by regional mandate | StateProvince | The state or province of the shipping address associated with the card being used for this purchase. | String – max 3 characters, should be the country subdivision code defined in ISO 3166-2. | Both | TransactionCustomerData/ ShippingData/ Address/ StateProvinceTransactionCustomerData/ ShippingData/ InternationalAddress/ StateProvince |
Conditional – Required on a 3DS 2.0 Request if available and not restricted by regional mandate | WorkPhone | The work phone number provided by the Cardholder. | String – Formatted as “CountryCode-Subscriber” with a hypen separating the country code and the subscriber. Like: 1-1234567890 | Both | TransactionCustomerData/ BillingData/ WorkPhone |
Conditional – required on a 3DS 2.0 Request if ThreeRIIndicator is Installment. | TotalNumberOfInstallments | Indicates the maximum number of authorisations permitted for instalment payments. | String, 3 Char, >1 | Both | BankcardTransation/ BankcardTransactionDataPro/ BankcardInterchangeData/ TotalNumberOfInstallments |
Conditional – Required on a 3DS 2.0 Request. Required on a 3DS 2.0 3RI Request if ThreeRIIndicator is Recurring or Installment. |
Amount | Purchase amount in minor units of currency | String, Decimal NOTE: EMVCo requires no decimal but Snap* will do translation |
Both | TransactionData/ Amount |
Conditional – Required on a 3DS 2.0 Request. Required on a 3DS 2.0 3RI Request if ThreeRIIndicator is Recurring or Installment. |
CurrencyCode | Currency in which purchase amount is expressed | String, 3 Char, Numeric | Both | TransactionData/ CurrencyCode |
Conditional – Required on a 3DS 2.0 3RI Request if ThreeRIIndicator is Recurring or Installment. | RecurringExpirationDate | Date after which no further authorisations shall be performed. | String, Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionDataPro/ BankcardInterchangeData/ RecurringExpirationDate |
Conditional – Required on a 3DS 2.0 3RI Request if ThreeRIIndicator is Recurring or Installment. | RecurringFrequency | Indicates the minimum number of days between authorizations. | Int, 4 Char | Both | BankcardTransaction/ BankcardTransactionDataPro/ BankcardInterchangeData/ RecurringFrequency |
Conditional – Required on an 3DS 2.0 3DS Requestor Intiated (3RI) Request | ThreeRIIndicator | Indicates the type of 3DS Requestor Intiated Request. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ ThreeRIIndicator |
Conditional – Required on a 3DS 2.0 Browser Flow Request | BrowserAcceptHeader | Exact content of the HTTP accept headers as sent to Snap* from the Cardholder’s browser. | Stringt, 2048 Char | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserAcceptHeader |
Optional on a 3DS 2.0 Browser Flow Request | IpAddress | IP address of the browser as returned by the HTTP headers to Snap*. | String, 45 Char | Browser | BankcardTransactionData/ InternetTransactionData/ IpAddress |
Conditional – Required on a 3DS 2.0 Browser Flow Request when BrowserJavaScriptEnabled is True | BrowserJavaEnabled | Boolean that represents the ability of the cardholder browser to execute Java. | Enum –
|
Browser | BankcardTransactionData/ InternetTransactionData/ BrowserJavaEnabled |
Conditional – Required on a 3DS 2.0 Browser Flow Request. If included, this field will be dropped from a 2.1 transaction request. | BrowserJavaScriptEnabled | Boolean that represents the ability of the cardholder browser to execute JavaScript. | Enum –
|
Browser | BankcardTransactionData/ InternetTransactionData/ BrowserJavaScriptEnabled |
Conditional – Required on a 3DS 2.0 Browser Flow Request | BrowserLanguage | Value representing the browser language as defined in IETF BCP47. | String, 1-8 Char | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserLanguage |
Conditional – Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is v2_1_0 Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.2.0 and BrowserJavaScriptEnabled is True. |
BrowserScreenColorDepth | Values accepted:
|
String, 1-2 Char | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserScreenColorDepth |
Conditional – Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.1.0 Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.2.0 and BrowserJavaScriptEnabled is True. |
BrowserScreenHeight | Total height of the Cardholder’s screen in pixels. | String, 1-6 Char, Numeric | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserScreenHeight |
Conditional – Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.1.0 Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.2.0 and BrowserJavaScriptEnabled is True. |
BrowserScreenWidth | Total width of the Cardholder’s screen in pixels. | String, 1-6 Char, Numeric | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserScreenWidth |
Conditional – Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.1.0 Required on a 3DS 2.0 Browser Flow Request if ProtocolVersion is 2.2.0 and BrowserJavaScriptEnabled is True. |
BrowserTimeZone | Time-zone offset in minutes between UTC and the Cardholder browser local time. | String, 1-5 Char | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserTimeZone |
Conditional – Required on a 3DS 2.0 Browser Flow Request | BrowserUserAgent | Exact content of the HTTP user-agent header. | String, 2048 Char | Browser | BankcardTransactionData/ InternetTransactionData/ BrowserUserAgent |
Optional on a 3DS 2.0 Request | MerchantRiskInfo | Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted. | Object – DeliveryEmailAddress DeliveryTimeframe GiftCardAmount GiftCardCount GiftCardCurrency PreorderDate PreorderPurchaseIndicator ReorderItemsIndicator ShipIndicator |
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo |
Optional on a 3DS 2.0 Request | DeliveryEmailAddress | For Electronic delivery, the email address to which the merchandise was delivered. | String, max 254 Char | Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ DeliveryEmailAddress |
Optional on a 3DS 2.0 Request | DeliveryTimeframe | Indicates the merchandise delivery timeframe. | Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ DeliveryTimeframe |
Optional on a 3DS 2.0 Request | GiftCardAmount | For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s). Value will be truncated. | Decimal, 15 Char | Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ GiftCardAmount |
Optional on a 3DS 2.0 Request | GiftCardCount | For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. | Int, 2 Char | Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ GiftCardCount |
Optional on a 3DS 2.0 Request | GiftCardCurrency | For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card. |
Enum – Existing currency enum. | Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ GiftCardCurrency |
Optional on a 3DS 2.0 Request | PreorderDate | For a pre-ordered purchase, the expected date that the merchandise will be available. | Datetime Format accepted: YYYYMMDD |
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ PreorderDate |
Optional on a 3DS 2.0 Request | PreorderPurchaseIndicator | Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. | Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ PreorderPurchaseIndicator |
Optional on a 3DS 2.0 Request | ReorderItemsIndicator | Indicates whether the cardholder is reordering previously purchased merchandise. | Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ ReorderItemsIndicator |
Optional on a 3DS 2.0 Request | ShipIndicator | Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. |
Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ MerchantRiskInfo/ ShipIndicator |
Optional on a 3DS 2.0 Request | AccountInfo | Additional information about the Cardholder’s account provided by the 3DS Requestor. | Object – AccountAgeIndicator AccountChangeDate AccountChangeIndicator AccountDate AccountPasswordChangeDate AccountPasswordChangeIndicator AccountPurchaseCount AccountProvisioningAttempts AccountDayTransactions AccountYearTransactions PaymentAccountAge PaymentAccountAgeIndicator ShipAddressUsageDate ShipAddressUsageIndicator ShipNameIndicator SuspiciousAccountActivity |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo |
Optional on a 3DS 2.0 Request | AccountAgeIndicator | Length of time that the cardholder has had the account with the merchant. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountAgeIndicator |
Optional on a 3DS 2.0 Request | AccountChangeDate | Date that the cardholder’s account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. |
Datetime, Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountChangeDate |
Optional on a 3DS 2.0 Request | AccountChangeIndicator | Length of time since the cardholder’s account information with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountChangeIndicator |
Optional on a 3DS 2.0 Request | AccountDate | Date that the cardholder opened the account with the merchant. | Datetime Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountDate |
Optional on a 3DS 2.0 Request | AccountPasswordChangeDate | Date that cardholder’s account with the merchant had a password change or account reset. | Datetime Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountPasswordChangeDate |
Optional on a 3DS 2.0 Request | AccountPasswordChangeIndicator | Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountPasswordChangeIndicator |
Optional on a 3DS 2.0 Request | AccountPurchaseCount | Number of purchases with this cardholder account during the previous six months. | Int, max 4 Char | Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountPurchaseCount |
Optional on a 3DS 2.0 Request | AccountProvisioningAttempts | Number of Add Card attempts in the last 24 hours | Int, max 3 Char | Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountProvisioningAttempts |
Optional on a 3DS 2.0 Request | AccountDayTransactions | Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous 24 hours. | Int, max 3 Char | Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountDayTransactions |
Optional on a 3DS 2.0 Request | AccountYearTransactions | Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous year. | Int, max 3 Char | Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ AccountYearTransactions |
Optional on a 3DS 2.0 Request | PaymentAccountAge | Date that the payment account was enrolled in the cardholder’s account with the merchant. | Datetime, Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ PaymentAccountAge |
Optional on a 3DS 2.0 Request | PaymentAccountAgeIndicator | Indicates the length of time that the payment account was enrolled in the cardholder’s account with the merchant. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ PaymentAccountAgeIndicator |
Optional on a 3DS 2.0 Request | ShipAddressUsageDate | Date when the shipping address used for this transaction was first used with the merchant. | Datetime Format accepted: YYYYMMDD |
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ ShipAddressUsageDate |
Optional on a 3DS 2.0 Request | ShipAddressUsageIndicator | Indicates when the shipping address used for this transaction was first used with the merchant. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ ShipAddressUsageIndicator |
Optional on a 3DS 2.0 Request | ShipNameIndicator | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ ShipNameIndicator |
Optional on a 3DS 2.0 Request | SuspiciousAccountActivity | Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. | Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AccountInfo/ SuspiciousAccountActivity |
Conditional – Required on a 3DS 2.0 Application Flow Request | SDKInfo | Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK. | Object – Interface (sdkInterface) UITypes AppId Encrypted Data PublicKey MaxTimeout ReferenceNumber TransactionId DeviceRenderOptions |
Application | BankcardTransactionData/ ThreeDSData/ SDKInfo |
Conditional – Required on a 3DS 2.0 Application Flow Request | AppId | Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation. |
String, 36 Char | Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ AppId |
Conditional – Required on a 3DS 2.0 Application Flow Request | EncryptedData | JWE Object (represented as a string) as defined in Section 6.2.2.1 of the EMVCo 2.2 Specification containing data encrypted by the SDK for the DS to decrypt. | String, 64000 Char | Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ EncryptedData |
Conditional – Required on a 3DS 2.0 Application Flow Request | PublicKey | Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. Defined in Section 6.2.3.1 of EMVCo 2.2 Specification. | String, 256 Char | Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ PublicKey |
Conditional – Required on a 3DS 2.0 Application Flow Request | MaxTimeout | Indicates maximum amount of time (in minutes) for all exchanges. | Int, Values accepted: Greater than or = to 05 |
Application | BankcardTransaction/ BanckardTransactionData/ ThreeDSData/ SDKInfo/ MaxTimeout |
Conditional – Required on a 3DS 2.0 Application Flow Request | ReferenceNumber | Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved. |
String, 32 Char | Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ ReferenceNumber |
Conditional – Required on a 3DS 2.0 Application Flow Request | TransactionId | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. | String | Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ TransactionId |
Conditional – Required on a 3DS 2.0 Application Flow Request | DeviceRenderOptions | Object that denotes all of the SDK Interface types and UI types that the device supports for displaying specific challenge user interfaces within the SDK. | Object – Interface UITypes |
Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ DeviceRenderOptions |
Conditional – Required on a 3DS 2.0 Application Flow Request | Interface | Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. | Enum –
|
Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ DeviceRenderOptions/ Interface |
Conditional – Required on a 3DS 2.0 Application Flow Request | UITypes | Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Valid values for each Interface: • Native UI = 01–04 • HTML UI = 01–05 Note: Currently, all SDKs need to support all UI Types. |
list< enum > –
|
Application | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ SDKInfo/ DeviceRenderOptions/ UITypes |
Optional on a 3DS 2.0 Request | AccountId | Additional information about the account optionally provided by the merchant. | String | Both | BankcardTransactionData/ ThreeDSData/ AccountId |
Conditional – Required on a 3DS 2.0 Browser Flow Request | ChallengeWindowSize | Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window. |
Enum –
|
Browser | BankcardTransactionData/ ThreeDSData/ ChallengeWindowSize |
Conditional – Required on a 3DS 2.0 Request if there is a de-tokenization of an Account Number | PaymentTokenIndicator | A value of True indicates that the transaction was de-tokenised prior to being received by the Snap*.
The Boolean value of true is the only valid response for this field when it is present. |
Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ PaymentTokenIndicator |
Required on a 3DS Request | ProtocolVersion | This will be the Protocol Version Number the transaction should be processed as. | Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ ProtocolVersion |
Conditional – Required on a 3DS 2.0 Request | SupportsProtocolVersion1 | Indicates Merchant support of 3DS 1.0 | Bool | Both | BankcardTransactionData/ ThreeDSData/ SupportsProtocolVersion1 |
Optional on a 3DS 2.0 Request | TransactionType | Identifies the type of transaction being authenticated. Note: this value will default to GoodsServicesPurchase if not set on the original request for Visa transactions only. |
Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ TransactionType |
Conditional – Required on a 3DS 2.0 Browser Flow Request | MethodCompletionIndicator | Indicates whether the 3DS Method successfully completed. | Enum –
|
Browser | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ MethodCompletionIndicator |
Conditional – Required on a 3DS 2.0 Request | AuthenticationIndicator | Indicates the type of Authentication request.
This data element provides additional information to the ACS to determine the best approach for handing an authentication request. |
Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ AuthenticationIndicator |
Optional on a 3DS 2.0 Request | RequestorChallengeIndicator | Indicates if a merchant wants to request a challenge for this transaction. Note: this value will default to NoPreference if not set on the original request for Visa transactions only. |
Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ RequestorChallengeIndicator |
Optional on a 3DS 2.0 Request. If included, this field will be dropped from a 2.1 transaction request. | DecoupledMaxTimeout | Indicates the maximum amount of time that the merchant requests Snap* to wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). | Int, Numeric values between 1 and 10080 accepted. | Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ DecoupledMaxTimeout |
Optional on a 3DS 2.0 Request. If included, this field will be dropped from a 2.1 transaction request. | DecoupledRequestIndicator | Indicates whether the merchant requests the ACS to utilize Decoupled Authentication and agrees to utilize Decoupled Authentication if the ACS confirms its use. |
Enum –
|
Both | BankcardTransaction/ BankcardTransactionData/ ThreeDSData/ DecoupledRequestIndicator |
Optional on a 3DS 2.0 Request | RequestorAuthData | Optional additional information that documents and supports a specific authentication process on how the cardholder authenticated to the merchant. This is used by the Access Control Server for verification of authentication. | String, 20,000 Char | Both | BankcardTransactionData/ ThreeDSData/ RequestorAuthData |
Optional on a 3DS 2.0 Request | RequestorAuthMethod | Mechanism used by the Cardholder to authenticate to the merchant. Note: this value will defult to None if not set on the original request for Visa transactions only. This enum of “None” states that the cardholder was NOT authenticated with the 3DS Requestor (or the cardholder facing website), or that no 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest). |
Enum –
|
Both | BankcardTransactionData/ ThreeDSData/ RequestorAuthMethod |
Optional on a 3DS 2.0 Request | RequestorAuthTimestamp | Date and time in UTC of the cardholder authentication. | Datetime Format accepted: YYYYMMDDHHMM |
Both | BankcardTransactionData/ ThreeDSData/ RequestorAuthTimestamp |
Optional on a 3DS 2.0 Request | ExemptionInfo | Merchant Application identified Exemption to be requested from the Issuer. For more information on Exemptions, please see the Integration Guide. | Object – ExemptionControl IsLowValue IsLowRisk IsRecurring IsWhitelisted IsSecureCorporate IsDelegatedSCA |
Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo |
Optional on a 3DS 2.0 Request | ExemptionControl | Identifies which flow Merchant Application would like the Exemption to be sent if different than the default. | Enum – NotSet AuthenticationFlow AuthorizationFlow |
Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ ExemptionControl |
Optional on a 3DS 2.0 Request | IsLowValue | Merchant Application requesting the Low Value Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsLowValue |
Optional on a 3DS 2.0 Request | IsLowRisk | Merchant Application requesting the Low Risk Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsLowRisk |
Optional on a 3DS 2.0 Request | IsRecurring | Merchant Application requesting the Recurring Payments Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsRecurring |
Optional on a 3DS 2.0 Request | IsWhitelisted | Merchant Application requesting the Merchant Whitelist Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsWhitelisted |
Optional on a 3DS 2.0 Request | IsSecureCorporate | Merchant Application requesting the Secure Corporate Payments Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsSecureCorporate |
Optional on a 3DS 2.0 Request | IsDelegatedSCA | Merchant Application requesting the Delegated SCA Exemption | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsDelegatedSCA |
Optional on a 3DS 2.0 Request | IsInterRegionalTransaction | Merchant Application is requesting interrregional transaction | Bool | Both | BankcardTransactionData/ ThreeDSData/ ExemptionInfo/ IsInterRegionalTransaction |
Required in Error Message if available (e.g. can be obtained from a message or is being generated). | ServerTransactionId | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. | String | Both | BankcardTransaction/ BankcardTenderData/ EcommerceSecurityData/ ServerTransactionId |
Required on Resubmit for Decoupled Authentication. | DecoupledInfo | Used to search for Decoupled Authentication results. | Class – ServerTransactionId ACSTransactionId |
2.2 | Resubmit3DSecure/ DecoupledInfo |
Required on Resubmit for Decoupled Authentication. | ServerTransactionId | Used to search for Decoupled Authentication results. | String | 2.2 | Resubmit3DSecure/ DecoupledInfo/ ServerTransactionId |
Required on Resubmit for Decoupled Authentication. | ACSTransactionId | Used to search for Decoupled Authentication results. | String | 2.2 | Resubmit3DSecure/ DecoupledInfo/ ACSTransactionId |
Response
Required | Parameter | Description | Data Type | Browser/App | Path |
---|---|---|---|---|---|
Conditional – Expected on a 3DS 2.0 Response. | ThreeDSInformation | This object is returned on a 3DS 2.0 Transaction. | Object | Both | BankcardTransactionResponse/ ThreeDSInformation |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is ChallengeRequired or DecoupledAuthenticationRequired. | IsChallengeMandated | Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable. | Bool | Both | BankcardTransactionResponse/ ThreeDSInformation/ IsChallengeMandated |
Conditional – Expected on a 3DS 2.0 Response. | ACSTransactionId | Identifier assigned by the Access Control Server to identify a single transaction. | String, 36 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ ACSTransactionId |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is ChallengeRequired. | AcsUrl | Fully qualified URL of the ACS to be used for the challenge.
In Application Flow, SDK will send the Challenge Request to this URL In Browser Flow, the merhcant will post the CReq to this URL via the challenge window |
String, 2048 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ AcsUrl |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is ChallengeRequired or DecoupledAuthenticationRequired. | AuthenticationType | Indicates the type of authentication method the Issuer will use to challenge the Cardholder. | Enum –
|
Both | BankcardTransactionResponse/ ThreeDSInformation/ AuthenticationType |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is SuccessfullyAuthenticated or AttemptsProcessingPerformed. Optional if TransactionStatus is InformationalOnly. |
AuthenticationValue | Payment System-specific value provided by the Access Control Server or Directory Server using an algorithm defined by Payment System. It is used to provide proof of authentication. | String, 28 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ AuthenticationValue |
Conditional – Expected on a 3DS 2.0 Response for Decoupled Authentication accepted transactions. | CardholderInformationText | Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. Note: If field is populated this information is required to be conveyed to the cardholder by the merchant. |
String, 128 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ CardholderInformationText |
Conditional – Expected on a 3DS 2.0 Response. | DSReferenceNumber | EMVCo-assigned unique identifier to track approved DS. | String, 32 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ DSReferenceNumber |
Conditional – Expected on a 3DS 2.0 Response. | DSTransactionId | Identifier assigned by the Directory Server to identify a single transaction. | String, 36 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ DSTransactionId |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is SuccessfullyAuthenticated or AttemptsProcessingPerformed. | AuthenticationECI | Payment System-specific value provided by the Access Control Server or Directory Server to indicate the results of the attempt to authenticate the Cardholder. | String,2 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ AuthenticationECI |
Conditional – Expected on a 3DS 2.0 Error Response. | ErrorCode | Code indicating the type of problem identified in the message. | String, 3 Char Defined values can be found in the EMVCo 2.2 Spec under Table A.4 |
Both | BankcardTransactionResponse/ ThreeDSInformation/ ErrorCode |
Conditional – Expected on a 3DS 2.0 Error Response. | ErrorDescription | Text describing the problem identified in the message. | String, 2048 Char Defined values can be found in the EMVCo 2.2 Spec under Table A.4 |
Both | BankcardTransactionResponse/ ThreeDSInformation/ ErrorDescription |
Conditional – Expected on a 3DS 2.0 Error Response. | ErrorDetail | Additional detail regarding the problem identified in the message. | String, 2048 Char Defined values can be found in the EMVCo 2.2 Spec under Table A.4 |
Both | BankcardTransactionResponse/ ThreeDSInformation/ ErrorDetail |
Conditional – Expected on a 3DS 2.0 Response. | MessageCategory | Identifies the category of the message, whether it be payment or non-payment. | Enum – NotSet NonPayment Payment |
Both | BankcardTransactionResponse/ ThreeDSInformation/ MessageCategory |
Conditional – Expected on a 3DS 2.0 Response. | ProtocolVersion | This will be the Protocol Version Number the transaction was processed as. Could be changed from request due to Fallback. | Enum –
|
Both | BankcardTransactionResponse/ ThreeDSInformation/ ProtocolVersion |
Conditional – Expected on a 3DS 2.0 Response. Optional if this is a Verify Transaction. |
TransactionStatus | This value defines the authentication status for validation purposes. | Enum –
|
Both | BankcardTransactionResponse/ ThreeDSInformation/ TransactionStatus |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is NotAuthenticated, UnableToAuthenticate or AuthenticationRejected. Optional if this is a Verify Transaction |
TransactionStatusReason | Provides information on why the Transaction Status field has the specified value. | Enum –
|
Both | BankcardTransactionResponse/ ThreeDSInformation/ TransactionStatusReason |
Optional on a 3DS 2.0 Response. If included, this field will be dropped from a 2.1 transaction request. | WhiteListStatus | Indicates the eligibilty of the card used in the transaction for customer Whitelisting between the ACS, the DS and the 3DS Requestor. | Enum –
|
Both | BankcardTransactionResponse/ ThreeDSInformation/ WhitelistStatus |
Conditional – Expected on a 3DS 2.0 Response. | ServerTransactionId | Universally unique transaction identifier assigned by Snap* or the Web App to identify a single transaction. Snap* will define this value if merchant is using their own Card Range Cache. | String, 36 Char Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements. |
Both | BankcardTransactionResponse/ ThreeDSInformation/ ServerTransactionId |
Conditional – Expected on a 3DS 2.0 Response if TransactionStatus is ChallengeRequired. | ChallengeRequest | The CReq message initiates Cardholder interaction in a Challenge Flow and can be used to carry authentication data from the Cardholder. In the Application Flow, the Creq is sent by the 3DS SDK and there can be 2 or more attempts betweeen the ACS and the Cardholder. In the Browser Flow, the Creq is sent by the merchant. There is only one Creq message per challenge. |
String | Both | BankcardTransactionResponse/ ThreeDSInformation/ ChallengeRequest |
Conditional – Expected on 3DS 2.0 Application Workflow Response if TransactionStatus is ChallengeRequired. | ACSRenderingInterface | This the ACS interface that the challenge will present to the cardholder. | Enum –
|
Application | BankcardTransactionResponse/ ThreeDSInformation/ ACSRenderingInterface |
Conditional – Expected on a 3DS 2.0 Response. | ChallengeCancellationIndicator | Indicator informing the ACS and the DS that the authentication has been canceled. |
String | Both | BankcardTransactionResponse/ ThreeDSInformation/ ChallengeCancellationIndicator |
Conditional – Expected on 3DS 2.0 Application Workflow Response if TransactionStatus is ChallengeRequired. | ACSRenderingUITemplate | Identifies the UI Template format that the ACS first presents to the consumer. Valid values for each ACSRenderingInterface: • Native UI = 01–04 • HTML UI = 01–05 |
Enum –
|
Application | BankcardTransactionResponse/ ThreeDSInformation/ ACSRenderingUITemplate |
Conditional – Expected on a 3DS 2.0 Response if SCA is required for the transaction. | SCARequired | Indicator that the Issuer has rejected the requested Exemption or Out of Scope Transaction. | Bool | Both | BankcardTransactionResponse/ ThreeDSInformation/ SCARequired |
Conditional – Expected on a 3DS 2.0 Response if requested Exemption is declined. | ReasonForNotHonoringExemption | Issuer reason that the requested Exemption was declined. | String | Both | BankcardTransactionResponse/ ThreeDSInformation/ ReasonForNotHonoringExemption |
Conditional – Expected on a 3DS 2.0 Response if an Exemption was Requested. | ExemptionControl | Issuer reason that the requested Exemption was declined. | Enum – NotSet AuthenticationFlow AuthorizationFlow |
Both | BankcardTransactionResponse/ ThreeDSInformation/ ExemptionControl |
Conditional – Expected on a 3DS 2.0 Response. | SDKResponseInfo | This object is returned on a 3DS 2.0 Transaction. | Object – AppId MaxTimeout TransactionId ACSOperatorId ACSReferenceNumber ACSSignedContent |
Both | BankcardTransactionResponse/ SDKResponseInfo |
Conditional – Expected on a 3DS 2.0 Response. | AppId | Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation. |
String, 36 Char | Application | BankcardTransactionResponse/ SDKResponseInfo/ AppId |
Conditional – Expected on a 3DS 2.0 Response. | MaxTimeout | Indicates maximum amount of time (in minutes) for all exchanges. | Int, Values accepted: Greater than or = to 05 |
Application | BankcardTransactionResponse/ SDKResponseInfo/ MaxTimeout |
Conditional – Expected on a 3DS 2.0 Response. | TransactionId | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. | String | Application | BankcardTransactionResponse/ SDKResponseInfo/ TransactionId |
Conditional – Expected on a 3DS 2.0 Application Flow Response if assigned by Directory Server. | ACSOperatorId | DS assigned ACS identifier. | String, 32 Char | Application | BankcardTransactionResponse/ SDKResponseInfo/ ACSOperatorId |
Conditional – Expected on a 3DS 2.0 Response. | ACSReferenceNumber | Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. | String, 32 Char | Both | BankcardTransactionResponse/ ThreeDSInformation/ ACSReferenceNumber |
Conditional – Expected on 3DS 2.0 Application Flow Response if TransactionStauts is C. | ACSSignedContent | Contains the JWS object (represented as a string) created by the ACS for the ARes message. | Object | Application | BankcardTransactionResponse/ SDKResponseInfo/ ACSSignedContent |
Conditional – Expected on 3DS 2.0 Application Workflow Response if TransactionStatus is ChallengeRequired. | ACSRenderingType | This the ACS interface and UI template form that the challenge will present to the cardholder. | Object – Interface UITemplate |
Application | BankcardTransactionResponse/ SDKResponseInfo/ ACSRenderingType |
Conditional – Expected on 3DS 2.0 Application Workflow Response if TransactionStatus is ChallengeRequired. | Interface | This the ACS interface that the challenge will present to the cardholder. | Enum –
|
Application | BankcardTransactionResponse/ SDKResponseInfo/ ACSRenderingType/ Interface |
Conditional – Expected on 3DS 2.0 Application Workflow Response if TransactionStatus is ChallengeRequired. | UITemplate | Identifies the UI Template format that the ACS first presents to the consumer. Valid values for each Interface: • Native UI = 01–04 • HTML UI = 01–05 |
Enum –
|
Application | BankcardTransactionResponse/ SDKResponseInfo/ ACSRenderingType/ UITemplate |
Optional on a 3DS 2.0 Response. | AuthenticationTimestamp | Date and time in UTC of the cardholder authentication. | Datetime | Application | BankcardTransactionResponse/ ThreeDSSecureInformation/ AuthenticationTimestamp |
Optional on a 3DS 2.0 Response. | AuthenticationMethod | Mechanism used by the Cardholder to authenticate the 3DS requestor. | Enum – NotSet Frictionless CardholderChallenge AVSVerified Other |
Application | BankcardTransactionResponse/ ThreeDSSecureInformation/ AuthenticationMethod |
Optional on a 3DS 2.0 Response. | PriorACSTransactionId | This data element provides additional information to the ACS to determine the best approach for handing a request. | String | Application | BankcardTransactionResponse/ ThreeDSSecureInformation/ PriorACSTransactionId |
Optional on a 3DS 2.0 Response. | PriorDSTransactionId | This data element provides additional information to the ACS to determine the best approach for handing a request. | String | Application | BankcardTransactionResponse/ ThreeDSSecureInformation/ PriorDSTransactionId |
Resubmit
Required | Parameter | Description | Data Type | Browser/App | Path |
---|---|---|---|---|---|
Required on a 3DS 2.0 Resubmit Request | TransactionId | Snap* TransactionId from the original transaction Response | String | Both | Resubmit3DSecure/ TransactionId |
Required on a 3DS 2.0 Resubmit Request | ChallengeResponse | The ACS response to the CReq message. It can indicate the result of the Cardholder authentication or, in the case of an App-based model, also signal that further Cardholder interaction is required to complete the authentication. | String | Both | Resubmit3DSecure/ ChallengeResponse |
Required on a 3DS 2.0 Resubmit Request | ResubmitReason | Identifier of what type of Resubmit this transaction is. For 3DS 2.0, the Resubmit Reason is Resubmission | Enum –
|
Both | ResubmitTransaction/ Resubmit3DSecure/ ResubmitReason |