Step 3: 3DS Auth API

Owned by Yogesh Dahe
Last updated: Nov 08, 2024
4 min read

The Authentication API must be called after a successful 3D Secure v2 initialization flow.

API Details

Mode:- Stateless REST API

API URL: - {{paymentApiUrl}}/3ds/authentication

HTTP Method:- POST

Request Body in Json

{ "netvalveMidId":{{netvalveMidId}}, "amount":43.10, "currency": "USD", "cardExpireMonth": "08", "cardExpireYear": "2025", "cardHolderName": "Test", "cardNumber": "4100000000000100", "customerEmail": "test@test.com", "customerIp": "123.123.123.123", "customerName": "Test", "customerLastName": "Test", "customerAddress": "Test Address", "customerCity": "Dubai", "customerCountryCode": "VA", "customerPhone": "+919900000000, "customerState": "VA", "customerZipCode": "85284", "transID":"732b4368-d69a-4d74-885e-35b5d402824e" }

Note :- As a new 3DS Visa mandate, the customer needs to send an email and phone in the below format to avoid 3DS compliance issues.

"customerEmail": "yogesh@dahe.com", "customerPhone": "+919900000000", (Customer Phone in the format of coutrycode-phone . e.g +919900000000)

Request table

Parameter

Type

Required

Description

Parameter

Type

Required

Description

netvalveMidId

String

Yes

Netvalve Mid Id configured with merchant profile.

e.g. aa09538b-2148-4e0b-8418-28391caa6af2

amount

BigDecimal

Yes

Transaction Amount

e.g. 100.50

currency

String

Yes

Currency with matching ISO-4217 currency standard e.g. "USD"

cardExpireMonth

String

Yes

regexp = "^(0[1-9]|1[0-2])$"

e.g. "08"

cardExpireYear

String

Yes

@Size(max = 4, min = 4)

e.g. "2025"

cardHolderName

String

Yes

@Size(max = 128)

cardNumber

String

Yes

Valid card number

customerEmail

String

Conditional. Required for Visa 3DS.

Customer email

customerIp

String

Optional

Customer IP Address

customerName

String

Yes

Customer First Name

customerLastName

String

Yes

Customer Last Name

customerAddress

String

Optional

Customer Address

customerCity

String

Optional

Customer City

customerCountryCode

String

Yes

Customer Country Code

Format:- US , 2 digits code

customerPhone

String

Conditional. Required for Visa 3DS.

Customer Phone in the formate of coutrycode-phone . e.g +919900000000

customerState

String

Optional

Customer State

customerZipCode

String

Optional

Customer Zip/Postal Code

transID

String

Yes

transID Id :- Unique 3DS Transaction id from init call . refer ThreeDSProviderResponse table

 

HTTP Response Codes

200 Sucess

401 Unauthorised

404 Bad request

500 Service Unavailable

API Response in JSON

  • Friction Less Flow (Challenge Not Required)

200 { "traceID": "eb603c99-cdd3-4cb4-801e-94e8c46e2059", "responseTimestamp": "2023-09-26T16:02:25.587+00:00", "responseCode": "3DS_1000", "responseMessage": "Three DS Transaction Successful.", "threeDSProviderResponse": { "transID": "e0cc7f76-2d85-4f2d-a284-96df7f59d5bb", "threeDs2TransactionId": "nDgrHKNMWMJbj3pSn710", "eci": "05", "cavv": "Y2FyZGluYWxjb21tZXJjZWF1dGg=", "challengeRequired": false, "threeDsVersion": "2.1.0" }, "midId": 2, "netvalveMidId": "289e253d-f955-4e29-a2c7-bb1805883ee0" } Error { "traceID": "8f2348b0-12f2-44c5-91f9-989124c74220", "responseTimestamp": "2023-11-01T11:43:50.647+00:00", "responseCode": "3DS_2003", "responseMessage": "Invalid Merchant ID. Kindly contact Netvalve support." } { "traceID": "d14726d6-8a00-4555-b2e0-f6fea3b944c5", "responseTimestamp": "2023-11-01T14:19:54.461+00:00", "responseCode": "3DS_2000", "responseMessage": "Three DS Transaction Processing Error. ", "threeDSProviderResponse": { "referenceId": "0fb6d85d-0a4e-4e1f-b6d8-5d0a4ece1fe7", "errorCode": "9400", "errorMessage": "Field 'mid_q' validation error: 'must not be empty' rejected value ''; Field 'mid_q' validation error: 'must not be blank' rejected value ''; Field 'mid_q' validation error: 'size must be between 1 and 8' rejected value ''; ", "challengeRequired": false, "status": "AUTHENTICATED_FAILED" } }

 

  • ACS/Challenge Flow (Challenge Required)

     

  • Frictionless Success Criteria:- {{paymentApiUrl}}/3ds/authentication response must have the below data and the client should add those checks

    • "responseCode" = "3DS_1000"

    • "transID" = (Non Null value)

    • threeDs2TransactionId = (Non Null value)

    • "eci" = (Non Null value)

    • "cavv" = (Non Null value)

    • threeDsVersion = (Non Null value)

  • ACS Success Criteria:- {{paymentApiUrl}}/3ds/authentication response must have the below data and the client should add those checks

    • "responseCode" = "3DS_1000"

    • "transID" = (Non Null value)

    • challengeRequired = true

    • "redirectUrl" = (Non Null value)

    • "status" = ACS_REQUIRED

Response table

Parameter

Type

Required

Description

Parameter

Type

Required

Description

traceID

String

Yes

Trace Id / Corellation ID :- Unique id for 3DS Transaction to trace back / enquiry.

e.g. dbea8561-4990-4582-b370-66ab2696f39a

responseTimestamp

Date

Yes

Date time of response.

e.g. "2023-10-17T08:52:17.845+00:00"

responseCode

String

Yes

Netvalve Response Code

e.g. 3DS_1000 SUCESS

3DS_2000 Failure

More Error Codes

responseMessage

String

Yes

e.g. "Three DS Transaction Successful."

threeDSProviderResponse

String

Optional (present in case of valid request)

TthreeDSProviderResponse JSON Object , refer ThreeDSProviderResponse table

midId

Long

Yes

MID ID

netvalveMidId

String

Yes

NetvalveMidId

 

ThreeDSProviderResponse table

 

Parameter

Type

Required

Description

Parameter

Type

Required

Description

transID

String

Yes

transID Id :- Unique 3DS Transaction id

e.g. dbea8561-4990-4582-b370-66ab2696f39a

referenceId

String

Yes

Reference Id for 3DS from provider

e.g. "124cf1a9-b211-4f7f-8cf1-a9b2115f7fb0"

threeDs2TransactionId

String

Yes

3DS Server Transaction Id

e.g. 6bb67882-1562-42c0-ae06-26875c6a62e3

eci

String

Yes

ECI value from 3DS Provider

e.g.

  • Visa. 05

  • Mastercard. 02

More details ECI Codes

cavv

String

Yes

CAVV value from 3DS Provider

e.g.AJkBAZd0ByiAAAAAJnQHAAAAAAA=

challengeRequired

boolen

Optional

true/false

redirectUrl

String

Optional

Netvalve url to do Iframe/redirect challenge flow . for more details see the documentation Step 4: ACS challenge and receive challenge result

status

String

Yes

"AUTHENTICATED" / “AUTHENTICATED_FAILED“ / “ACS_REQUIRED"

errorCode

String

Optional

e.g. 9400

errorMessage

String

Optional

e.g. “Field 'mid_q' validation error."

 

 

Error Codes