Merchants > API Reference > Endpoints > 3D Secure > Authenticate

Authenticate

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance.

Optional Optional fields are additional data points that can be shared with the card schemes, issuers, and Ravelin. These fields may impact performance or dashboard usability.

Conditional Fields that may be required under certain conditions.

POST 3ds.live.pci.ravelin.com/3ds/authenticate

This endpoint allows you to provide customer and transaction data related to the 3DS authentication. Ravelin will use this data to produce the AReq message and initiate 3DS authentication with the customer’s card issuer.

Device Channel: Version:

Authenticate Request

Show all

timestamp integer

required

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC.

Example: 1512828988826

customerId string

optional

Enterprise Merchants: the unique identifier for the customer used on the Checkout endpoint.

PSPs: the unique identifier for the customer used on the Transaction endpoint.

This is required if you want to associate the 3D Secure authentication with the customer.

Example: "123-abc-XYZ"

Minimum length: 1

transactionId string

optional

Enterprise Merchants: the unique identifier for the transaction used on the Checkout endpoint.

PSPs: the unique identifier for the transaction used on the Transaction endpoint.

Required if you want to associate the 3D Secure authentication with the transaction.

Example: "123-abc-XYZ"

Minimum length: 1

transactionStepId string

optional

The unique identifier for the transaction step within the transaction used only for PSP clients on the Transaction endpoint.

Example: "123-abc-XYZ"

Minimum length: 1

paymentMethod object

2.1.0 2.2.0

APP BRW 3RI

conditional

The card being used for the transaction, encrypted using the Ravelin card encryption SDK.

See Submission of Encrypted Card Details for more information.

Conditions:

Either paymentMethod or areqData.pan must be provided.

Hide definition

cardCiphertext string required	The card ciphertext produced by the Ravelin card encryption SDK. This field constitutes cardholder data. Submission of this field requires PCI DSS SAQ-A or SAQ-AEP certification. Please see our PCI DSS Compliance Guide for more information.
aesKeyCiphertext string required	The AES key ciphertext produced by the Ravelin card encryption SDK . Minimum length: 1
algorithm string required	The algorithm used to generate the ciphertexts. Example: `"RSA_WITH_AES_256_GCM"` Minimum length: 1
ravelinSDKVersion string optional	The version of the Ravelin mobile or JavaScript SDK that performed the encryption. Example: `"0.0.13-ravelinjs"`
keyIndex integer optional	The index of the public RSA key used to encrypt the card.
keySignature string optional	An identifier for the public RSA key used to encrypt the card.

areqData object

required

Customer and transaction data used to perform the 3DS authentication. Although many of these fields are optional, the more you can provide, the higher the chance of receiving a Frictionless authentication.

Hide definition

messageVersion string

2.1.0 2.2.0

APP BRW 3RI

optional

The 3DS protocol version to be used for the 3DS authentication. If the version is not provided we default to the versionRecommendation returned in the Version Response. You should populate fields according to the selected messageVersion.

Options:

2.1.0

2.2.0

Minimum length: 4

Maximum length: 8

messageCategory string

2.1.0 2.2.0

APP BRW 3RI

required

Identifies whether this is a payment or non-payment 3DS authentication. For example, a non-payment 3DS authentication may be used when a customer adds a card to their account, but does not make a purchase.

Options:

`01`	Payment authentication (PA)
`02`	Non-payment authentication (NPA)

deviceChannel string

2.1.0 2.2.0

APP BRW 3RI

required

Indicates the channel being used to initiate the authentication.

Options:

`01`	App-based (APP)
`02`	Browser (BRW)
`03`	3DS Requestor Initiated (3RI)

threeDSServerTransID string

2.1.0 2.2.0

APP BRW 3RI

conditional

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

Example: "c5584543-b67e-5117-bb34-3567ac6a1123"

Conditions:

Required when deviceChannel is Browser, and a threeDSServerTransID has already been returned in the Version Response. In this case the same threeDSServerTransID should be used.

Length: 36

purchaseAmount string

2.1.0 2.2.0

APP BRW 3RI

conditional

Purchase amount in minor units of currency with all punctuation removed.

Example: "10000"

Conditions:

Required for Payment Authentications (PA). Required for Non-Payment Authentications (NPA) when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03).

purchaseCurrency string

2.1.0 2.2.0

APP BRW 3RI

conditional

Currency in which purchaseAmount is expressed (ISO 4217 three-digit numeric currency code).

Example: "826"

Conditions:

Required for Payment Authentications (PA). Required for Non-Payment Authentications (NPA) when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03).

purchaseExponent string

2.1.0 2.2.0

APP BRW 3RI

conditional

Minor units of currency as specified in the ISO 4217 currency exponent.

Example: "2"

Conditions:

Required for Payment Authentications (PA). Required for Non-Payment Authentications (NPA) when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03).

purchaseDate string

2.1.0 2.2.0

APP BRW 3RI

conditional

Date and time of the purchase expressed in UTC.

Format: YYYYMMDDhhmmss

Conditions:

Required for Payment Authentications (PA). Required for Non-Payment Authentications (NPA) when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03).

pan string

2.1.0 2.2.0

APP BRW 3RI

conditional

The Primary Account Number (PAN) of the card being used for the transaction. If EMV Tokenisation is supported, this may be an EMV Payment Token instead of a PAN.

This field is cardholder data. Submission of this field requires PCI DSS SAQ-D certification.

Please see our PCI DSS documentation for more information.

Example: "4900000000001234"

Conditions:

Either a pan or a client side encrypted payment method must be provided

cardExpiryDate string

2.1.0 2.2.0

APP BRW 3RI

optional

Expiry date of the PAN or token.

Format: YYMM

Example: "2105"

Length: 4

threeDSCompInd string

2.1.0 2.2.0

BRW

required

Indicates whether the 3DS Method successfully completed.

This should be set to N if the method request has not completed after 10 seconds.

Options:

`Y`	Successfully completed
`N`	Did not successfully complete
`U`	Unavailable - the 3DS Method URL was not present in the Version Response

threeDSRequestorID string

2.1.0 2.2.0

APP BRW 3RI

required

The 3DS requestor identifier assigned by the card scheme.

Example: "example-requestor-id"

Maximum length: 35

threeDSRequestorName string

2.1.0 2.2.0

APP BRW 3RI

required

3DS Requestor name assigned by the card scheme.

Example: "Example Requestor Name"

Maximum length: 40

threeDSRequestorURL string

2.1.0 2.2.0

APP BRW 3RI

required

Fully qualified URL of 3DS Requestor website or customer support website.

Example: "https://www.example-requestor.com"

threeDSRequestorAuthenticationInd string

2.1.0 2.2.0

APP BRW

required

Indicates the type of 3DS authentication request.

Options:

`01`	Payment transaction
`02`	Recurring transaction
`03`	Instalment transaction
`04`	Add card
`05`	Maintain card
`06`	Cardholder verification as part of EMV token ID&V
`07`	Billing Agreement

threeDSRequestorAuthenticationInfo object

2.1.0 2.2.0

APP BRW

optional

Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.

Show definition

threeDSReqAuthMethod string

optional

Mechanism used by the cardholder to authenticate with the 3DS Requestor.

Options:

`01`	Cardholder did not log in	2.1.0 2.2.0
`02`	Cardholder logged in using a username and password	2.1.0 2.2.0
`03`	Cardholder logged in using using federated ID	2.1.0 2.2.0
`04`	Cardholder logged in using using issuer credentials	2.1.0 2.2.0
`05`	Cardholder logged in using using third-party authentication	2.1.0 2.2.0
`06`	Cardholder logged in using using FIDO Authenticator	2.1.0 2.2.0
`07`	Cardholder logged in using using FIDO Authenticator (FIDO assurance data signed)	2.2.0
`08`	SRC Assurance Data	2.2.0

threeDSReqAuthTimestamp string

optional

Date and time in UTC of the cardholder authentication.

Example: "202004011000"

threeDSReqAuthData string

optional

Data that documents and supports a specific authentication process.

threeDSRequestorChallengeInd string

2.1.0 2.2.0

APP BRW

optional

Indicates whether a challenge is requested for this transaction.

Options:

`01`	No preference	2.1.0 2.2.0
`02`	No challenge requested	2.1.0 2.2.0
`03`	Challenge requested (3DS Requestor preference)	2.1.0 2.2.0
`04`	Challenge requested (mandate, e.g. required for PSD2 compliance)	2.1.0 2.2.0
`05`	No challenge requested (transactional risk analysis is already performed)	2.2.0
`06`	No challenge requested (data share only)	2.2.0
`07`	No challenge requested (strong consumer authentication is already performed)	2.2.0
`08`	No challenge requested (utilise whitelist exemption if no challenge required)	2.2.0
`09`	Challenge requested (whitelist prompt requested if challenge required)	2.2.0
`90`	Enable the Cartes Bancaires Scoring Service (Cartes Bancaires only)	2.1.0

threeDSRequestorDecMaxTime string

2.2.0

APP BRW 3RI

optional

Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). Numeric values between 00001 and 10080 are accepted.

Example: "00005"

Length: 5

threeDSRequestorDecReqInd string

2.2.0

APP BRW 3RI

optional

Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use. If the element is not provided, the expected action is for the ACS to default to a value of N (that is, to not use Decoupled Authentication).

Options:

`Y`	Decoupled Authentication is supported and preferred if challenge is necessary
`N`	Do not use Decoupled Authentication

threeDSRequestorPriorAuthenticationInfo object

2.1.0 2.2.0

APP BRW 3RI

optional

Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.

Show definition

threeDSReqPriorAuthMethod string

optional

Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.

Options:

`01`	Frictionless authentication occurred by ACS
`02`	Cardholder challenge occurred by ACS
`03`	AVS verified
`04`	Other issuer methods

threeDSReqPriorAuthTimestamp string

optional

Date and time in UTC of the cardholder authentication.

Format: YYYYMMDDhhmm

threeDSReqPriorRef string

optional

An ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

threeDSReqPriorAuthData string

optional

Data that documents and supports a specific authentication process.

Maximum length: 2048

threeRIInd string

2.1.0 2.2.0

3RI

required

Indicates the type of 3DS requestor initiated request.

Options:

`01`	Recurring transaction	2.1.0 2.2.0
`02`	Instalment transaction	2.1.0 2.2.0
`03`	Add card	2.1.0 2.2.0
`04`	Maintain card information	2.1.0 2.2.0
`05`	Account verification	2.1.0 2.2.0
`06`	Split/delayed shipment	2.2.0
`07`	Top-up	2.2.0
`08`	Mail order	2.2.0
`09`	Telephone order	2.2.0
`10`	Whitelist status check	2.2.0
`11`	Other payment	2.2.0
`12`	Billing Agreement	2.2.0

acctType string

2.1.0 2.2.0

APP BRW 3RI

conditional

Indicates the type of account.

Conditions:

Required in some markets (for example, for merchants in Brazil). Otherwise optional.

Options:

`01`	Not Applicable
`02`	Credit
`03`	Debit

broadInfo object

2.1.0 2.2.0

APP BRW 3RI

optional

Broadcast information - unstructured information sent between the 3DS Server, the DS and the ACS.

Maximum length: 4096

acquirerMerchantID string

2.1.0 2.2.0

APP BRW 3RI

conditional

Acquirer-assigned merchant identifier.

Conditions:

Required for Payment Authentications (PA).

Maximum length: 35

acquirerBIN string

2.1.0 2.2.0

APP BRW 3RI

conditional

Acquiring institution identification code as assigned by the DS receiving the AReq message.

Example: "535522"

Conditions:

Required for Payment Authentications (PA). Required for Visa Non-Payment Authentications (NPA)

Maximum length: 11

notificationURL string

2.1.0 2.2.0

BRW

required

The Challenge Notification URL that will receive the Challenge Response.

Example: "https://www.example-merchant.com/challenge-notification"

Maximum length: 256

recurringExpiry string

2.1.0 2.2.0

APP BRW 3RI

conditional

Date after which no further authorisations shall be performed.

Format: YYYYMMDD

Conditions:

Required when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03)

recurringFrequency string

2.1.0 2.2.0

APP BRW 3RI

conditional

Indicates the minimum number of days between authorisations.

Example: "0031"

Conditions:

Required when threeDSRequestorAuthenticationInd is Recurring transaction (02) or Instalment transaction (03)

Maximum length: 4

purchaseInstalData string

2.1.0 2.2.0

APP BRW 3RI

conditional

Indicates the maximum number of authorisations permitted for instalment payments.

Example: "002"

Conditions:

Required if threeDSRequestorAuthenticationInd is Instalment transaction (03).

Maximum length: 3

transType string

2.1.0 2.2.0

APP BRW 3RI

conditional

Identifies the type of transaction being authenticated.

Conditions:

Required in some markets, when the messageCategory is Payment Authentication (PA) (01).

Options:

`01`	Purchase of goods or services
`03`	Check acceptance
`10`	Account funding
`11`	Quasi-cash transaction
`28`	Prepaid activation and load

browserAcceptHeader string

2.1.0 2.2.0

BRW

conditional

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser.

Example: "text/html,application/xml"

Conditions:

Required when deviceChannel is Browser.

Maximum length: 2048

browserIP string

2.1.0 2.2.0

BRW

optional

IP address of the browser as returned by the HTTP headers to the 3DS Requestor.

Example: "0.0.0.0"

browserJavascriptEnabled boolean

2.2.0

BRW

required

Boolean that represents the ability of the cardholder browser to execute JavaScript.

Example: true

browserJavaEnabled boolean

2.1.0 2.2.0

BRW

conditional

Boolean that represents the ability of the cardholder browser to execute Java.

Example: true

Conditions:

Required when browserJavascriptEnabled is true.

browserLanguage string

2.1.0 2.2.0

BRW

required

The cardholder browser language as defined in IETF BCP47.

Example: "en"

browserColorDepth string

2.1.0 2.2.0

BRW

conditional

The bit depth of the browser's colour palette for displaying images. Use the closest lower option for color depths that are not in the listed options. For example if the color depth is 30, use 24 instead.

Conditions:

Required when browserJavascriptEnabled is true.

Options:

`1`	1 bit per pixel
`4`	4 bits per pixel
`8`	8 bits per pixel
`15`	15 bits per pixel
`16`	16 bits per pixel
`24`	24 bits per pixel
`32`	32 bits per pixel
`48`	48 bits per pixel

browserScreenHeight string

2.1.0 2.2.0

BRW

conditional

Total height of the cardholder’s screen (not browser window) in pixels.

Example: "1080"

Conditions:

Required when browserJavascriptEnabled is true.

Maximum length: 6

browserScreenWidth string

2.1.0 2.2.0

BRW

conditional

Total width of the cardholder’s screen (not browser window) in pixels.

Example: "1920"

Conditions:

Required when browserJavascriptEnabled is true.

Maximum length: 6

browserTZ string

2.1.0 2.2.0

BRW

conditional

Time-zone offset in minutes between UTC and the cardholder browser local time.

Example: "300"

Conditions:

Required when browserJavascriptEnabled is true.

Maximum length: 5

browserUserAgent string

2.1.0 2.2.0

BRW

conditional

Exact content of the HTTP user-agent header.

Example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_0_0) AppleWebKit/0.0 (KHTML, like Gecko) Chrome/0.0.0.0 Safari/0.0"

Conditions:

Required when deviceChannel is Browser.

Maximum length: 2048

sdkTransID string

2.1.0 2.2.0

APP

required

Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. Obtained by calling the getSDKTransactionID() SDK method. See details

Example: "a3384543-b67e-5117-bb34-4567ac6a1123"

Length: 36

sdkAppID string

2.1.0 2.2.0

APP

required

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. Obtained by calling the getSDKAppID() SDK method. See details

Example: "c3994512-a99f-ab17-bb66-4566ac6b1334"

Length: 36

sdkEncData string

2.1.0 2.2.0

APP

required

Device data encrypted by the SDK. Obtained by calling the getDeviceData() SDK method. See details

Maximum length: 64000

sdkEphemPubKey object

2.1.0 2.2.0

APP

required

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. Obtained by calling the getSDKEphemeralPublicKey() SDK method. See details

Maximum length: 256

sdkMaxTimeout string

2.1.0 2.2.0

APP

required

Indicates maximum amount of time (in minutes) for all exchanges.

Example: "05"

Length: 2

sdkReferenceNumber string

2.1.0 2.2.0

APP

required

Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor App.

Example: "3DS_xxx_SDK_xxxx_020200_nnnnn"

Maximum length: 32

deviceRenderOptions object

2.1.0 2.2.0

APP

required

Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK.

Show definition

sdkInterface string

optional

Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.

Options:

`01`	Native
`02`	HTML
`03`	Both

sdkUiType array

optional

Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.

Options:

`01`	Text field
`02`	Single select field
`03`	Multi select field
`04`	OOB
`05`	HTML Other (valid only for HTML UI)

merchantName string

2.1.0 2.2.0

APP BRW 3RI

conditional

Merchant name assigned by the acquirer.

Conditions:

Required for Payment Authentications (PA)

Maximum length: 40

merchantCountryCode string

2.1.0 2.2.0

APP BRW 3RI

conditional

ISO 3166-1 numeric three-digit country code of the merchant.

Example: "826"

Conditions:

Required for Payment Authentications (PA)

Length: 3

mcc string

2.1.0 2.2.0

APP BRW 3RI

conditional

Merchant category code. A card scheme specific code describing the merchant’s type of business, product or service.

Conditions:

Required for Payment Authentications (PA)

Length: 4

merchantRiskIndicator object

2.1.0 2.2.0

APP BRW 3RI

optional

Optional information about the purchase.

Show definition

deliveryEmailAddress string

optional

For electronic delivery, the email address to which the merchandise was delivered.

Example: "customer@example-merchant.com"

Maximum length: 320

deliveryTimeframe string

optional

Indicates the merchandise delivery timeframe.

Options:

`01`	Electronic Delivery
`02`	Same day shipping
`03`	Overnight shipping
`04`	Two-day or more shipping

giftCardAmount string

optional

For prepaid or gift card purchases, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

Example: "123"

giftCardCount string

optional

For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased.

Example: "10"

giftCardCurr string

optional

For prepaid or gift card purchases, the ISO 4217 three-digit currency code of the gift card.

Example: "826"

preOrderPurchaseInd string

optional

Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.

Options:

`01`	Merchandise available
`02`	Future availability

preOrderDate string

optional

For a pre-ordered purchase, the expected date that the merchandise will be available.

Format: YYYYMMDD

reorderItemsInd string

optional

Indicates whether the cardholder is reordering previously purchased merchandise.

Options:

`01`	First time ordered
`02`	Reordered

shipIndicator string

optional

Indicates the shipping method chosen for the transaction.

Options:

`01`	Ship to cardholder’s billing address
`02`	Ship to another verified address on file with merchant
`03`	Ship to address that is different than the cardholder’s billing address
`04`	Ship to store / pick-up at local store (store address shall be populated in shipping address fields)
`05`	Digital goods (includes online services, electronic gift cards and redemption codes)
`06`	Travel and event tickets, not shipped
`07`	Other (for example, gaming, digital services not shipped, emedia subscriptions, etc.)

cardholderName string

2.1.0 2.2.0

APP BRW 3RI

conditional

Name of the cardholder.

As per EMV guidelines, only a specific set of common characters are allowed. Please refer to Annex B ('Common Character Set') of EMV's Book 4 for more information.

Example: "John Smith"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Minimum length: 2

Maximum length: 45

acctID string

2.1.0 2.2.0

APP BRW 3RI

optional

Cardholder account identifier. The customerId may be used for this field.

Maximum length: 64

acctInfo object

2.1.0 2.2.0

APP BRW 3RI

optional

Information about the cardholder's account.

Show definition

chAccAgeInd string

optional

Length of time that the cardholder has had the account.

Options:

`01`	No account (guest check-out)
`02`	Changed during this transaction
`03`	Less than 30 days
`04`	30−60 days
`05`	More than 60 days

chAccChange string

optional

Date that the cardholder’s account was last changed, including billing or shipping address, new payment account, or new user(s) added.

Format: YYYYMMDD

chAccChangeInd string

optional

Time since the cardholder’s account information was last changed, including billing or shipping address, new payment account, or new user(s) added.

Options:

`01`	Changed during this transaction
`02`	Less than 30 days
`03`	30−60 days
`04`	More than 60 days

chAccDate string

optional

Date that the cardholder opened the account.

Format: YYYYMMDD

chAccPwChange string

optional

Date that cardholder last changed their password or had their account reset.

Format: YYYYMMDD

chAccPwChangeInd string

optional

Time since the cardholder last changed their password or had their account reset.

Options:

`01`	No change
`02`	Changed during this transaction
`03`	Less than 30 days
`04`	30−60 days
`05`	More than 60 days

nbPurchaseAccount string

optional

Number of purchases by this cardholder account during the last six months.

Example: "10"

txnActivityDay string

optional

Number of transactions (successful and abandoned) by this cardholder account across all payment methods in the last 24 hours.

Example: "1"

txnActivityYear string

optional

Number of transactions (successful and abandoned) by this cardholder account across all payment methods in the last year.

Example: "5"

paymentAccAge string

optional

Date that the payment method was added to the cardholder’s account.

Format: YYYYMMDD

paymentAccInd string

optional

Indicates the length of time since the payment method was added to the cardholder’s account.

Options:

`01`	No account (guest check-out)
`02`	During this transaction
`03`	Less than 30 days
`04`	30−60 days
`05`	More than 60 days

shipAddressUsage string

optional

Date when the shipping address used for this transaction was first used with the 3DS Requestor.

Format: YYYYMMDD

shipAddressUsageInd string

optional

Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.

Options:

`01`	This transaction
`02`	Less than 30 days
`03`	30−60 days
`04`	More than 60 days

shipNameIndicator string

optional

Indicates if the cardholder name on the account is identical to the shipping name used for this transaction.

Options:

`01`	Account name identical to shipping name
`02`	Account name different than shipping name

suspiciousAccActivity string

optional

Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Options:

`01`	No suspicious activity has been observed
`02`	Suspicious activity has been observed

email string

2.1.0 2.2.0

APP BRW 3RI

conditional

The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor.

Example: "customer@example.com"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 254

homePhone object

2.1.0 2.2.0

APP BRW 3RI

optional

Home phone number. Refer to ITU-E.164 for additional information on format and length.

Show definition

cc string optional	Country code. Example: `"44"`
subscriber string optional	Subscriber number. Example: `"1234567899"` Maximum length: 15

mobilePhone object

2.1.0 2.2.0

APP BRW 3RI

optional

Mobile phone number. Refer to ITU-E.164 for additional information on format and length.

Show definition

cc string optional	Country code. Example: `"44"`
subscriber string optional	Subscriber number. Example: `"1234567899"` Maximum length: 15

workPhone object

2.1.0 2.2.0

APP BRW 3RI

optional

Work phone number. Refer to ITU-E.164 for additional information on format and length.

Show definition

cc string optional	Country code. Example: `"44"`
subscriber string optional	Subscriber number. Example: `"1234567899"` Maximum length: 15

addrMatch string

2.1.0 2.2.0

APP BRW

optional

Indicates whether the billing address and shipping address are the same.

Options:

`Y`	Billing address matches shipping address
`N`	Billing address does not match shipping address

billAddrLine1 string

2.1.0 2.2.0

APP BRW 3RI

conditional

First line of the billing address associated with the card used for this purchase.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

billAddrLine2 string

2.1.0 2.2.0

APP BRW 3RI

conditional

Second line of the billing address associated with the card used for this purchase.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

billAddrLine3 string

2.1.0 2.2.0

APP BRW 3RI

conditional

Third line of the billing address associated with the card used for this purchase.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

billAddrCity string

2.1.0 2.2.0

APP BRW 3RI

conditional

The city of the billing address associated with the card used for this purchase.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

billAddrState string

2.1.0 2.2.0

APP BRW 3RI

conditional

ISO 3166-2 country subdivision code for the state or province of the billing address associated with the card used for this purchase.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 3

billAddrPostCode string

2.1.0 2.2.0

APP BRW 3RI

conditional

ZIP or other postal code of the billing address associated with the card used for this purchase.

Example: "EC1V 9BP"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 16

billAddrCountry string

2.1.0 2.2.0

APP BRW 3RI

conditional

The numeric country code of the billing address associated with the card used for this purchase.

Example: "826"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Length: 3

shipAddrLine1 string

2.1.0 2.2.0

APP BRW 3RI

conditional

First line of the shipping address requested by the cardholder.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

shipAddrLine2 string

2.1.0 2.2.0

APP BRW 3RI

conditional

Second line of the shipping address requested by the cardholder.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

shipAddrLine3 string

2.1.0 2.2.0

APP BRW 3RI

conditional

Third line of the shipping address requested by the cardholder.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

shipAddrCity string

2.1.0 2.2.0

APP BRW 3RI

conditional

City of the shipping address requested by the cardholder.

Example: "London"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 50

shipAddrState string

2.1.0 2.2.0

APP BRW 3RI

conditional

ISO 3166-2 country subdivision code for the state or province of the shipping address requested by the cardholder.

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 3

shipAddrPostCode string

2.1.0 2.2.0

APP BRW 3RI

conditional

The ZIP or other postal code of the shipping address requested by the cardholder.

Example: "EC1V 9BP"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Maximum length: 16

shipAddrCountry string

2.1.0 2.2.0

APP BRW 3RI

conditional

Numeric country of the shipping address requested by the cardholder.

Example: "826"

Conditions:

Required unless a market or regional mandate restricts sending this information.

Length: 3

messageExtension array

2.1.0 2.2.0

APP BRW 3RI

optional

Data necessary to support requirements not otherwise defined in the 3D Secure message format.

Show definition

id string optional	A unique identifier for the extension. Example: `"id-123"`
name string optional	The name of the extension as defined by the extension owner. Example: `"Extension Name"`
criticalityIndicator boolean optional	Indicates whether the recipient must understand the contents of the extension to interpret the entire message.
data object,array,boolean,integer,number,string optional	The data carried in the extension.

Authenticate Response

Show all

timestamp integer

A Unix timestamp indicating when we finished handling the request.

Example: 1512828988

status integer

The HTTP response status code.

Example: 200

cardScheme string

2.1.0 2.2.0

The card scheme which the card uses.

Example: "Visa"

liabilityShifted boolean

Whether liability for this transaction was shifted to the issuer. See Liability Shift.

Example: true

data object

Response payload.

Hide definition

messageVersion string

2.1.0 2.2.0

APP BRW 3RI

3DS protocol version identifier.

threeDSServerTransID string

2.1.0 2.2.0

APP BRW 3RI

The unique identifier (UUID) for tracking the transaction throughout the 3DS process.

Example: "c5584543-b67e-5117-bb34-3567ac6a1123"

sdkTransID string

2.1.0 2.2.0

APP

Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

Example: "a3384543-b67e-5117-bb34-4567ac6a1123"

acsTransID string

2.1.0 2.2.0

APP BRW 3RI

The unique identifier (UUID) used by the ACS for tracking the transaction throughout the 3DS process.

Must be provided in the Challenge Request.

May be provided in the threeDSReqPriorRef field in order to identify a prior authentication.

Example: "214a549e-2310-4359-b590-c53a20adcc78"

dsTransID string

2.1.0 2.2.0

APP BRW 3RI

The unique identifier (UUID) used by the directory server for tracking the transaction throughout the 3DS process. Provided for information only.

Example: "a3384543-b67e-5117-bb34-4567ac6a1123"

dsReferenceNumber string

2.1.0 2.2.0

APP BRW 3RI

A unique identifier assigned to the directory server by EMVCo. Provided for information only.

Example: "3DS_LOA_DIS_ABCD_020200_00001"

acsReferenceNumber string

2.1.0 2.2.0

APP BRW 3RI

A unique identifier assigned to the ACS by EMVCo. Provided for information only.

Example: "3DS_LOA_ACS_ABCD_020200_00001"

authenticationType string

2.1.0 2.2.0

APP BRW

The type of authentication the issuer will use to challenge the Cardholder.

Options:

`01`	Static, for example, a password or passcode
`02`	Dynamic, for example, a one time password (OTP)
`03`	Out-of-Band (OOB), for example, using the issuing bank's mobile app
`04`	Decoupled Authentication

authenticationValue string

2.1.0 2.2.0

APP BRW 3RI

The card scheme specific value to be used for authorising the transaction. Also referred to as "CAVV" (Cardholder Authentication Verification Value) by Visa, AAV (Accountholder Authentication Value) by Mastercard and AEVV (American Express Verification Value) by American Express.

On Non-Payment Authentications (NPA) no value is returned by American Express or Mastercard, even if they are successful.

There are limitations on when and for how long the authenticationValue can be stored.

Please refer to the Payment Card Industry 3-D Secure (PCI 3DS) guide for further details.

transStatus string

2.1.0 2.2.0

APP BRW 3RI

Indicates the outcome of the authenticate request, and how to proceed.

Options:

`Y`	Authentication Successful	The transaction achieved a Frictionless authentication, continue to authorisation using the authenticationValue.
`A`	Authentication Attempted	3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer's behalf.
`N`	Authentication Failed	The authentication failed, stop processing the transaction.
`U`	Authentication Unavailable	Authentication could not be performed. You may attempt to proceed to authorisation without an authenticationValue.
`C`	Challenge Required	A challenge is required, make a Challenge Request.
`D`	Decoupled Challenge Required	A challenge will be performed by the issuer without using a 3DS Challenge Request. Make a Result Request to learn the final outcome. You may need to wait the length of time set in the threeDSRequestorDecMaxTime Authenticate Request field.
`R`	Authentication Rejected	The issuer rejected the authentication attempt and requests that authorisation is not attempted.
`I`	Informational Only	Authentication for the transaction was not requested. The data was sent to the ACS for informational purposes only.

transStatusReason string

2.1.0 2.2.0

APP BRW 3RI

Provides information on the transStatus value.

Options:

`01`	Card authentication failed
`02`	Unknown device
`03`	Unsupported device
`04`	Exceeds authentication frequency limit
`05`	Expired card
`06`	Invalid card number
`07`	Invalid transaction
`08`	No card record
`09`	Security failure
`10`	Stolen card
`11`	Suspected fraud
`12`	Transaction not permitted to cardholder
`13`	Cardholder not enrolled in service
`14`	Transaction timed out at the ACS
`15`	Low confidence
`16`	Medium confidence
`17`	High confidence
`18`	Very high confidence
`19`	Exceeds ACS maximum challenges
`20`	Non-payment (NPA) transaction not supported
`21`	3RI transaction not supported
`22`	ACS technical issue
`23`	Decoupled authentication required by ACS but not requested by 3DS Requestor
`24`	3DS Requestor decoupled authentication max expiry time exceeded
`25`	Insufficient time provided for decoupled authentication to authenticate cardholder. ACS will not attempt authentication
`26`	Authentication attempted but not performed by the cardholder

eci string

2.1.0 2.2.0

APP BRW 3RI

Electronic Commerce Indicator

Options:

`00`	Authentication Failed	Mastercard
`01`	Authentication attempted, but not completed	Mastercard
`02`	Authentication Successful	Mastercard
`05`	Authentication Successful	Visa, American Express, Discover, JCB, UnionPay
`06`	Authentication attempted, but not completed	Visa, American Express, Discover, JCB, UnionPay
`07`	Authentication Failed	Visa, American Express, Discover, JCB, UnionPay
`N0`	Not Authenticated (NPA)	Mastercard
`N2`	Authenticated (NPA)	Mastercard

acsChallengeMandated string

2.1.0 2.2.0

APP BRW 3RI

Indicates whether regional mandates (e.g. PSD2) require a challenge to be performed. If using the 3RI device channel, a decoupled challenge must be used.

Options:

`Y`	Challenge is mandated
`N`	Challenge is not mandated

acsDecConInd string

2.2.0

APP BRW 3RI

Indicates whether the ACS will use decoupled authentication.

Options:

`Y`	Decoupled authentication will be used
`N`	Decoupled authentication will not be used

acsRenderingType object

2.1.0 2.2.0

APP

Indicates whether the ACS will use decoupled authentication.

Show definition

acsInterface string

The user interface type which the ACS will use to present the challenge.

Options:

`01`	Native UI
`02`	HTML UI

acsUiTemplate string

The user interface template which the ACS will present to the cardholder.

Options:

`01`	Text field
`02`	Single select field (e.g. dropdown field)
`03`	Multi select field (e.g. checkbox fields)
`04`	Out-of-Band (OOB) (e.g. using the issuing bank's mobile app)
`05`	HTML other

acsSignedContent string

2.1.0 2.2.0

APP

A JSON Web Signature (JWS) object containing the ACS URL, ACS ephemeral public key and SDK ephemeral public key. These are used by the SDK to communicate securely with the ACS when performing the challenge.

acsURL string

2.1.0 2.2.0

BRW

The URL of the ACS to be used for the challenge.

cardholderInfo string

2.1.0 2.2.0

APP BRW 3RI

Text provided by the issuer to be displayed to the cardholder.

whiteListStatus string

2.2.0

APP BRW 3RI

Indicates whether the cardholder has added the merchant to their list of trusted merchants. A cardholder can typically only choose to trust a merchant after successfully completing a challenge. A cardholder may not be required to complete a challenge with a merchant they have previously trusted.

Options:

`Y`	Merchant is trusted by cardholder
`N`	Merchant has not yet been trusted by cardholder
`E`	Not eligible as determined by issuer
`P`	Pending confirmation by cardholder
`R`	Cardholder rejected the request to trust the merchant
`U`	Trusted status unknown, unavailable, or does not apply

whiteListStatusSource string

2.2.0

APP BRW 3RI

Identifies the system which set the whiteListStatus value.

Options:

`01`	3DS Server
`02`	Directory Server (DS)
`03`	Access Control Server (ACS)

messageExtension array

2.1.0 2.2.0

APP BRW 3RI

Data necessary to support requirements not otherwise defined in the 3D Secure message format.

Show definition

id string	A unique identifier for the extension. Example: `"id-123"`
name string	The name of the extension as defined by the extension owner. Example: `"Extension Name"`
criticalityIndicator boolean	Indicates whether the recipient must understand the contents of the extension to interpret the entire message.
data object,array,boolean,integer,number,string	The data carried in the extension.

Feedback

Was this page helpful?