V2 Step 1: 3DS Initialisation Api

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",

Request table

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 formate of coutrycode-phone . e.g `+919900000000`
`customerEmail`	`String`	Conditional. Required for Visa 3DS.	Customer email
`userAgent`	`String`	Yes	`userAgent`param from browser data captured
`browserHeader`	`String`	Yes	`browserHeader` param from browser data captured
`browserJavaEnabled`	`String`	Yes	`browserJavaEnabled`param from browser data captured
`browserLanguage`	`String`	Yes	`browserLanguage`param from browser data captured Format :- `"en-US"`
`browserColorDepth`	`Integer`	Yes	`browserColorDepth`param from browser data captured
`browserScreenHeight`	`Integer`	Yes	`browserScreenHeight`param from browser data captured
`browserScreenWidth`	`Integer`	Yes	`browserScreenWidth`param from browser data captured
`browserTimeZone`	`Integer`	Yes	`browserTimeZone`param 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

API Response in JSON

1:- Initialization 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

200
{
    "traceID": "dbea8561-4990-4582-b370-66ab2696f39a",
    "responseTimestamp": "2023-10-17T08:52:17.845+00:00",
    "responseCode": "3DS_1000",
    "responseMessage": "Three DS Transaction Successful.",
    "threeDSProviderResponse": {
        "transID": "146f7ded-2ea9-41c1-a56a-2d182322aab7",
        "referenceId": "124cf1a9-b211-4f7f-8cf1-a9b2115f7fb0",
        "threeDs2TransactionId": "6bb67882-1562-42c0-ae06-26875c6a62e3",
        "redirectUrl": "https://gateway.sandbox-netvalve.com/threeds/ddc?transId=146f7ded-2ea9-41c1-a56a-2d182322aab7&t=eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJlOWE3OWM4My04ZTc3LTQ4MzctYjkzOS1hOTk2ODU4OWExMTMiLCJpYXQiOjE2OTc1MzI3MzgsImV4cCI6MTY5NzUzMzMzOCwiaXNzIjoiTkVUVkFMVkUiLCJ0eG5JZCI6IjE0NmY3ZGVkLTJlYTktNDFjMS1hNTZhLTJkMTgyMzIyYWFiNyIsInN0YXR1cyI6IklOSVRJQUxJWkVEIiwicHJvdmlkZXIiOiJSWVZZTCJ9.MAlQjy-aL7lYLrpEVxYtsBFkBdkoMWI7_q_p1QHCJtU",
        "status": "INITIALIZED"
    }
}

2:- Direct Auth

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.

200

{
    "traceID": "c1228eb5-2246-4cf5-ae3d-4c19234e1acb",
    "responseTimestamp": "2024-05-28T08:04:13.503+00:00",
    "responseCode": "3DS_1000",
    "responseMessage": "Three DS Transaction Successful.",
    "threeDSProviderResponse": {
        "transID": "53d002cd-9998-4399-94b7-ad1d9e722ea2",
        "threeDs2TransactionId": "e37b458a-c171-4ad3-adb5-e70d3cb9902b",
        "eci": "05",
        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "threeDsVersion": "2.2.0"
    }
}

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": "INITIALIZATION_FAILED"
    }
}

ACS 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

200

{
    "traceID": "8bd4c342-eb46-435b-b6c5-3532b11abe2a",
    "responseTimestamp": "2024-05-28T07:30:33.020+00:00",
    "responseCode": "3DS_1000",
    "responseMessage": "Three DS Transaction Successful.",
    "threeDSProviderResponse": {
        "transID": "c19d5b5b-0dd6-47f4-98ad-096f319cd8c6",
        "threeDs2TransactionId": "619eeb8c-4020-4dcd-9594-aaa53bd6a5e9",
        "challengeRequired": true,
        "redirectUrl": "https://3dsecuresuite.uat.sandbox-netvalve.com?transId=c19d5b5b-0dd6-47f4-98ad-096f319cd8c6&acsWindowSize=5&t=eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI5YWRkYTQ3ZS1hNDE2LTQ2ZjgtODdhYS04OGU5ODIwNDNiYzgiLCJpYXQiOjE3MTY4ODE0MzgsImV4cCI6MTcxNjg4MjAzOCwiaXNzIjoiTkVUVkFMVkUiLCJ0eG5JZCI6ImMxOWQ1YjViLTBkZDYtNDdmNC05OGFkLTA5NmYzMTljZDhjNiIsInN0YXR1cyI6IkFDU19SRVFVSVJFRCIsInByb3ZpZGVyIjoiQ0FSRElOQUwifQ.AHW72RgzRthk1YDBWqIJy4oNcXebxeYCLEzvJUFrj9I",
        "status": "ACS_REQUIRED",
        "threeDsVersion": "2.0.0"
    }
}

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": "INITIALIZATION_FAILED"
    }
}

Response table

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

ThreeDSProviderResponse table

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

// 1000 series for Approval,
THREE_DS_SUCCESS("3DS_1000", "Three DS Transaction Successful."),
THREE_DS_REQUEST_SUCCESS("3DS_1001", "Request Successful."),

// 2000 series for error
THREE_DS_ERROR("3DS_2000", "Three DS Transaction Processing Error. "),
THREE_DS_REQUIRED_CALL_BACK_URL("3DS_2001", "Event Callback Url Is Missing. This Value Must Be Provided."),
THREE_DS_NOT_CONFIGURED("3DS_2002", "Mid Not configured for 3DS. Kindly contact Netvalve support."),
THREE_DS_INVALID_MERCHANT("3DS_2003", "Invalid Merchant ID. Kindly contact Netvalve support."),
THREE_DS_TRANSACTION_ID_REQUIRED("3DS_2004", "Three DS Transaction Id Is Missing. This Value Must Be Provided."),
THREE_DS_CHALLENGE_INDICATOR_REQUIRED("3DS_2005", "Challenge Indicator Is Missing. This Value Must Be Provided."),
THREE_DS_BROWSER_INFO_REQUIRED("3DS_2006", "Browser Info token Is Missing. This Value Must Be Provided."),
THREE_DS_DF_REF_ID_REQUIRED("3DS_2007", "DF Reference Id Is Missing. This Value Must Be Provided."),
THREE_DS_GATEWAY_ERROR("3DS_2008", "Three DS Transaction Processing Error from Gateway. Kindly contact Netvalve support."),
THREE_DS_IMPL_TYPE_REQUIRED("3DS_2009", "3DS implementation type Is Missing. This Value Must Be Provided.");