Authentication Request (Lookup)

externalReferenceId

String

50 digits

Unique Id for this authentication transaction (MerchantReferenceNumber)

Required

ddcId

String

50 digits

Same value in DDC request

Required

threeDsRequestorAuthInd

String

2 digits

PaymentTransaction = "01"

RecurringTransaction = "02"

InstalmentTransaction = "03"

AddCard = "04"

MaintainCard = "05"

CardholderVerification = "06"

Indicates the type of Authentication request

Required

session

String

1024 chars

3DS Requestor session data that is returned by the ACS in the final CRes

Optional

browserInfo

Object

table "Browser"

See Browser Fields format and description

Information about cardholder browser

Required

notificationUrl

String

Uri

Url where will send final CRes at end of challenge. If null, 3DS Server will receive final CRes

Optional

challengeWindowSize

Int

1 digit

250 X 400 =1,
390 X 400 =2,
500 X 600 =3,
600 X 400 = 4,
Full Screen = 5

Dimensions of the challenge window that has been displayed to the Cardholder, in pixels

Optional

Default = 3

acquirerCode

String

max 15 chars

BANK CODE

Code of Acquirer -
Provided by 2c2p for each partner/merchant/acquirer.
For 3DS Requestor this is always will be “3DS Requestor”

Required

acquirerBIN

Override the acquiring institution identification code (the Acquirer BIN) that is currently configured in the 2C2P profile.

Required

merchantCode

String

max 35 chars

Override the Acquirer Merchant identifier configured in the Merchant's profile. Same as the merchantId.

Required

deviceChannel

Int

1 digit

2

Device Channel, valid value follows:
1- App (App-based)
2 - BRW (Browser-based)
3 - 3RI

Required

messageCategory

String

2 digits

"01"

"01" - Payment
"02" - Non payment

Required

threeDsRequestorChallengeInd

Int

1 digit

NoPreference = 1,

NoChallengeRequested = 2,

ChallengeRequested = 3,

ChallengeRequired = 4

No challenge requested (strong consumer authentication is already performed) = 7

Indicates whether a challenge is requested for this transaction
Default = 1

Optional

messageVersion

String

8 digits

Values active:
2.0.0 Deprecated
2.1.0 Active
2.2.0 Active
2.3.0 Pending

Protocol version identifier This shall be the Protocol Version Number of the specification utilized by the system creating this message.

Optional

requestFeatures

integer

Values accepted:
0 to 99

Indicates whether the 3DS Requestor requests the ACS to utilize Visa DAF, Decoupled Authentication, Merchants WhiteList. (for 2.2.0 protocol)

"0" - No Features - Enable only this feature - 0(0000),

"1" - DAF Feature - Enable only this feature - 1(0001),

"2" - Merchant WhiteList - Enable only this feature - 2(0010),

"3" - Decouple Authentication - Enable only this feature - 4(0100)

Optional

threeDsRequestorDecMaxTime

integer

5 digits

Values accepted:
1-10080 (default=15)

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).

Optional

threeDsRequestorAuthenticationInfo

Object

table "3DS Requestor Authentication Information"

See 3DS Requestor Authentication Information Fields format and description

Require if threeDsRequestorChallengeInd = 7

card

Object

table "Card"

See Card Fields format and description

Required

merchantName

String

maximum 50 chars

“MERCHANT COMP1”

This is 3DS Requestor merchant name which will be displayed on OTP Challenge page to customer

Optional

purchase

Object

table "Purchase"

See Purchase Fields format and description

Purchase information.
Can't use for 3RI

Required if messageCategory is "01"

recurring

Object

table "Recurring"

See Recurring Fields format and description

Recurring information.
Can't use for 3RI

Optional

instalmentData

Int

Indicates the maximum number of authorizations permitted for instalment payments.
Can't use for 3RI

Required, if "threeDsRequestorAuthInd " is "03"

requestor

Object

table "Requestor"

See Requestor Fields format and description

Information about initiator of 3DS flow

Optional.
If null - 3DS Server becomes Requestor.

billingAddress

Object

table "Address"

See Address Fields format and description

Information about billing address of cardholder

Optional. Some ACS may require it.

shippingAddress

Object

table "Address"

See Address Fields format and description

Information about shipping address of cardholder

Optional. Some ACS may require it.

email

String

maximum 254 characters

test@test.com

Cardholder email

Optional. Some ACS may require it.

homePhone

Object

table "Phone"

See Phone Fields format and description

Cardholder home phone number

Optional. Some ACS may require it.

mobilePhone

Object

table "Phone"

See Phone Fields format and description

Cardholder mobile phone number

Optional. Some ACS may require it.

workPhone

Object

table "Phone"

See Phone Fields format and description

Cardholder work phone number

Optional. Some ACS may require it.

accountInfo

Object

table "AccountInfo"

See AccountInfo Fields format and description

Information about the Cardholder’s account provided by the 3DS Requestor

Optional

additionalAccountInfo

Object

table "AdditionalInfo"

See AdditionalInfo Fields format and description

Additional information about the Cardholder’s account provided by the 3DS Requestor

Optional

merchantRiskInfo

Object

table "MerchantRiskIndicator"

See MerchantRiskIndicator Fields format and description

Merchant’s assessment of the level of fraud risk for the specific authentication

Optional

acceptHeader

String

max 2048 chars

"image/webp,image/apng,image/,/*;q=0.8"

Exact content of the HTTP accepts headers as sent to the 3DS Requestor from the Cardholder’s

Required

ip

String

max 45 chars

"192.168.123.123"
"2001:0db8:85a3:0000:0000:8a2e:0370:7334"

IP address of the cardholder browser.

Optional

javascriptEnabled

Bool

true/false

true

Value is returned from the navigator.javascriptEnabled property

Required

javaEnabled

Bool

true/false

true

Value is returned from the navigator.javaEnabled property

Required

language

String

1-8 chars

"en-GB"

Value is returned from the navigator.language property

Required

colorDepth

String

1-2 chars

"24"

Value is returned from the screen.colorDepth property

Required

screenHeight

String

1-6 chars

"782"

Value is returned from the screen.height property

Required

screenWidth

String

1-6 chars

"1452"

Value is returned from the screen.width property

Required

timeZone

String

1-5 chars

"-420"

Value is returned from the "new Date().getTimezoneOffset()" method

Required

userAgent

String

max 2048 chars

"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N)
AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/83.0.4103.97
Mobile Safari/537.36"

Exact content of the HTTP user-agent header

Required

authenticationData

string

JSON (maximum 20,000 characters)

Data that documents and supports a specific authentication process.
In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.
For example, if the 3DS Requestor Authentication Method is:

• 03, then this element can carry information about the provider of the federated ID and related information.
• 06, then this element can carry the FIDO attestation data (including the signature).
• 07, then this element can carry FIDO Attestation data with the FIDO assurance data signed.
• 08, then this element can carry the SRC assurance data.

Required

authenticationTimestamp

string

YYYYMMDDHHMM (12 characters)

Date and time in UTC of the customer authentication

Required

expiryDate

string

YYMM

Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder

Optional

cardNumber

string

13–19 chars

Account number that will be used in the authorization request for payment transactions.
May be represented by PAN, token

Required

cardholderName

string

2-45 chars

Name of the Cardholder
Alphanumeric special characters(English language and special characters only), listed in EMV Book 4, “Appendix B”.

Optional

date

string

yyyy-MM-dd HH:mm:ss

"2020-06-08 22:11:44"

UTC datetime of purchase

Required

instalData

int

Example values accepted:
• 2
• 02
• 002

Maximum 3 characters

Values accepted:
Value shall be greater than 1

Indicates the maximum number of authorisations permitted for instalment payments.

Optional

• Essential if 3DS Requestor Authentication Indicator = 03. Omitted if not an instalment payment authentication

amount

decimal

decimal value

120.10

amount of purchase

Required

currencyCode

string

3 digit ISO 4217

"THB"

currency code

Required

chAccAgeInd

String

2 digit string

NoAccount = "01",

CreatedDuringThisTransaction = "02",

LessThan30Days = "03",

From30To60Days = "04",

MoreThan60Days = "05"

Length of time that the cardholder has had the account with the 3DS Requestor

Optional

chAccChange

String

"yyyyMMdd"

20201224

Date that the cardholder’s account with the 3DS Requestor was last changed

Optional

chAccChangeInd

String

2 digit string

DuringThisTransaction = "01",

LessThan30Days = "02",

From30To60Days = "03",

MoreThan60Days = "04"

Length of time since the cardholder’s account information with the 3DS Requestor was last changed

Optional

chAccDate

String

"yyyyMMdd"

"20201224"

Date that the cardholder opened the account with the 3DS Requestor

Optional

chAccPwChange

String

"yyyyMMdd"

"20201224"

Date that cardholder’s account with the 3DS Requestor had a password change or account reset

Optional

chAccPwChangeInd

String

2 digit string

NoChange = "01",

ChangedDuringThisTransaction ="02",

LessThan30Days = "03",

From30To60Days = "04",

MoreThan60Days = "05"

Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change

Optional

nbPurchaseAccount

String

max 4 chars

"1234"

Number of purchases with this cardholder account during the previous six months

Optional

provisionAttemptsDay

String

max 3 chars

"123"

Number of Add Card attempts in the last 24 hours

Optional

txnActivityDay

String

max 3 chars

"123"

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours

Optional

txnActivityYear

String

max 3 chars

"123"

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year

Optional

paymentAccAge

String

yyyyMMdd

"20201224"

Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor

Optional

paymentAccInd

String

2 digit string

NoAccount = "01",

CreatedDuringThisTransaction = "02",

LessThan30Days = "03",

From30To60Days = "04",

MoreThan60Days = "05"

Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor

Optional

shipAddressUsage

String

yyyyMMdd

"20201224"

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

Optional

shipAddressUsageInd

String

2 digit string

DuringThisTransaction = "01",

LessThan30Days = "02",

From30To60Days = "03",

MoreThan60Days = "04"

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

Optional

shipNameIndicator

String

2 digit string

AccountNameIdenticalToShippingName = "01",

AccountNameDifferentToShippingName = "02"

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction

Optional

suspiciousAccActivity

String

2 digit string

NoSuspiciousActivityObserved = "01",

SuspiciousActivityHasBeenObserved = "02"

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

Optional

accountType

Number

1 digit

NotApplicable = 1,

Credit = 2,

Debit = 3

Indicates the type of account. For example, for a multi-account card product

Optional

authenticationMethod

int

1 digit

NoAuth = 1,

LoginUsingOwnCredentials = 2,

LoginUsingFederatedId = 3,

LoginUsingIssuerCredentials = 4,

LoginUsingThirdParty = 5,

LoginUsingFido = 6

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

Optional

authenticationTimeStamp

String

yyyyMMddHHmmss

"20200608221144"

Date and time in UTC of the cardholder authentication

Optional

deliveryEmailAddress

String

email

"test@test.com"

For Electronic delivery, the email address to which the merchandise was delivered

Optional

deliveryTimeframe

String

2 digit

ElectronicDelivery = "01",

SameDayShipping = "02",

OvernightShipping = "03",

TwoDayOrMoreShipping = "04"

Indicates the merchandise delivery timeframe

Optional

giftCardAmount

String

max 15 chars

"1234"

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

Optional

giftCardCount

String

2 chars

"12"

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased

Optional

giftCardCurr

String

3 chars

"840"

For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

Optional

preOrderDate

String

"yyyyMMdd"

"20201224"

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

Optional

preOrderPurchaseInd

String

2 digit

MerchandiseAvailable = "01",

FutureAvailability = "02"

Indicates whether Cardholder is placing an order for merchandise with a future availability or release

Optional

reorderItemsInd

String

2 digit

FirstTimeOrdered = "01",

Reordered = "02"

Indicates whether the cardholder is reordering previously purchased merchandise

Optional

shipIndicator

String

2 digit

ToCardholderBillingAddress = "01",

ToAnotherVerifiedAddressOnFileWithMerchant = "02",

ToAddressThatDifferentThanBillingAddress = "03",

ShipToStore = "04",

DigitalGoods = "05",

TravelAndEventTickets = "06",

Other = "07"

Indicates shipping method chosen for the transaction

Optional

challengeHtml

String

HTML

HTML with form, which contains Base64Url encoded initial CReq.

This is optional for 3DS Requestor. 3DS Requestor will use only the hostedChallengeUrl field.

version

String

10 chars

This field contains the 3DS version that was used to process the transaction.
Possible Values:
1.0.2
2.1.0
2.2.0
Note: Required for Mastercard Identity Check transactions in Authorization

Message Protocol version

hostedChallengeUrl

String

Y

The fully qualified URL that the client uses to post the cardholder in order to complete the Consumer Authentication transaction for 2c2p 3dss challenge page API integration.
Note: This is only for a 2c2p challenge page Integration
3DS Requestor called this one as “stepUpUrl”

dsTransId

String

UUID
36 characters

"91147cb8-d836-44e0-a1cc-b8e25040297f",

DS transaction id

acsTransId

String

Y

UUID
36 characters

"f38f4639-b820-4dbb-91af-6643f997bd69",

ACS transaction id

threeDsServerTransId

String

Y

UUID
36 characters

"3dc1a061-ca59-4c87-b104-3d2bd04ed3e5"

3DS Server transaction id

status

String

Y

1 char

Transactions status result identifier.

Possible Values:

Y - Successful Authentication

N - Failed Authentication / Account Not Verified / Transaction Denied

U - Unable to Complete Authentication

A - Successful Attempts Transaction

C** - Challenge Required for Authentication

R** - Authentication Rejected (Merchant must not submit for authorization)

D - Challenge Required; Decoupled Authentication confirmed.

I - Informational Only; 3DS Requestor challenge preference acknowledged.

NOTE:Statuses of C and R only apply to Consumer authentication 2.0. Decoupled authentication is not supported at this time.

Status of the authentication.

If the status is “C”, 3DS Requestor should redirect to the hosted challenge URL.

authenticationValue

String

28 chars

"xgTukdwAAAAAAAAAAAAAAAAAAAA="

Proof of authentication

• Only when the Transactions Status is “A” or “Y”

eci

String

Y

2 chars

“05”

Electronic Commerce Indicator (ECI)

• Not available when the Transaction Status is “C”
  Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.Possible Values:
  02 or 05 - Fully Authenticated Transaction01 or 06 - Attempted Authentication Transaction

00 or 07 - Non 3-D Secure Transaction

Mastercard - 02, 01, 00

VISA - 05, 06, 07

AMEX - 05, 06, 07

JCB - 05, 06, 07

DINERS CLUB - 05, 06, 07

Union Pay International: 05, 06, 07

cardScheme

String

Card brand that the transaction was processed for authentication.
Possible Values:
AMEX
DISCOVER
JCB
MASTERCARD
VISA
UNKNOWN
UPI
ITMX
TPN

cardBin

String

Card bin represents the first six numbers of the CardNumber field passed in on the cmpi_lookup request.

externalReferenceId

String

Y

Unique ID from the merchant level. Merchant Reference Number.

StatusReason

String

Y

Provides additional information as to why the PAResStatus has the specific value.
NOTE: Required for Payment (e.g. Authentication Indicator equals 01 on Lookup Request) transactions when PAResStatus is equal to N, U, or R in the Lookup Response. Please refer to "EMV 3-D Secure Protocol and Core Functions Specification v2.2.0" for a list of Reason Codes.

acsReferenceNumber

String

Y

Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.

acsOperatorId

String

Y

DS assigned ACS identifier.
Each DS can provide a unique ID to each ACS
on an individual basis.

authenticationType

String

2 digit

Indicates the type of authentication that will be used to challenge the card holder.

Possible Values:

01 - Static

02 - Dynamic

03 - OOB (Out of Band)

04 - Decoupled

NOTE: EMV® 3-D Secure version 2.1.0 supports values 01-03. Version 2.2.0 supports values 01-04. Decoupled authentication is not supported at this time.

Optional

status

String

1 char

"U" - authentication failed

Transactions status result identifier.

Possible Values:
N - Failed Authentication / Account Not Verified / Transaction Denied

U - Unable to Complete Authentication

A - Successful Attempts Transaction

C** - Challenge Required for Authentication

R** - Authentication Rejected (Merchant must not submit for authorization)

error

String

255 varchar

"2.0 is not supported for this card"

Error Description

errorCode

String

4 chars

"A002"

Error code

emvErrorCode

String

3 characters

Code indicating the type of problem identified in the message.

Required in Message Error

emvErrorComponent

String

1 character

Code indicating the 3-D Secure component that identified the error.

Required in Message Error

emvErrorDescription

String

2048 characters

Text describing the problem identified in the message.

Required in Message Error

emvErrorDetail

String

2048 characters

Additional detail regarding the problem identified in the message.

Required in Message Error