V2 Initialisation Api

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

The initialization call must be sent to start the 3D Secure v2 authentication flow. Successful initialization

responses will return the 3DS Initialisation details in response

API Details

Mode:- Stateless REST API

API URL: - {{paymentApiUrl}}/3ds/v2/initialization

HTTP Method:- POST

Request Body in Json

{ "netvalveMidId":{{netvalveMidId}}, "amount": 43.10, "currency": "USD", "cardExpireMonth": "08", "cardExpireYear": "2025", "cardHolderName": "Yogesh", "cardNumber": "4000000000001091", "merchantRedirectUrl": "https://amazon.com/redirect", "customerIp": "123.123.123.123", "customerEmail": "yogesh@dahe.com", "customerPhone": "+919900000000", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36", "browserHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8", "browserJavaEnabled": true, "browserLanguage": "en-US", "browserColorDepth": 24, "browserScreenHeight": 864, "browserScreenWidth": 1536, "browserTimeZone": 300 }

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

merchantRedirectUrl

String

Optional(In case of redirect required)

valid merchant redirect URL

customerIp

String

Yes

IP address

customerPhone

String

Conditional. Required for Visa 3DS.

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

customerEmail

String

Conditional. Required for Visa 3DS.

Customer email

userAgent

String

Yes

userAgentparam from browser data captured

browserHeader

String

Yes

browserHeader param from browser data captured

browserJavaEnabled

String

Yes

browserJavaEnabledparam from browser data captured

browserLanguage

String

Yes

browserLanguageparam from browser data captured

Format :- "en-US"

browserColorDepth

Integer

Yes

browserColorDepthparam from browser data captured

browserScreenHeight

Integer

Yes

browserScreenHeightparam from browser data captured

browserScreenWidth

Integer

Yes

browserScreenWidthparam from browser data captured

browserTimeZone

Integer

Yes

browserTimeZoneparam from browser data captured

Format :- like 300

Generating browser data for the request body

The browser related parameters in the request must be fetched on the client. You can use this JavaScript function to collect this data:

function fetchBrowserData(){ return { userAgent: navigator.userAgent, browserHeader: 'text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8', browserJavaEnabled: navigator?.javaEnabled() || false, browserLanguage: navigator?.language || navigator?.userLanguage, browserColorDepth: screen.colorDepth, browserScreenHeight: screen.height, browserScreenWidth: screen.width, browserTimeZone: new Date().getTimezoneOffset() }; } const browserData = fetchBrowserData(); // include in the Initialization API request

 

Note: The browserHeader can be the hard coded string above. This will be unnecessary in future versions.

 

HTTP Response Codes

200 Sucess

401 Unauthorised

404 Bad request

500 Service Unavailable

 

Responses for different flows.

The following indicates the response for each of the possible 3DS flows. The merchant must check the response to see which flow to take.

 

FLOW A: 3DS Complete

See V2 Flows for a description of this flow.

  • Frictionless Flow

Frictionless Success Criteria:- 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

Note:- If the above success criteria match skip all the next steps and use eci,cavv,threeDs2TransactionId,threeDsVersion in payment.

 

FLOW B: challenge required

See V2 Flows for a description of this flow.

  • ACS Success Criteria:-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

    • Note:- If the above success criteria match then follow the next step as (step 4) and in seq for the next

FLOW C:- Device data collection required

See V2 Flows for a description of this flow.

  • Success Criteria:- Response must have the below data and the client should add those checks

    • "responseCode" = "3DS_1000"

    • "transID" = (Non Null value)

    • "redirectUrl" = (Non Null value)

    • "status" = INITIALIZED

  • Note:- If the above success criteria match then follow the next step as (step 2) and in seq of the next

 

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

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" / “INITIALIZATION_FAILED“

errorCode

String

Optional

e.g. 9400

errorMessage

String

Optional

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

 

 

Error Codes

 

Â