Authenticate (Enquiry)

This API is used to get authentication result in case challenge.

Note:
• Please refer to the step number 27 in the above diagram.

Request

Field name	Type	Description
threeDsServerTransId	String	Generated by 3DS provider. This value is in lookup response and callback.
externalReferenceId	String	Unique authentication Id which is generated by 3DS Requestor. Conditional only if available

Response

Sample API URL (UAT):

POST Method: https://demo-emv3dss.2c2p.com/enquiry/

1) Enquiry Request Fields format and description

Header

Field Name	Data Type	Example	Description	Requirement
Authorization	String		Bearer xxxx	Required
Content-Type	String		application/json	Required

Body

Field Name	Data Type	Example	Description	Requirement
externalReferenceId	String		Unique authentication Id which is generated by 3DS Requestor
threeDsServerTransId	String 36 characters	"8a880dc0-d2d2-4067-bcb1-b08d1690b26e"	3DS Server transaction ID or transactionID Generated by 3DS provider. This value is in lookup response and callback.	If both parameter passed, we take threeDsServerTransId as a higher priority.

Full Request example:

Request Header:

POST /enquiry
Content-Type: application/json
Authorization: Bearer xxx

Request Body:

{
  "threeDsServerTransId": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e"
}

Or 

{
  "externalReferenceId": "795baa56-204d-42bd-a9c8-4cf0b7a567bd”
}

2) Enquiry Response Filed format and description

Field Name	Data Type	Example	Description	Requirement
threeDsServerTransId	String 36 characters	"8a880dc0-d2d2- 4067-bcb1-b08d1690b26e"	Unique transaction identifier assigned by the 3DS Server to identify a single transaction.	Required
dsTransId	String 36 characters	"8a890900- d2d2-4067-bcb1- b08d1690b26e"	Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. NOTE: Required for Mastercard Identity Check transaction in Authorization	Required
acsTransactionId			Unique transaction identifier assigned by the ACS to identify a single transaction.	Required
authenticationValue	String 28 characters	"xgSUOhRfAAA AAAAAAAAAAA AAAAAA"	CAVV	Required
transactionStatus	String 1 character	“Y”	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) Statuses of C and R only apply to Consumer authentication 2.0. Decoupled authentication is not supported at this time. 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.	Required
eci	String 2 characters	"05"	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 Transaction 01 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 Mastercard - 02, 01, 00 Union Pay International: 05, 06, 07	Required
version	String		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	Required
cardScheme	String		Card brand that the transaction was processed for authentication. Possible Values: AMEX DISCOVER JCB MASTERCARD VISA UNKNOWN UPI ITMX TPN	Required
cardBin	String 11		Card bin represents the first six to eleven numbers of the CardNumber field passed in on the authentication request.	Required
dsTransactionId	String		Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. NOTE: Required for Mastercard Identity Check transaction in Authorization	Required
threeDSServerTransactionId	String		Unique transaction identifier assigned by the 3DS Server to identify a single transaction.	Required
challengeCancel	String		An indicator as to why the transaction was canceled. Possible Values: 01 - Cardholder selected 'Cancel' 02 - Reserved for future EMVCo use (values invalid until defined by EMVCo). 03 - Transaction Timed Out—Decoupled Authentication 04 - Transaction timed out at ACS—other timeouts 05 - Transaction Timed out at ACS - First CReq not received by ACS 06 - Transaction Error 07 - Unknown 08 = Transaction Timed Out at SDK NOTE: Only present when the Consumer cancels the challenge. Decoupled authentication is not supported at this time.	Conditional
statusReason	String		Provides additional information as to why the PAResStatus has a 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.	Required
whiteListStatus	String		Enables the communication of trusted beneficiary/trustlist status between the ACS, the DS and the 3DS Requestor. Possible Values: Y - 3DS Requestor is trustlisted by cardholder N - 3DS Requestor is not trustlisted by cardholder E - Not eligible as determined by issuer P - Pending confirmation by cardholder R - Cardholder rejected U - Trustlist status unknown, unavailable, or does not apply	Optional
whiteListStatusSource	String		This data element will be populated by the system setting WhitelistStatus. Possible Values: 01 - 3DS Server 02 - DS 03 - ACS	Required if WhitelistStatus is present.
authenticationType	String		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.	Conditional

Enquiry Response

Success Response example:

{
"dsTransId": "9999999-bcb1-b08d1690b26e",
"threeDsServerTransId": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
"authenticationValue": "xgSUOhRfAAAAAAAAAAAAAAAAAAAA",
"eci": "05",
"transactionStatus": "Y",
"cardScheme" : " ",
"cardBin" : " ",
"externalReferenceId" : " ",
"reasonCode" : " ",
"reasonDesc" : " ",
"statusReason" : " ",
"acsReferenceNumber" : " ",
"acsOperatorId" : " ",
"whiteListStatusSource" : " ",
"whiteListStatus" : " ",
"acsTransactionId" : " ", 
"version" : " ", 
"challengeCancel" : " ",
"authenticationType " : " "
}

Error Response

Field Name	Data Type	Format	Example	Description
status	String	1 char	"U" - authentication failed	status of authentication
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

Error Response example:

{
  "status": "string",
  "error": "string",
  "errorCode": "string",
  "emvError": {
         "emvErrorCode": "string",
         "emvErrorComponent": "string",
         "emvErrorDescription": "string",
         "emvErrorDetail": "string"
  }
}