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/initialization

HTTP Method:- POST

Request Body in Json

 {
    "netvalveMidId":{{netvalveMidId}},
    "amount": 43.10,
    "currency": "USD",
    "cardExpireMonth": "08",
    "cardExpireYear": "2025",
    "cardHolderName": "Yogesh",
    "cardNumber": "4100000000000100",
    "merchantRedirectUrl" : "https://testmerchant.com/redirect"
}

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

HTTP Response Codes

200 Sucess

401 Unauthorised

404 Bad request

500 Service Unavailable

API Response in JSON

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"
    },
    "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": "INITIALIZATION_FAILED"
    },
    "midId": 2,
    "netvalveMidId": "289e253d-f955-4e29-a2c7-bb1805883ee0"
}

Success Criteria:- {{paymentApiUrl}}/3ds/initialization 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

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`
`redirectUrl`	`String`	Yes	`Netvalve url to do Iframe/redirect for device collection flow. for more details see the documentation` 2: Create Device Data Collection Iframe and POST event listener
`status`	`String`	Yes	`"INITIALIZED"` / “`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.");