POST
The 3DS Requestor initiates the Authentication Request by calling the /pArq or /auth method on the D8 3DSS.
api/pArq is considered as "legacy" method. New method name is /auth. However, api/pArq is not deprecated and is used by D8. Despite the name difference both methods accept identical payloads and behave the same internally.
Sends valid pArq object provided as JSON object.
| Name | Pattern | Mandatory | Description |
|---|---|---|---|
| messageCategory | Length: 2 characters JSON Data Type: String Values accepted: • 01 = PA • 02 = NPA |
Mandatory | Identifies the category of the message for a specific use case. |
| notificationURL | Length: Variable, maximum 256 characters JSON Data Type: String Value accepted: Fully Qualified URL |
Mandatory | Fully qualified URL of the system that receives the CRes message or Error Message. The CRes message is posted by the ACS through the Cardholder browser at the end of the challenge. |
| deviceRenderOptions | Length: Variable JSON Data Type: Object Refer to Table A.13 for data elements to include. Note: Data will be formatted into a JSON object prior to being placed into the Device Rendering Options Supported field of the message. |
Mandatory | Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK. |
| acquirerMerchantID | Length: Variable, maximum 35 characters JSON Data Type: String Value accepted: Individual Directory Servers may impose specific format and character requirements on the contents of this field. |
Mandatory | Acquirer-assigned Merchant identifier. This may be the same value that is used in authorisation requests sent on behalf of the 3DS Requestor and is represented in ISO 8583 formatting requirements. |
| acctNumber | Length: Variable, 13–19 characters JSON Data Type: String Value accepted: Format represented ISO 7812. |
Mandatory | Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, token. |
| purchaseAmount | Length: Variable, maximum 48 characters JSON Data Type: String Example: purchase amount is USD 123.45, Example values accepted: • 12345 • 012345 • 0012345 |
Mandatory | Purchase amount in minor units of currency with all punctuation removed. When used in conjunction with the Purchase Currency Exponent field, proper punctuation can be calculated. |
| purchaseCurrency | Length: 3 characters, Numeric JSON Data Type: String ISO 4217 three-digit currency code. |
Mandatory | Currency in which purchase amount is expressed. |
| purchaseExponent | Length: 1 character JSON Data Type: String |
Mandatory | Minor units of currency as specified in the ISO 4217 currency exponent. Example: • USD = 2 • Yen = 0 |
| purchaseDate | Length: 14 characters JSON Data Type: String Format accepted: YYYYMMDDHHMMSS |
Mandatory | Date and time of the purchase expressed in UTC. |
| deviceChannel | Length: 2 characters JSON Data Type: String Values accepted: • 01 = App-based(APP) • 02 = Browser (BRW) • 03 = 3DS Requestor Initiated (3RI) |
Mandatory | Indicates the type of channel interface being used to initiate the transaction. |
| sdkAppID | Length: 36 characters JSON Data Type: String Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions as long as the output meets specified requirements. |
Mandatory | 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. |
| sdkEphemPubKey | Length: Variable, maximum 256 characters JSON Data Type: Object JWK |
Mandatory | 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. In AReq, this data element is present as its own object. In ARes, this data element is contained within the ACS Signed Content JWS Object. |
| sdkMaxTimeout | Length: 2 characters JSON Data Type: String Values accepted: • Greater than or = 05 |
Mandatory | Indicates maximum amount of time (in minutes) for all exchanges. |
| sdkReferenceNumber | Length: Variable, maximum 32 characters JSON Data Type: String |
Mandatory | 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. |
| sdkTransID | Length: 36 characters JSON Data Type: String Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions if the output meets specified requirements. |
Mandatory | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. |
| sdkEncData | Length: Variable, maximum 64000 characters JSON Data Type: String |
Mandatory | JWE Object (represented as a string) containing data encrypted by the SDK for the DS to decrypt. Note: This element is the only field encrypted in this version of the EMV 3-D Secure specification. |
| Name | Pattern | Mandatory | Description |
|---|---|---|---|
| threeDSServerTransID | Length: 36 characters JSON Data Type: String Value accepted: Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements |
Mandatory | A unique identifier for the transaction that will be the same as the 3DS Server Transaction ID in the AReq |
| acsReferenceNumber | Length: Variable, maximum 32 characters JSON Data Type: String Value accepted: Set by the EMVCo Secretariat. |
Mandatory | Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. |
| acsChallengeMandated | Length: 1 character JSON Data Type: String Values accepted: • Y = Challenge is mandated • N = Challenge is not mandated |
Mandatory | Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable. |
| acsRenderingType | JSON Data Type: Object Note: Data will be formatted into a JSON object prior to being placed into the acsRenderingType field of the message. |
Mandatory | Identifies the ACS UI Template that the ACS will first present to the consumer. |
| dsReferenceNumber | Length: Variable, maximum 32 characters JSON Data Type: String |
Mandatory | EMVCo-assigned unique identifier to track approved DS |
| authenticationType | Length: 2 characters JSON Data Type: String Values accepted: • 01 = Static • 02 = Dynamic • 03 = OOB • 04 = Decoupled |
Mandatory | Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. |
| authenticationValue | Length: 28 characters JSON Data Type: String Value accepted: A 20-byte value that has been Base64 encoded, giving a 28-byte result. |
Mandatory | Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. |
| transStatus | Length: 1 character JSON Data Type: String Refer to EMV 3-D Secure Protocol and Core Functions Specification for the particular value. |
Mandatory | Indicates whether a transaction qualifies as an authenticated transaction or account verification. |
| sdkTransID | Length: 36 characters JSON Data Type: String Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions if the output meets specified requirements. |
Mandatory | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. |
| acsURL | Length: Variable, maximum 2048 characters JSON Data Type: String Value accepted: Fully qualified URL. For example: https://server.acsdomainname.com |
Mandatory | Fully qualified URL of the ACS to be used for the challenge. 01-APP—SDK will send the Challenge Request to this URL 02-BRW—3DS Requestor will post the CReq to this URL via the challenge window For App-based, this data element is contained within the ACS Signed Content JWS Object. For Browser-based, this data element is present as its own object. |
| dsTransID | Length: 36 characters JSON Data Type: String Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions if the output meets specified requirements. |
Mandatory | Universally unique transaction identifier assigned by the DS to identify a single transaction. |
| messageVersion | Length: Variable, 5–8characters JSON Data Type: String Value accepted: • 2.1.0 • 2.2.0 |
Mandatory | Protocol version identifier. This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. |
| messageType | Length: 4 characters JSON Data Type: String Values accepted: • AReq • ARes • CReq • CRes • PReq • PRes • RReq • RRes • Erro |
Mandatory | Identifies the type of message that is passed. |
| acsTransID | Length: 36 characters JSON Data Type: String Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions if the output meets specified requirements. |
Mandatory | Universally Unique transaction identifier assigned by the ACS to identify a single transaction. |
| eci | Length: 2 characters JSON Data Type: String Values accepted: • Payment System specific |
Mandatory | Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. |
{
"acctNumber": "5500000000001002",
"acquirerMerchantID": "ABC00000",
"addrMatch": "Y",
"cardExpiryDate": "2212",
"deviceChannel": "01",
"deviceRenderOptions": {
"sdkUiType": [
"01",
"02",
"03",
"04",
"05"
],
"sdkInterface": "03"
},
"messageCategory": "01",
"notificationURL": "http://requestor.com/api/cresponse",
"purchaseAmount": "100",
"purchaseCurrency": "840",
"purchaseDate": "20200610131735",
"purchaseExponent": "2",
"threeDSRequestorAuthenticationInd": "01",
"threeDSRequestorChallengeInd": "01",
"sdkEphemPubKey": {
"kty": "EC",
"crv ": "P-256",
"x": "UkcaABSIQfugqTC1cYisPkGNkofsWsNKAhAyTM8shM4",
"y": "wRzN5Hp-b0WEDyUaX6sh5N-hDCZFE2MxXeKCrxAhrJo"
},
"sdkMaxTimeout": "05",
"sdkReferenceNumber": "3DS_LOA_SDK_AAAA_000000_00000",
"sdkAppID": "0d858d97-f4d7-43fd-b483-737ac5907a07",
"sdkEncData": "sdkEncData",
"sdkTransID": "a850f2a6-a8f8-4ba4-b3a5-823e49d88e12"
}
{
"acsChallengeMandated": "N",
"acsReferenceNumber": "3DS_LOA_ACS_AAAA_000000_00000",
"acsTransID": "417e6d77-229a-4de1-bd9b-e7e6b1e05c21",
"acsOperatorID": "00000014",
"acsURL": "https://acs.vendorcert.com/creq",
"authenticationType": "01",
"dsReferenceNumber": "3DS_LOA_DIS_AAAA_000000_00000",
"dsTransID": "843f1784-52f8-5bba-8000-000000605627",
"eci": "05",
"messageType": "pArs",
"messageVersion": "2.1.0",
"threeDSServerTransID": "bd7cab21-dcc3-4a5d-a3f4-9ceeb383086d",
"transStatus": "Y"
}
The Device Rendering Options Supported contains information about the rendering types and interface that the device supports.
All Device Rendering Options must be supported by all components.
| Data Element/Field Name | Description | Length/Format/Values |
|---|---|---|
| SDK Interface Field Name: sdkInterface |
Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. | Length: 2 characters JSON Data Type: String Values accepted: • 01 = Native • 02 = HTML • 03 = Both |
| SDK UI Type Field Name: sdkUiType |
Lists all UI types that the device supports for displaying specificchallenge 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. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined by this specification). |
Length: 2 characters JSON Data Type: Array of String String values accepted: • 01 = Text • 02 = Single Select • 03 = Multi Select • 04 = OOB • 05 = HTML Other (valid only for HTML UI) |
{
"deviceRenderOptions": {
"sdkInterface": "03",
"sdkUiType": [
"01",
"02",
"03",
"04",
"05"
]
}
}
The ACS Rendering Type contains information about the rendering type that the ACS is sending for the cardholder authentication.
| Data Element/Field Name | Description | Length/Format/Values |
|---|---|---|
| ACS Interface Field Name: acsInterface |
This the ACS interface that the challenge will present to the cardholder. | Length: 2 characters JSON Data Type: String Values accepted: • 01 = Native UI • 02 = HTML UI |
| ACS UI Template Field Name: acsUiTemplate |
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 Note: HTML Other is the only valid in combination with 02 = HTML UI. If used with 01 = Native UI, the DS will respond with Error = 203 |
Length: 2 characters JSON Data Type: String Values accepted: • 01 = Text • 02 = Single Select • 03 = Multi Select • 04 = OOB • 05 = HTML Other |
{
"acsRenderingType": {
"acsInterface": "02",
"acsUiTemplate": "03"
}
}