How to - 3-D Secure v2

A guide to implementing 3DS v2. When this function is enabled, every REST API real-time transaction call will run through the 3-D Secure process before it processes the payment.

The real-time transaction API (POST Make a live card transaction) remains the same, except there are now two new fields that it supports which become mandatory for merchants that have 3DS v2 enabled. The new fields are “CallbackUrl” and “BrowserInfo” - see sample below:

{
  "ProcessType": "COMPLETE",
  "Reference": "3DS Test1",
  "Description": "This is an example real-time transaction",
  "Amount": 100,
  "CurrencyCode": "AUD",
  "CardToken": null,
  "Card": {
    "CardNumber": "4111111111111111",
    "CardholderName": "TEST Card",
    "ExpiryYear": 2023,
    "ExpiryMonth": 10,
    "Ccv": "123"
  },
  "Payer": null,
  "CallbackUrl" : "https://www.integrapay.com/3ds",
  "BrowserInfo" : {
        "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.106 Safari/537.36",
        "AcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "Language": "en-US",
        "TimeZone": "0",
        "ColorDepth": 24,
        "ScreenHeight": 768,
        "ScreenWidth": 1024,
        "JavaEnabled": true
  },
  "Audit": {
  "Username": "Example-User",
  "UserIP": "1.2.3.4"
  }
}

When this function is called, we run AReq and one of the following responses will be returned based on what response we get back:

1. If AReq returns Frictionless Successful it will proceed to process the transaction and a result as normal.

{
    "transactionId": "RT869918",
    "reference": "3DS Testing 20",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 150.00,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

2. If AReq returns Frictionless Rejection the transaction will not be submitted to the bank/gateway for processing and a new transaction will be immediately generated with the rejected status and the result will be as follows:

{
    "transactionId": "2648881",
    "reference": "3DS Testing 21",
    "statusCode": "R",
    "subStatusCode": "R20",
    "statusDescription": "DO NOT PROCESS - 3-D Secure rejected the transaction due to suspected fraud",
    "processedAmount": null,
    "cardType": null,
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

3. If AReq returns Challenge Required, we will return a response with a new StatusCode of “V” (no transaction is generated yet). Sample below:

{
    "transactionId": null,
    "reference": "3DS Testing 22",
    "statusCode": "V",
    "subStatusCode": "VCR",
    "statusDescription": "3-D Secure Required - send your customer to the 'RedirectUrl'",
    "processedAmount": null,
    "cardType": null,
    "redirectId": "710aebb4092e4e3cbfe37f5f5f3d6dc2",
    "redirectUrl": "https://sandbox.rest.paymentsapi.io/businesses/8C81D848-1E9D-45B3-8382-0C108FDB9C9C/services/tokenize-card/3dsecure/redirect2/710aebb4092e4e3cbfe37f5f5f3d6dc2",
    "cardAuthorizationReference": null
}

Note the two new fields “redirectUrl” and “redirectId” which are returned only for this status “V” response.

If challenge required was returned, it will be up to the merchant to redirect their customer to the URL we provided in the response. For testing, you can simply copy and paste the “redirectUrl” into your browser to get to the challenge page.

Once you have completed the challenge, you should be redirected to the URL provided in the “CallbackUrl” from the previous API call. To determine the result of the challenge and complete the transaction, you will need to call this API - (3-D Secure Finalize Transaction) by using the “redirectId”.

This function checks the result of the challenge and if it was successful, it will continue to process the transaction with all the information originally provided in the card transaction API call. This function returns the same result model as the real-time transaction function, so can be handled in the same way.

Sample if challenge successful:

{
    "transactionId": "RT869919",
    "reference": "3DS Testing 22",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 150.00,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

Sample if challenge failed

{
    "transactionId": "2648883",
    "reference": "3DS Testing 23",
    "statusCode": "R",
    "subStatusCode": "R20",
    "statusDescription": "NOT AUTHORISED - 3-D Secure challenge was not completed",
    "processedAmount": null,
    "cardType": null,
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}