Request Method :: POST

Description: This API is used to start the 3D Secure (3DS) authentication process for a cardholder before completing a payment transaction. It validates the cardholder’s identity with the issuer’s Access Control Server (ACS) by generating a unique authentication transaction ID and passing transaction details.

Headers

merchantId:123
authcTxnId:100917632329922288
Content-Type: application/json

Request Body Parameters

Parameters Parameter Description Length/Format Data types Mandatory
/Optional
/conditional		 Sample Value
authcTxnId Unique authentication transaction ID. 19 String Mandatory 1302
authentication Contains authentication details. - Object Mandatory -
orderId Unique order ID for transaction. 20 String Mandatory 658756756
deviceChannel Indicates the type of channel interface being used to initiate the transaction. 2 String Mandatory 01 = App-based (APP)
02 = Browser (BRW)
03 = 3DS Requestor Initiated(3RI)
04–79 = Reserved for EMVCofuture use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use
messageCategory Identifies the category of the message for a specific use case. 2 String Mandatory 01 = PA
02 = NPA
03–79 = Reserved for EMVCofuture use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use
merchantId Merchant identifier.e.g.-123 15 String Mandatory -
threeDSRequestorChallengeInd Challenge indicator,
For 01-PA, a 3DS Requestor may have concerns about the transaction, and request a challenge.
For 02-NPA, a challenge may be necessary when adding a new card to a wallet.
NOTE: When providing two preferences, the 3DS Requestor ensures that they are in preference order and are not conflicting. For example, 02 = No challenge requested and 04 = Challenge requested (Mandate).		 2 String Mandatory 01 = No preference
02 = No challenge requested
03 = Challenge requested (3DS Requestor preference)
04 = Challenge requested (Mandate)
05 = No challenge requested (transactional risk analysis is already performed)
06 = No challenge requested (Data share only)
07 = No challenge requested (strong consumer authentication is already performed)
08 = No challenge requested (use Trust List exemption if no challenge required)
09 = Challenge requested (Trust List prompt requested if challenge required)
10 = No challenge requested (use low value exemption)
11 = No challenge requested (Secure corporate payment exemption)
threeDSRequestorDecReqInd Indicates whether the 3DS Requestor requests the ACS to use Decoupled Authentication and agrees to use DecoupledAuthentication if the ACS confirms its use.
NOTE: If the element is not provided, the expected action is for the ACS to interpret as N (Do not use Decoupled Authentication)		 1 String Mandatory Y = Decoupled Authenticationis supported and is preferredas a primary challenge method if a challenge is necessary(Transaction Status = D inARes).
N = Do not use Decoupled Authentication.
F = Decoupled Authentication is supported and is to be used only as a fallback challenge method if a challenge is necessary (Transaction Status= D in RReq).
B = Decoupled Authentication is supported and can be used as a primary or fallback challenge method if a challenge is necessary(Transaction Status = D in either ARes or RReq).
threeDSRequestorDecMaxTime 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) 5 String Mandatory Numeric values between 00001 and 10080. e.g.- 765
purchaseCurrency Currency in which purchase amount is expressed. 3 String Conditional Mandatory for 02-NPA if 3DS Requestor Authentication Indicator= 02, 03,07, 08, 09 Mandatory for 02-NPA if 3RI Indicator =01, 02, 06,07, 08, 09,11, 15. ISO 4217 three-digit currency code. e.g.- AED
purchaseExponent Currency exponent. Minor units of currency as specified in the ISO 4217 currency exponent. 2 String Conditional(Mandatory for 02-NPA if 3DS Requestor Authentication Indicator = 02, 03, 07, 08, 09.(Mandatory for 02-NPA if 3RI Indicator = 01, 02, 06, 07, 08, 09, 11, 15.) USD = 2
JPY = 0
purchaseDate Date and time of the authentication converted into UTC. 14 String Conditional(Mandatory for 02-NPA if 3DS Requestor Authentication Indicator = 02, 03, 07, 08, 09.(Mandatory for 02-NPA if 3RI Indicator = 01, 02, 06, 07, 08, 09, 11, 15.) 01-APP
02-BRW
03-3RI
purchaseAmount 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.		 48 String Conditional(Mandatory for 02-NPA if 3DS Requestor Authentication Indicator = 02, 03, 07, 08, 09.(Mandatory for 02-NPA if 3RI Indicator = 01, 02, 06, 07, 08, 09, 11, 15.) Purchase amount is USD 123.45 Example values accepted:12345
012345
0012345
threeDSRequestorAuthenticationInd Indicates the type of authentication request.
This data element provides additional information to the ACS to determine the best approach for handling an authentication request		 2 String Mandatory 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
08 = Split shipment
09 = Delayed shipment
10 = Split payment
11–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use
threeDSRequestorURL Fully Qualified URL of3DS Requestor Websiteor customer care site.This data element provides additional information to the receiving 3-D Secure system if a problem arises and should provide contact information. 2048 String Mandatory URL
recurringInd Indicates whether the recurring or installment payment has a fixed or variable amount and frequency.The Recurring Indicator object contains:
the Amount Indicator
the Frequency Indicator.		 2 String Conditional 01 = Fixed Purchase Amount
02 = Variable Purchase Amount
03–79 = Reserved for EMVCofuture use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use Frequency Indicator.
recurringIndfrequency Indicates whether the recurring or instalment payment has a fixed or variable frequency 2 String Mandatory 01 = Fixed Frequency
02 = Variable or Unknown Frequency
03–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use.
e.g.{"recurringInd":{"frequencyInd":"02"}}
recurringFrequency Indicates the minimum number of days between authorisations for a recurring or instalment transaction. e.g.- e 4 String Mandatory(if Recurring Indicator/FrequencyIndicator = 01.) Numeric values between 1 and 9999/td>
sourceOfFunds Source of Funds. - Object Mandatory -
cardnumber Card number (PAN) 19 String Mandatory 765430270000463
expiry Card expiry. - Object Mandatory -
month Card expiry month (MM) 2 String Mandatory -
year Card expiry year (YY) 4 String Mandatory -
securityCode Three- or four-digit security code printed on the card (CVV/CVC). 4 String Mandatory 123
coftConsent Card-on-file consent(false/true) - Boolean Optional -
type Source type (e.g., card) 10 String Mandatory -
cardholderName Name of Cardholder. 45 String Mandatory Santosh
billAddressDetails Bill Address Details - Object Mandatory -
billAddrLine1 First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. 50 String Mandatory Infocity
billAddrLine2 Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. 50 String Optional Bill address line 2
billAddrLine3 Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. 50 String Optional Bill address line 3
billAddrCity The city of the Cardholder billing address associated with the card used for this purchase 50 String Mandatory Bhubaneswar
billAddrState The state or province of the Cardholder billing address associated with the card used for this purchase 50 String Mandatory Odisha
billAddrPostCode Billing Address Postal Code 16 String Mandatory 751024
billAddrCountry The country of the Cardholder billing address associated with the card used for this purchase. (ISO 3166-1 numeric three-digit country code) 3 String Mandatory 840
shipAddressDetails Shipping Address Details - Object Mandatory -
shipAddrLine1 First line of the street address or equivalent local portion of the shipping address requested by the Cardholder. 100 String Optional Shipping Address line1
shipAddrLine2 Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder. 100 String Optional Ship address line 2
shipAddrLine3 Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder. 100 String Optional Ship address line 3
shipAddrCity The city of the Shipping address associated with the card used for this purchase 50 String Mandatory Shipping City
shipAddrState The state of the Shipping address associated with the card used for this purchase 50 String Mandatory Shipping State
shipAddrPostCode Shipping Address Postal Code 16 String Mandatory 751024
shipAddrCountry Shipping Country 3 String Mandatory -
phone Phone Details - String Mandatory -
workPhone The work phone number provided by the card holder. e.g.- 909090090 15 String Mandatory Country Code and Subscriber sections of the number represented by the following named fields:- cc- subscriber Refer to ITU-E.164 for additional information on format and length.
Example: "workPhone":{ "cc":"1", "subscriber":"1234567 899" }
mobilePhone The mobile phone number provided by the card holder. 15 String Mandatory Country Code and Subscriber sections of the number represented by the following named fields:- cc- subscriber Refer to ITU-E.164 for additional information on format and length.
Example: "workPhone":{ "cc":"1", "subscriber":"1234567 899" }
mobilePhone The mobile phone number provided by the card holder. 15 String Mandatory Country Code and Subscriber sections of the number represented by the following named fields:- cc- subscriber Refer to ITU-E.164 for additional information on format and length.
Example: "workPhone":{ "cc":"1", "subscriber":"1234567 899" }
homePhone The home phone number provided by the card holder. 15 String Mandatory Country Code and Subscriber sections of the number represented by the following named fields:- cc- subscriber Refer to ITU-E.164 for additional information on format and length.
Example: "workPhone":{ "cc":"1", "subscriber":"1234567 899" }
acctInfo Account Information. - Object Mandatory -
chAccAgeInd Card holder account age indicator. Length of time that the Cardholder has had the account with the 3DS Requestor. Account age indicator. 2 String Optional • 01 = No account (guest checkout)
• 02 = Created during this transaction
• 03 = Less than 30 days
• 04 = 30–60 days •>
chAccChange Card holder account change date. Date converted into UTC that the Cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. 8 String Optional Date format = YYYYMMDD
chAccChangeInd Card holder account change indicator. 2 String Optional 01 = Changed during this transaction
02 = Less than 30 days
03 = 30–60 days
04 = More than 60 days
chAccDate Date converted into UTC that the Cardholder opened the account with the 3DS Requestor. (YYYYMMDD). 8 String Optional e.g.- 20170101
chAccPwChange Password change date Date converted into UTC that Card holder’s account with the 3DS Requestor had a password change or account reset. (YYYYMMDD). 8 String Optional e.g.- 20170101
nbPurchaseAccount Cardholder Account purchase Count Number of purchases with this Cardholder account during the previous six months. If the Cardholder Account Purchase Count reaches the value 999, it remains set at 999. 4 String Optional 0-999
txnActivityDay Number of transactions (successful and abandoned) for this Cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. 5 String Optional 2,02,002
txnActivityYear No. of transaction per year. Number of transactions (successful and abandoned) for this Cardholder account with the 3DS Requestor across all payment accounts in the previous year. If the maximum value is reached, the Number of Transactions Per Year remains set at 999. 5 String Optional 0-999
paymentAccAge Dateconverted into UTC that the payment accountwas enrolled in theCardholder’s account with the3DS Requestor. e.g.- 20170101 8 String Optional YYYYMMDD
paymentAccInd Indicates the length of time that the paymentaccount was enrolled in theCardholder’s accountwith the 3DS Requestor. 2 String Optional Valuesaccepted:01= No account (guest checkout)
02= During this transaction
03= Less than 30 days
04= 30–60 days
05= More than 60 days
shipAddressUsage Ship address usage. Date converted into UTC when the shipping address used for this transaction was first used with the 3DS Requestor. 20 String Optional YYYYMMDD
shipAddressUsageInd Shipping address usage indicator. Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 5 String Optional 01 = This transaction
02 = Less than 30 days
03 = 30–60 days
04 = More than 60 days
shipNameIndicator shipping name indicator. Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 10 String Optional 01 = Account Name identical to shipping Name
02 = Account Name different than shipping Name
suspiciousAccActivity Suspicious account activity. Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the Cardholder account. 2 String Optional 01 = No suspicious activity has been observed.
02 = Suspicious activity has been observed.
merchantRiskIndicator Merchant Risk Indicator - Object Mandatory -
shipIndicator Indicates shipping method chosen for the transaction.Merchants must choose the Shipping Indicator code that most accuratelydescribes theCardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the ShippingIndicator code for the physical goods, or if all digital goods,use the Shipping Indicator code that describes the mostexpensive item. e.g.- 01 2 String Mandatory 01 = Ship to the Cardholder’s billing address
02 = Ship to another verified address on file with the Merchant
03 = Ship to an address i.e. different than the Cardholder’s billing address
04 = “Ship to Store” / Pick-up ata localstore (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, e media subscriptions,etc.)
08 =Pick-upandgo delivery
09 = Locker delivery (or other automatedpick up)
deliveryTimeframe Indicates the merchandise delivery timeframe. e.g.- 02 2 String Mandatory •01= Electronicdelivery
•02= Same-day shipping
•03= Overnight shipping
•04= Two-dayor more shipping
deliveryEmailAddress For electronic delivery, the email address to which the merchandise was delivered. 254 String Mandatory [email protected]
preOrderPurchaseInd Indicates whether the Cardholder is placing an order for merchandise with a future availability or release date. 2 String Mandatory •01= Merchandise available
•02= Future availability
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available. 8 String Mandatory YYYYMMDD
giftCardAmount For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD123.45 is 123). 15 String Mandatory 123
giftCardCurr For prepaid or gift card purchase, ISO 4217 3 -digit currency code of the gift card. 3 String Mandatory 840
giftCardCount For prepaid or gift card purchase, total count of individualprepaid or gift cards/codes purchased. 2 String Mandatory 01
sdkData SDK Data - Object Conditional -
sdkAppID 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.
NOTE: In case of Split SDK/Browser, the SDK App ID value is not reliable, and may change for each transaction.		 36 String Conditional Canonical format as defined in IETF RFC 4122. This may use any of the specified versions as long as the output meets specified requirements.
sdkEncData JWE Object (represented as a string) containing data encrypted by the 3DS SDK for the DS to decrypt. 6400 String Conditional eyJhbGciOiJ-----9gVWMnxc7kQ
sdkEphemPubKey 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. 256 Object Conditional -
kty Key Type 20 String Conditional iug8uf3g4r324
crv Curve Type 20 String Conditional yt873842r234
x Public key X coordinate. 256 String Conditional h34r983
y Public key Y coordinate. 256 String Conditional 32t23t
sdkReferenceNumber Identifies the vendor and version of the 3DS SDK that is used for a specific transaction. The value is assigned by EMVCo when the LOA of the specific 3DS SDK is issued. 32 String Conditional 3DS_LOA_SDK_UTSB_020100_00011
sdkTransID Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. 36 String Conditional Canonical format as defined in IETF RFC 4122. This may use any of the specified versions if the output meets specified requirements.
sdkMaxTimeout Indicates the maximum amount of time (in minutes) for all exchanges. 2 String Conditional value accept greater than or = 05.
sdkType Indicates the type of 3DS SDK. This data element provides additional information to the DS and ACS to determine the best approach for handling the transaction. 2 String Conditional 01 = Default-SDK
02 = Split-SDK
03–79 = Reserved for EMVCofuture use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use
deviceRenderOptions Device Render Options - Object Conditional -
sdkInterface SDK interface type. e.g.- 03 2 String Conditional 01 = Native
02 = HTML
03 = Both
sdkAuthenticationType Supported authentication methods. 12 Array Conditional 01 = Static Passcode
02 = SMS OTP
03 = Key fob or EMV card reader OTP
04 = App OTP
05 = OTP Other
06 = KBA
07 = OOB Biometrics
08 = OOB Login
09 = OOB Other
10 = Other
11 = Push Confirmation
12–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
80–99 = Reserved for DS use
sdkUiType sdkType 7 Array Conditional Supported UI types
browserDetails Browser details - Object Conditional -
browserJavascriptEnabled JS enabled flag. Boolean that represents the ability of the Cardholder Browser to execute JavaScript. - Boolean Conditional true/false
browserAcceptHeader Browser accept header. Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder Browser. 256 String Conditional If the total length of the accept header sent by the Browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
browserUserAgent Browser user-agent. Exact content of the HTTP user-agent header.
NOTE: If the total length of the User-Agent sent by the Browser exceeds 2048 characters, the 3DS Server truncates the excess portion.		 512 String Conditional e.g.- Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
threeDSCompInd Indicates whether the 3DS Method successfully completed. 1 String Conditional Y = Successfully completed
N = Did not run or did not successfully complete
U = Unavailable – 3DS Method URL was not present
in the PRes message data for the card range associated with the Cardholder Account Number.
browserJavaEnabled Java enabled flag. Boolean that represents the ability of the Cardholder Browser to execute Java. Value is returned from the navigator.javaEnabled property - Boolean Conditional false/true
browserColorDepth Color depth (bits). Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from the Cardholder Browser using the screen. colorDepth property. 2 String Conditional 32
browserScreenHeight Screen height. Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. 5 String Conditional 1920
browserScreenWidth Screen width. Total width of the Cardholder’s screen in pixels.Value is returned from the screen.width property. 5 Numeric Conditional 1080
browserTZ Time zone offset in minutes between UTC and the Cardholder Browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. e.g.- 0 14 Numeric Conditional Value is returned from the get Timezone Offset() method. Example time zone offset values in minutes: If UTC -5 hours: • 300 • +300 If UTC +5 hours: • -300
browserLanguage Browser language code. 35 String Conditional Browser language as defined in IETF BCP47. e.g.- ‘en’
riDetails 3DS Requestor-Initiated transactions - Object Conditional -
threeRIInd Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handling a 3RI request 2 String Conditional 01 = Recurring transaction 02 = Instalment transaction 03 = Add card 04 = Maintain card information 05 = Account verification 06 = Split shipment 07 = Top-up 08 = Mail Order 09 = Telephone Order 10 = Trust List status check 11 = Other payment 12 = Billing Agreement 13 = Device Binding status check
recurringInd Indicates whether the recurring or instalment payment has a fixed or variable amount and frequency. The Recurring Indicator object contains:the Amount Indicator, the Frequency Indicator 3 String Conditional 01 = Fixed Purchase Amount 02 = Variable Purchase Amount 03–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use Frequency Indicator Field Name: frequencyInd Values accepted: 01 = Fixed Frequency 02 = Variable or Unknown Frequency 03–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use
frequencyInd Frequency indicator. 10 String Conditional 01 = Fixed Frequency 02 = Variable or Unknown Frequency03–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use
recurringFrequency Recurring frequency. Indicates the minimum number of days between authorisations for a recurring or installmentet. 4 String Conditional Numeric values between 1 and 9999
NOTE:
 

SDK Authentication Type

The "sdkAuthenticationType": ["01","02","03","04","05","06","07","08","09","10","11","12"] field refers to the supported authentication methods during payer authentication initiation.

Code Description
01 Text Authentication (Password / Passphrase)
02 Single Select
03 Multi Select
04 Out-of-Band (OOB)
05 OOB with Biometrics
06 OOB with PIN
07 OOB with Password
08 OOB with Other Method
09 Decoupled Authentication
10 Biometrics in-App
11 PIN in-App
12 Password in-App
Reserved Values:
• 03–79 = Reserved for EMVCo future use
• 80–99 = Reserved for DS use

SDK UI Type

The "sdkUiType": ["01","02","03","04","05","06","07"] field defines the challenge screen types that the SDK can render during authentication.

Code Description
01 Text Challenge
02 Single Select
03 Multi Select
04 Out-of-Band (OOB)
05 OOB with Biometrics
06 OOB with PIN
07 OOB with Password
08 OOB with Other Method
09 Decoupled Authentication
10 HTML Other
11 App-Based Biometrics
12 App-Based Other
👉 Important:
These codes allow the ACS (Access Control Server) to determine which challenge screens and authentication methods are supported by the SDK, ensuring that the most appropriate user experience is presented to the cardholder during the 3D Secure authentication flow.

Sample Request Body

```

📘 Important Notes

authcTxnId

A unique identifier for the payment authentication. It must be generated by the PayerMax Team for each individual request.

orderId

A unique identifier for the order. This should be included in every request by the PayerMax Team.

threeDSRequestorURL

A fully qualified URL of the system designated to receive the CRes or error messages. The CRes message is sent by the ACS via the cardholder's browser upon completion of the challenge and after the RRes message is received.

```

Response Body Parameters

Parameters Description Data Type
authcTxnId 3DS transaction ID. String
success Following data is fetched successfully object
messageVersion Version of the 3DS message being used. String
messageType Type of the message being returned. String
eci Electronic Commerce indicator. (identifies the authentication result for the transaction.) String
threeDSServerTransID Unique identifier for the transaction assigned by the 3DS Server. String
dsTransID Unique identifier assigned by the Directory Server(DS). String
acsTransID Unique identifier assigned by the Access Control Server (ACS). String
dsReferenceNumber Directory Server reference number for system identification. String
acsReferenceNumber Access Control Server reference number for system identification. String
transStatus Transaction status: indicates the result of authentication ((e.g. C = Challenge Required, Y= Authenticated). String
cardSecurityCodeStatus Result of CVV/CVC check (M = Match, N = No Match). String
cardSecurityCodeStatusSource Source of CVV/CVC validation (e.g., Merchant). String
acsOperatorID Access Control Server Operator ID String
deviceInfoRecognisedVersion Device Information Recognized Version. String
acsURL Access Control Server URL String
authenticationValue Cryptographic proof of authentication, generated by the ACS. String
threeDSRequestorAppURLInd Indicates if 3DS Requestor App URL is present (Y = Yes). String
acsChallengeMandated Indicates if ACS mandates a challenge (Y = Yes, N = No). String
base64EncodedCReq Challenge Request (CReq) message encoded in Base64. Contains ACS challenge data. String
acsRenderingType Access Control Server Rendering Type Object
acsInterface ACS interface type for rendering (e.g., 01 = Native, 02 = HTML, etc.). String
acsUiTemplate Identifies the UI Template format that the ACS first presents to theCardholder. (e.g., 01 = Text, 02 = Single Select). String

Sample Response Body