Page Comparison

A guide to implementing 3DS v2. When this function When 3D Secure v2 is enabled, every each REST API real-time transaction call will can run through the 3-D 3D Secure process before it processes the payment depending on the selected setting. There are 3 settings that are available for you to choose when processing eCommerce transactions.

Info

Please note:

Each payment via HPP will always run through the 3D Secure process no matter the setting.
3D Secure is not available when charging a stored card
3D Secure is not compatible with Wallet Payments (Apple Pay and Google Pay)

Real-time Transaction API call

The real-time transaction API (POST Make a live tokenised card transaction) remains the same, except there are now two new extra fields that it supports which become mandatory for merchants that have 3DS v2 enabled. The new fields are “CallbackUrl” and “BrowserInfo” - see sample below:depending on which 3DS setting you select. There are 3 settings for you to choose from:

Optional
Required
Required (eCommerce)

3DS “Optional” Setting

When “Optional” setting is selected, three new fields are required to support 3DS. The three fields are “CallbackUrl”, “BrowserInfo” and “use3ds”. You can decide per transaction if you want to use 3DS or not by making use of the “use3ds” field.

For example:

If value of “use3ds” = “true” – 3DS actioned
If value of “use3ds” = “false” – no 3DS action
If “use3ds” not in body = no 3DS action
If no extra fields are supplied = no 3DS action

Sample:

POST

Code Block

language	json

{{url}}/businesses/{{business-id}}/transactions/card-payments/token

BODY

Code Block

language	json

{
  "ProcessType": "COMPLETE",
  "Reference": "3DS Testing

Test1

212",
  "Description": "This is an example real-time transaction",
  "Amount": 100.25,
  "

CurrencyCode

CallbackUrl": "

AUD

https://www.payrix.com.au",
  "

CardToken

use3ds":

null

"true",
  "

Card

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

CardNumber

Language": "

4111111111111111

en-GB",
    "

CardholderName

TimeZone": -660,

"TEST Card"

"ColorDepth": 24,
    "ScreenHeight": 1080,
    "

ExpiryYear

ScreenWidth": 1920,

2023

},
  "CardToken": "c698ed0d8ac943188c69d88a439bdce3",
  "

ExpiryMonth

ServiceDate": "2022-03-01T10:00:00+10:00",
  "Payer": {
    "email": "test@test.com",
  },
  "Audit": {
    "Username": "Example-User",
    "

Ccv

UserIP": "

123"

1.2.3.4"
  }
}

If you are missing any required fields, it will return a response like the samples below:

Code Block

language	json

{
    "errorCode": "BadRequest",
    "

Payer

errorMessage":

null

 "Your business requires 3-D Secure Authentication so you must provide a CallbackUrl",
    "errorDetail": "CallbackUrl"
}

Code Block

language	json

{
    "errorCode": "BadRequest",
    "errorMessage": "Your business requires 3-D Secure Authentication so you must provide BrowserInfo data",
    "errorDetail": "BrowserInfo"
}

3DS “Required” Setting

When “Required” setting is selected, 3DS is required for all real-time transactions and the 3DS process is mandatory for all transactions. Two extra fields become mandatory for merchants with this setting.

The new fields are “CallbackUrl” and “BrowserInfo” – see example below:

Info
If these fields are not included, you will receive an error and will not progress.

Sample

POST

Code Block
{{url}}/businesses/{{business-id}}/transactions/card-payments/token

BODY

Code Block

language	json

{
  "ProcessType": "COMPLETE",
  "Reference": "3DS Testing 313",
  "Description": "This is an example real-time transaction",
  "Amount": 100.25,
  "CallbackUrl": "https://www.

integrapay.com/3ds", "BrowserInfo" : { "

payrix.com.au",
  "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-GB",
    "TimeZone": -660,
    "ColorDepth": 24,
    "ScreenHeight": 1080,
    "ScreenWidth": 1920,
  },
  "CardToken": "42ec77f95e8a4107b129e4406d105e44",
  "ServiceDate": "2022-03-01T10:00:00+10:00",
  "Payer": {
    "uniqueReference": "A306026D-0B4B-479F-9716-256152C8D310",
    "groupReference": "A306026D-0B4B-479F-9716-256152C8D310",
    "familyOrBusinessName": "Surname",
    "givenName": "First Name",
    "billingAddress": {
      "Line1": "1 Test St",
      "Line2": "Test Building",
      "Suburb": "Testville",
      "State": "QLD",
      "PostCode": "4001",
      "Country": "AUS"
    },
    "email": "test@test.com",
    "phone": "0733331111",
    "savePayer": "true"
  },
  "Audit": {
    "Username": "Example-User",
    "UserIP": "1.2.3.4"
  }
}

3DS “Required (eCommerce)” Setting

When “Required (eCommerce”) is selected, from the Card Transaction model, three extra fields become mandatory. The three extra fields plus, “CallbackUrl” and “BrowserInfo” are:

“CardAuthorizationType”
“RecurringReference”
“CardStorageType”

If you send CIT_ECOMMERCE as the value for “CardStorageType”, 3DS will be performed.

For Example:

If “CardStorageType” value = CIT_ECOMMERCE – 3DS actioned
If “CardStorageType” value = CIT_MOTO – no 3DS action
If “CardStorageType” value = CIT_MERCHANT_STORED – no 3DS action
If “CardStorageType” value = MIT_MERCHANT_STORED – no 3DS action

Sample

POST

Code Block

language	json

{{url}}/businesses/{{business-id}}/transactions/card-payments/token

BODY

Code Block

language	json

{
  "ProcessType": "COMPLETE",
  "Reference": "3DS Testing 515",
  "Description": "This is an example real-time transaction",
  "Amount": 500.25,
  "callbackURL": "https://www.payrix.com.au",
  "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-GB",
    "TimeZone": -660,
    "ColorDepth": 24,

"Language

"ScreenHeight": 1080,
    "ScreenWidth": 1920,
  },
  "CardAuthorizationType": "INITIAL",
  "RecurringReference": "Test1",
  "CardStorageType": "CIT_ECOMMERCE",
  "CardToken": "93167a9e346c48f098045dbfe4754ebd",
  "ServiceDate": "

en-US",

2022-03-01T10:00:00+10:00",
  "Payer": {
    "uniqueReference": "3DS Testing",
    "groupReference": "3DS Testing",
    "familyOrBusinessName": "Surname",
    "givenName": "First Name",
    "billingAddress": {
      "

TimeZone

Line1": "

0

1 Test St",
      "Line2": "Test

"ColorDepth

Building",
      "Suburb":

24,

"Testville",
      "State": "QLD",
      "

ScreenHeight

PostCode":

768

"4001",
      "Country": "AUS"
    },
    "

ScreenWidth

email":

1024,

"test@test.com",
    "phone": "0733331111",
    "

JavaEnabled

savePayer": "true"
  },
  "Audit": {
    "Username": "Example-User",
    "UserIP": "1.2.3.4"
  }
}

Real-time Transaction API call cont.

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.

Code Block

language	json

{
    "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:

Code Block

language	json

{
    "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 belowwhich looks like this:

Code Block

language	json

{
    "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.

Info
“redirectUrl and “redirectId” is required to process the challenge as described in “3-D Secure Finalise Transaction” API call

Finalise Real-time Transaction API call

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 Finalise 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:

Code Block

language	json

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

If challenge failed, a rejected transaction record is generated and a rejected result is returned.

Code Block

language	json

{
    "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
}

Versions Compared

Old Version 5

New Version Current

Key

Real-time Transaction API call

3DS “Optional” Setting

3DS “Required” Setting

3DS “Required (eCommerce)” Setting

Real-time Transaction API call cont.

Finalise Real-time Transaction API call