This guide describes the changes to the request and response formats for version 2.3.1 relative to version 2.2.0.
Each field in a request or response section is linked through to its detailed definition on the corresponding 3DS API endpoints page.
These are the changes to the Authenticate Request for version 2.3.1.
These are changes to the existing fields on the Authenticate Request for version 2.3.1.
| Field | Description of change | Action required |
|---|---|---|
threeDSRequestorAuthenticationInfo | from string to an array of strings | Single string or array of strings accepted; consider using an array if you want to provide multiple values for this field on 2.3.1 requests |
threeDSRequestorChallengeInd | from object to array of objects | Single object or array of objects accepted; consider using an array if you want to provide multiple instances of this field on 2.3.1 requests |
threeDSRequestorPriorAuthenticationInfo | from object to array of objects | Single object or array of objects accepted; consider using an array if you want to provide multiple instances of this field on 2.3.1 requests |
whiteListStatus | renamed to trustListStatus | For maintaining backward compatibility we accept either field name. |
whiteListStatusSource | renamed to trustListStatusSource | For maintaining backward compatibility we accept either field name. |
authenticationType | changed to authenticationMethod | On 2.1.0 and 2.2.0 responses the original authenticationType will be returned. On 2.3.1 responses the authenticationMethod will be mapped to an equivalent authenticationType |
These are the new fields on the Authenticate Request for version 2.3.1.
| Field | Description of change | Required, Conditional, Optional |
|---|---|---|
acceptLanguage | browser language preference | Required (BRW) |
acquirerCountryCode | country code of acquirer | Required (APP, BRW, 3RI) |
appIp | IP address used by the 3DS Requestor App | Optional |
cardSecurityCode | three or four-digit security code printed on the card | Conditional — based on DS rules |
defaultSdkType | indicates the characteristics of a Default-SDK | Optional |
deviceBindingStatus | to allow devices to be remembered as trusted | Optional |
deviceBindingStatusSource | source of device binding status | Optional |
deviceId | unique and immutable identifier linked to a device | Conditional — required if available |
multiTransaction | additional transaction information in case of multiple transactions or Merchants | Optional |
payeeOrigin | origin of Payee for SPC Transaction data | Optional |
recurringAmount | amount for recurring payments | Conditional |
recurringCurrency | currency for recurring amount | Conditional — required when recurringAmount is provided |
recurringDate | date for recurring amount | Conditional — required if recurringInd (01) or recurringFrequency (01) |
recurringExponent | exponent for recurring amount | Conditional — required when recurringAmount is provided |
recurringInd | indicator for recurring payment | Conditional — required when threeDSRequestorAuthenticationInd is Recurring (02) or Instalment (03), or threeRIInd is Recurring (01) or Instalment (02) |
sdkType | type of 3DS SDK | Required (APP) |
splitSdkType | indicates the characteristics of a Split-SDK | Conditional — required if sdkType = 02 |
sdkServerSignedContent | signed content for Split-SDK | Conditional — required if sdkType = 02 |
sdkSignatureTimestamp | timestamp of signed content | Optional |
threeDSMethodId | allows Method requests to be reused | Conditional — required if 3DS Requestor reuses a previous 3DS Method execution |
sellerInfo | additional transaction information regarding sellers | Optional |
threeDSRequestorSpcSupport | indicates 3DS Requestor support for SPC | Optional |
taxId | cardholder’s tax identification | Optional |
userId | identifier of the transacting user’s Browser Account ID | Conditional — required if available |
These are the changes in permitted values for existing fields on the Authenticate Request.
| Field | Description of change |
|---|---|
threeRIInd | additional values for version 2.3.1 |
These are the changes to the Authenticate Response for version 2.3.1.
These are changes to existing fields on the Authenticate Response for version 2.3.1.
| Field | Description of change | Action required |
|---|---|---|
authenticationType | changed to authenticationMethod | On 2.1.0 and 2.2.0 responses the original authenticationType will be returned. On 2.3.1 responses the authenticationMethod will be mapped to an equivalent authenticationType |
whiteListStatus | renamed to trustListStatus | For maintaining backward compatibility we accept either field name. |
whiteListStatusSource | renamed to trustListStatusSource | For maintaining backward compatibility we accept either field name. |
These are new fields on the Authenticate Response for version 2.3.1.
| Field | Description of change |
|---|---|
authenticationMethod | Finer granularity than legacy authenticationType. On 2.3.1 responses authenticationMethod is returned from the scheme; on 2.1.0 and 2.2.0 we map authenticationType onto the nearest equivalent authenticationMethod. |
cardholderInfoIssuerImage | the URL of the issuer’s logo or image to be displayed to the cardholder. |
cardholderInfoPaymentSystemImage | the URL of the payment system’s logo or image to be displayed to the cardholder |
cardSecurityCodeStatus | enables the communication of Card Security Code Status between the ACS, the DS and the 3DS Requestor |
cardSecurityCodeStatusSource | populated by the system setting Card Security Code Status |
deviceBindingStatus | to allow devices to be remembered as trusted |
deviceBindingStatusSource | source of device binding status |
deviceRecognisedVersion | the highest Data Version of the Device Information supported by the ACS |
spcTransData | information that the 3DS Requestor passes in the SPC API for display in the Smart Modal Window |
threeDSRequestorAppURLInd | indicates whether the OOB Authentication App used by the ACS during a challenge supports the 3DS Requestor App URL |
transChallengeExemption | exemption applied by the ACS to authenticate the transaction without requesting a challenge |
transStatusReasonInfo | transaction Status Reason Information |
webAuthnCredList | list of WebAuthn credentials that the ACS can use to authenticate the cardholder |
These are changes in permitted values for existing fields on the Authenticate Response.
| Field | Description of change |
|---|---|
transStatus | additional values for 2.3.1 |
transStatusReason | additional values for 2.3.1 |
No changes have been made to the Result Request for version 2.3.1.
These are changes to the Result Response for version 2.3.1.
These are changes to existing fields on the Result Response for version 2.3.1.
| Field | Description of change | Action required |
|---|---|---|
authenticationType | changed to authenticationMethod | On 2.1.0 and 2.2.0 responses the original authenticationType will be returned. On 2.3.1 responses the authenticationMethod will be mapped to an equivalent authenticationType |
whiteListStatus | renamed to trustListStatus | For maintaining backward compatibility we accept either field name. |
whiteListStatusSource | renamed to trustListStatusSource | For maintaining backward compatibility we accept either field name. |
These are new fields on the Result Response for version 2.3.1.
| Field | Description of change |
|---|---|
acsRenderingType | identifies the type of UI the ACS presents to the consumer |
acsTransID | unique identifier (UUID) used by the Issuer for tracking the transaction throughout the 3DS process |
authenticationMethod | Finer granularity than legacy authenticationType. On 2.3.1 responses authenticationMethod is returned from the scheme; on 2.1.0 and 2.2.0 we map authenticationType onto the nearest equivalent authenticationMethod. |
cardholderInfo | information about the cardholder. |
challengeErrorReporting | error message sent or received by the ACS in case of error in the CReq/CRes messages |
deviceBindingStatus | to allow devices to be remembered as trusted |
deviceBindingStatusSource | source of device binding status |
dsTransID | unique identifier (UUID) used by the Scheme for tracking the transaction throughout the 3DS process |
transStatusReasonInfo | transaction Status Reason Information |
These are changes in permitted values for existing fields on the Result Response.
| Field | Description of change |
|---|---|
challengeCancel | additional values for 2.3.1 |
transStatus | additional values for 2.3.1 |
transStatusReason | additional values for 2.3.1 |
Was this page helpful?