Introduction

3D Secure 2 aims to provide merchants with an improved online experience by offering both frictionless and challenge authentication flows, coupled with additional authentication mechanisms.

As there are some issuers that are not ready to support 3DS Secure 2, you should also take into consideration a fallback mechanism to be able to handle a 3D Secure 1 request. Our APIs will help you determine if a card is not ready for 3D Secure 2.

Those who have implemented 3D Secure 1 will remember a redirect (via browser, or within an iFrame) taking place for all authentication requests. 3D Secure 2 modifies this behaviour to authenticate the customer within your application (web or mobile) and provide a more seamless payments experience for the consumer.

You can find test cards here for your sandbox testing of the different 3DS2 scenarios.

3DS 2 Authentication Flows

There are two types of authentication flows (frictionless and challenge) that a 3D Secure 2 authentication may go through.

Frictionless

A frictionless flow is triggered when you have submitted the required request data (customer's fingerprint and any other additional data provided) to the issuer, and the issuer opts to authenticate the customer with this data. In this scenario the transaction is processed without any interaction from the customer.

Challenge

A challenge flow is triggered when the issuer opts to have the customer provide additional identification via two-factor authentication (this may be via an SMS or biometrics).

The 3D Secure 2 authentication flow can be depicted in 7 steps, as seen in the diagram below.

3DS v2 Sequence 900.png

If you have your own MPI provider, you will be completing steps 1 through to 6 via your own MPI and should then use the Authorization Only processCard to complete the transaction.

Step 1 - getAccessToken

The getAccessToken method generates a one time access token that can be used with a 3D Secure 2 authentication request. It is then also used with the processCard method when you submit a transaction for processing.

Parameter Description
method

This field is case sensitive.
Example: getAccessToken

merchantUUID

The value of this parameter is provided to you by Merchant Warrior.
Example: 123456789abcd

apiKey

The value of this parameter is provided to you by Merchant Warrior.
Example: 1a3b5c

transactionAmount

The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00

transactionCurrency

One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD

notifyURL

Asynchronous POST notifications will be sent to this URL.
Example: https://www.example.com/notify.php

urlHash

The urlHash field is a combination of your API Passphrase, Merchant UUID and notifyURL. See Web URL Hash for information on how to construct the hash correctly.
Example: 511999e54b9ad51ce4c28d7f0550ac81
Valid Length: 32 characters

hash

The verification hash is a combination of the MD5 of your API Passphrase, and specific parameters sent in the transaction. See Transaction Type Hash for information on how to construct the hash correctly.
Example: e9ddc296b76b3398934bfc06239073df
Valid length: 32 characters

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=getAccessToken' \
--data-urlencode 'merchantUUID=4fce073f145a7' \
--data-urlencode 'apiKey=ou8xigxw' \
--data-urlencode 'transactionAmount=1.00' \
--data-urlencode 'transactionCurrency=AUD' \
--data-urlencode 'notifyURL=https://yourdomain.com/notify' \
--data-urlencode 'urlHash=fd19f24f1ee2d2fdb6ee5c4e8668f659' \
--data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481'
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'method=getAccessToken' \ --data-urlencode 'merchantUUID=4fce073f145a7' \ --data-urlencode 'apiKey=ou8xigxw' \ --data-urlencode 'transactionAmount=1.00' \ --data-urlencode 'transactionCurrency=AUD' \ --data-urlencode 'notifyURL=https://yourdomain.com/notify' \ --data-urlencode 'urlHash=fd19f24f1ee2d2fdb6ee5c4e8668f659' \ --data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
  <token>51acb2b7b7</token>
</mwResponse>
0 Operation successful 51acb2b7b7
{
    "responseCode": 0,
    "responseMessage": "Operation successful",
    "token": "51acb2b7b7"
}
{ "responseCode": 0, "responseMessage": "Operation successful", "token": "51acb2b7b7" }
Step 2 - checkEnrollment

The checkEnrollment method determines if a card number is enrolled for 3D Secure 2 and provides a mechanism to determine if a fallback to 3D Secure 1 is required.

If your checkEnrollment response contains values for threeDSServerTransID and threeDSCompInd you should proceed to Step 4 with these values.

If your checkEnrollment response has null values for threeDSServerTransID and threeDSCompInd you should proceed to Step 3, as this means the issuer would like to fingerprint your customer.

Parameter Description
method

This field is case sensitive.
Example: checkEnrollment

accessToken

The accessToken obtained in Step 1.
Example: 2783a265a0

transactionCurrency

One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD

transactionAmount

The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00

transactionProduct

A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.

paymentCardNumber

Do not send separators with the card number (e.g. 1234-5678… or 1234 5678).
Example: 5123456789012346 or 4557012345678902
Valid length: Between 13 and 16 digits

paymentCardExpiry

This must be MMYY format. The month must be zero padded if it is less than 10.
Example: 0513
Valid length: 4 digits

paymentCardName

This must contain at the very least a space and no less than two characters. Only alphanumeric characters, hyphens, spaces and full stops are allowed.
Example: Mr. Example Person or MR E PERSON or Example Person
Valid length: Between 3 and 255 characters

notifyURL

Asynchronous POST notifications will be sent to this URL. This parameter can also be hardcoded via the merchant administration interface.
Example: https://yourdomain.com/notify

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=checkEnrollment' \
--data-urlencode 'accessToken=ab3c896eaa' \
--data-urlencode 'transactionCurrency=AUD' \
--data-urlencode 'transactionAmount=1.00' \
--data-urlencode 'transactionProduct=Test Product' \
--data-urlencode 'paymentCardNumber=5123456789012346' \
--data-urlencode 'paymentCardExpiry=0139' \
--data-urlencode 'paymentCardName=Bob Jones' \
--data-urlencode 'notifyURL=https://yourdomain.com/notify'
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'method=checkEnrollment' \ --data-urlencode 'accessToken=ab3c896eaa' \ --data-urlencode 'transactionCurrency=AUD' \ --data-urlencode 'transactionAmount=1.00' \ --data-urlencode 'transactionProduct=Test Product' \ --data-urlencode 'paymentCardNumber=5123456789012346' \ --data-urlencode 'paymentCardExpiry=0139' \ --data-urlencode 'paymentCardName=Bob Jones' \ --data-urlencode 'notifyURL=https://yourdomain.com/notify'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
  <acsURL>https://acs.sandbox.3dsecure.io/3dsmethod</acsURL>
  <paReq>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlaWx1bi1vdmVybG9yZC5tZXJjaGFudHdhcnJpb3IudGVzdC9ub3RpZnkucGhwIn0=</paReq>
  <notifyURL>https://yourdomain.com/notify</notifyURL>
  <threeDSServerTransID/>
  <threeDSCompInd/>
  <fallback>N</fallback>
</mwResponse>
0 Operation successful https://acs.sandbox.3dsecure.io/3dsmethod eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlaWx1bi1vdmVybG9yZC5tZXJjaGFudHdhcnJpb3IudGVzdC9ub3RpZnkucGhwIn0= https://yourdomain.com/notify N
{
    "responseCode": 0,
    "responseMessage": "Operation successful",
    "acsURL": "https:\/\/acs.sandbox.3dsecure.io\/3dsmethod",
    "paReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlaWx1bi1vdmVybG9yZC5tZXJjaGFudHdhcnJpb3IudGVzdC9ub3RpZnkucGhwIn0=",
    "notifyURL": "https:\/\/yourdomain.com\/notify",
    "threeDSServerTransID": "",
    "threeDSCompInd": "",
    "fallback": "N"
}
{ "responseCode": 0, "responseMessage": "Operation successful", "acsURL": "https:\/\/acs.sandbox.3dsecure.io\/3dsmethod", "paReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlaWx1bi1vdmVybG9yZC5tZXJjaGFudHdhcnJpb3IudGVzdC9ub3RpZnkucGhwIn0=", "notifyURL": "https:\/\/yourdomain.com\/notify", "threeDSServerTransID": "", "threeDSCompInd": "", "fallback": "N" }
Step 3 - 3DS Method Data

The 3DS Method Data is used by issuers to gather a device fingerprint from your customer directly.

  1. Render a hidden HTML iframe in the cardholder's browser
  2. Create a form with an input field named threeDSMethodData
  3. This field must contain the paReq (retrieved from Step2 ) and be Base64-URL encoded
  4. Post the form to the acsURL (retrieved from Step2 ), with the HTML iframe as a target

Example

Add an iframe to the user's browser using JavaScript

let displayBox = document.getElementById('displayBox'); 
let iframe = document.createElement('iframe'); 
 iframe.classList.add('hidden'); 
 iframe.name = "threeDSMethodIframe";
 displayBox.appendChild(iframe); 

Resulting in the following html

<iframe name="threeDSMethodIframe" class="hidden"/> 

Create a HTML form that contains the input field:

<form class="" id="threeDSMethodForm"> 
  <input type="hidden" name="threeDSMethodData" id="threeDSMethodData"/> 
</form> 

This form can be submitted using the following JavaScript:

let form = document.getElementById('threeDSMethodForm');
document.getElementById('threeDSMethodData').value = '<paReq from Step 2>';

// Fill out the form information and submit.
form.action = '<acsURL from Step 2>';
form.target = iframe.name; // name of iframe
form.method = 'POST';
form.submit();

The acsURL will respond with the threeDSServerTransID which will be submitted via POST to the notifyURL you specified in your Step 1 - getAccessToken request.

If the callback from the acsURL is not received by your notifyURL within 10 seconds from the POST call above, it is deemed to have failed. In this situation you should proceed to Step 4 and set the 3DS Completion Indicator (threeDSCompInd) to N.

{"threeDSServerTransID": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyJ9"}

If your notifyURL receives a threeDSServerTransID you can proceed to Step 4 and set the 3DS Completion Indicator (threeDSCompInd) to Y. You may want to communicate with your frontend after gathering a device fingerprint using the 3DS Method Data above. If this is the case see postMessage Notifications for further information.

Step 4 - checkTDSAuth

The checkTDSAuth method determines if the issuer opts for a frictionless or challenge flow. If the issuer opts for a frictionless flow you will receive a threeDSToken and you can move to Step 7. If the issuer requests a challenge flow, you should continue with Step 5 and Step 6 below.

Parameters

Parameter Description
method

This field is case sensitive.
Example: checkTDSAuth
Required: Yes

accessToken

The accessToken obtained in Step 1.
Example: 2783a265a0
Required: Yes

transactionAmount

The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00
Required: Yes

transactionCurrency

One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD
Required: Yes

transactionProduct

A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.
Required: Yes

paymentCardNumber

Do not send separators with the card number (e.g. 1234-5678… or 1234 5678).
Example: 5123456789012346 or 4557012345678902
Valid length: Between 13 and 16 digits
Required: Yes

paymentCardExpiry

This must be MMYY format. The month must be zero padded if it is less than 10.
Example: 0513
Valid length: 4 digits
Required: Yes

paymentCardCSC

This is also known as the CVN or CVV/2. This is required by some Acquirers if the transaction is initiated by the customer. Please contact Merchant Warrior for more information.
Example: 123
Valid length: Between 3 and 4 characters
Required: Yes

paymentCardName

This must contain at the very least a space and no less than two characters. Only alphanumeric characters, hyphens, spaces and full stops are allowed.
Example: Mr. Example Person or MR E PERSON or Example Person
Valid length: Between 3 and 255 characters
Required: Yes

mobilePhone

The mobile phone number provided by the Cardholder.
Required: No

browserAcceptHeader

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
Required: Yes

browserJavascriptEnabled

Boolean that represents the ability of the cardholder browser execute JavaScript.
Required: Yes

browserJavaEnabled

Boolean that represents the ability of the cardholder browser execute JavaScript.
Required: Conditional, on if browserJavascriptEnabled is true

browserColorDepth

Required if browserJavascriptEnabled is true

Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. In case the actual value does not exist in the allowed values, use the closest lower value.
Required: Conditional, on if browserJavascriptEnabled is true

browserLanguage

Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
Required: Yes

browserScreenHeight

Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.
Required: Conditional, on if browserJavascriptEnabled is true

browserScreenWidth

Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
Required: Conditional, on if browserJavascriptEnabled is true

browserTZ

Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.
Required: Conditional, on if browserJavascriptEnabled is true

browserUserAgent

Exact content of the HTTP user-agent header. Note: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion.
Required: Conditional, on if browserJavascriptEnabled is true

purchaseDate

Date and time of the purchase expressed in UTC.
Required: Yes

billAddrLine1

First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Required: Yes

billAddrCity

The city of the Cardholder billing address associated with the card used for this purchase.
Required: Yes

billAddrState

The ISO 3166-2 state or province of the Cardholder billing address associated with the card used for this purchase.
Required: Yes

billAddrCountry

Two letter ISO 3166-1 alpha-2 country code.
Required: Yes

billAddrPostCode

ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.
Required: Yes

threeDSCompInd

Indicates whether the 3DS Method (fingerprinting) successfully completed. This is either provided in Step 2 or determined in Step 3.
Required: Yes

threeDSRequestorAuthenticationInd

Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request.
Required: Yes

  • 01 Payment transaction
  • 02 Recurring transaction
  • 03 Instalment transaction
  • 04 Add card
  • 05 Maintain card
  • 06 Cardholder verification as part of EMV token ID&V
threeDSRequestorChallengeInd

This is an optional field that indicates whether or not you would like to perform or have a preference to request a challenge flow.
Required: No

  • 01 No preference
  • 02 No challenge requested
  • 03 Challenge requested: 3DS Requestor Preference
  • 04 Challenge requested: Mandate
threeDSRequestorURL

Your website URL that a customer can use to identify your business.
Required: Yes

threeDSServerTransID

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
Required: Yes

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=checkTDSAuth' \
--data-urlencode 'accessToken=ab3c896eaa' \
--data-urlencode 'threeDSServerTransID=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyJ9' \
--data-urlencode 'transactionCurrency=AUD' \
--data-urlencode 'transactionAmount=1.00' \
--data-urlencode 'transactionProduct=Test Product' \
--data-urlencode 'customerName=Bob Jones' \
--data-urlencode 'paymentCardNumber=5123456789012346' \
--data-urlencode 'paymentCardExpiry=0139' \
--data-urlencode 'paymentCardCSC=123' \
--data-urlencode 'paymentCardName=Bob Jones' \
--data-urlencode 'notifyURL=https://yourdomain.com/notify' \
--data-urlencode 'mobilePhone=0712341234' \
--data-urlencode 'browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9' \
--data-urlencode 'browserColorDepth=24' \
--data-urlencode 'browserJavaEnabled=1' \
--data-urlencode 'browserJavascriptEnabled=1' \
--data-urlencode 'browserLanguage=en-US' \
--data-urlencode 'browserScreenHeight=1080' \
--data-urlencode 'browserScreenWidth=1920' \
--data-urlencode 'browserTZ=-600' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36' \
--data-urlencode 'purchaseDate=20211208021057' \
--data-urlencode 'billAddrCity=Brisbane' \
--data-urlencode 'billAddrCountry=AU' \
--data-urlencode 'billAddrLine1=345 Ann Street' \
--data-urlencode 'billAddrPostCode=4000' \
--data-urlencode 'billAddrState=QLD' \
--data-urlencode 'threeDSCompInd=Y' \
--data-urlencode 'threeDSRequestorAuthenticationInd=01' \
--data-urlencode 'threeDSRequestorChallengeInd=03' \
--data-urlencode 'threeDSRequestorURL=https://yourdomain.com'
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'method=checkTDSAuth' \ --data-urlencode 'accessToken=ab3c896eaa' \ --data-urlencode 'threeDSServerTransID=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImY3OGYyM2ZlLTEzNzAtNDYyNC1iNDI5LThhYjhkODQ1NWJkYyJ9' \ --data-urlencode 'transactionCurrency=AUD' \ --data-urlencode 'transactionAmount=1.00' \ --data-urlencode 'transactionProduct=Test Product' \ --data-urlencode 'customerName=Bob Jones' \ --data-urlencode 'paymentCardNumber=5123456789012346' \ --data-urlencode 'paymentCardExpiry=0139' \ --data-urlencode 'paymentCardCSC=123' \ --data-urlencode 'paymentCardName=Bob Jones' \ --data-urlencode 'notifyURL=https://yourdomain.com/notify' \ --data-urlencode 'mobilePhone=0712341234' \ --data-urlencode 'browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9' \ --data-urlencode 'browserColorDepth=24' \ --data-urlencode 'browserJavaEnabled=1' \ --data-urlencode 'browserJavascriptEnabled=1' \ --data-urlencode 'browserLanguage=en-US' \ --data-urlencode 'browserScreenHeight=1080' \ --data-urlencode 'browserScreenWidth=1920' \ --data-urlencode 'browserTZ=-600' \ --data-urlencode 'browserUserAgent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36' \ --data-urlencode 'purchaseDate=20211208021057' \ --data-urlencode 'billAddrCity=Brisbane' \ --data-urlencode 'billAddrCountry=AU' \ --data-urlencode 'billAddrLine1=345 Ann Street' \ --data-urlencode 'billAddrPostCode=4000' \ --data-urlencode 'billAddrState=QLD' \ --data-urlencode 'threeDSCompInd=Y' \ --data-urlencode 'threeDSRequestorAuthenticationInd=01' \ --data-urlencode 'threeDSRequestorChallengeInd=03' \ --data-urlencode 'threeDSRequestorURL=https://yourdomain.com'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
  <authenticationFlow>challenge</authenticationFlow>
  <challengeData>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE4YTdhZDg2LWM2NGQtNDk0Ni05OGY4LTc5OGEzNThhMGQzZSIsImFjc1RyYW5zSUQiOiIyZjdkMmJiMC04MjM5LTRlMjQtODZlMi1iNjIwNWRkMmNkNzciLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwibWVzc2FnZVR5cGUiOiJDUmVxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0=</challengeData>
  <acsURL>https://acs.sandbox.3dsecure.io/browser/challenge/manual</acsURL>
  <notifyURL>https://www.yourdomain.com/notify.php</notifyURL>
  <tdsPayKey>dd768b6592aeb9d860d29d3a6587f3d5</tdsPayKey>
  <tdsPayToken>YIWT12204697802153</tdsPayToken>
</mwResponse>
0 Operation successful challenge eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE4YTdhZDg2LWM2NGQtNDk0Ni05OGY4LTc5OGEzNThhMGQzZSIsImFjc1RyYW5zSUQiOiIyZjdkMmJiMC04MjM5LTRlMjQtODZlMi1iNjIwNWRkMmNkNzciLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwibWVzc2FnZVR5cGUiOiJDUmVxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0= https://acs.sandbox.3dsecure.io/browser/challenge/manual https://www.yourdomain.com/notify.php dd768b6592aeb9d860d29d3a6587f3d5 YIWT12204697802153
{
    "responseCode": 0,
    "responseMessage": "Operation successful",
    "authenticationFlow": "challenge",
    "challengeData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE4YTdhZDg2LWM2NGQtNDk0Ni05OGY4LTc5OGEzNThhMGQzZSIsImFjc1RyYW5zSUQiOiIyZjdkMmJiMC04MjM5LTRlMjQtODZlMi1iNjIwNWRkMmNkNzciLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwibWVzc2FnZVR5cGUiOiJDUmVxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0=",
    "acsURL": "https:\/\/acs.sandbox.3dsecure.io\/browser\/challenge\/manual",
    "notifyURL": "https:\/\/www.yourdomain.com\/notify.php",
    "tdsPayKey": "dd768b6592aeb9d860d29d3a6587f3d5",
    "tdsPayToken": "YIWT12204697802153"
}
{ "responseCode": 0, "responseMessage": "Operation successful", "authenticationFlow": "challenge", "challengeData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE4YTdhZDg2LWM2NGQtNDk0Ni05OGY4LTc5OGEzNThhMGQzZSIsImFjc1RyYW5zSUQiOiIyZjdkMmJiMC04MjM5LTRlMjQtODZlMi1iNjIwNWRkMmNkNzciLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwibWVzc2FnZVR5cGUiOiJDUmVxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0=", "acsURL": "https:\/\/acs.sandbox.3dsecure.io\/browser\/challenge\/manual", "notifyURL": "https:\/\/www.yourdomain.com\/notify.php", "tdsPayKey": "dd768b6592aeb9d860d29d3a6587f3d5", "tdsPayToken": "YIWT12204697802153" }
Step 5 - Challenge

If the issuer has opted for a challenge flow, you will need to present the authentication experience (two-factor authentication) to the customer.

Example

Add an iframe to the users browser, either statically or using JavaScript.

let displayBox = document.getElementById('displayBox');
let iframe = document.createElement('iframe');
iframe.name = "challengeIframe";
displayBox.appendChild(iframe);

Add a form containing the appropriate input elements:

<form class="" id="challengeForm">
  <input type="hidden" name="creq" id="creq"/>
  <!-- This input can carry up to 1024 Base64-URL encoded characters -->
  <input type="hidden" name="threeDSSessionData" id="threeDSSessionData"/>
</form>

Fill out the form inputs and submit them to the acsURL in the iframe.

let form = document.getElementById('challengeForm');
document.getElementById('creq').value = '<challengeData from Step 4>';
form.action = '<acsURL from Step 4>';
form.target = iframe.name; // name of the iframe
form.method = 'POST'; 
form.submit();

The acsURL will respond with the cres which will be submitted via POST to your notifyURL that was specified in Step 1.

{"cres": "eyJhY3NUcmFuc0lEIjoiZTg5YzNmNzQtNTlkOS00N2QxLTg3Y2EtZGZlMTQyMmI4MWMwIiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI5ZDE2MzUwZC1mZDdhLTRjODItYTYwOC1lMjgzZjdlNDNmNmUiLCJ0cmFuc1N0YXR1cyI6IlkifQ=="}

You may want to communicate with your frontend after performing a challenge. If this is the case see postMessage Notifications for further information.

Step 6 - checkPARes

The checkPARes method is used to verify the result the of the challenge. At this stage you can determine (based on the challenge result) if you would like to proceed with the transaction (Step 7) or not. The PARes value submitted in this request should be the cres you received from Step 5.

You will receive a threeDSToken that you can use in Step 7.

Parameter Description
method

This field is case sensitive.
Example: checkPARes

accessToken

The accessToken obtained in Step 1.
Example: 2783a265a0

cres

This is the cres obtained in Step 5.
Example: eJzNWVmvm9iy/it

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'cres=eyJhY3NUcmFuc0lEIjoiZTg5YzNmNzQtNTlkOS00N2QxLTg3Y2EtZGZlMTQyMmI4MWMwIiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI5ZDE2MzUwZC1mZDdhLTRjODItYTYwOC1lMjgzZjdlNDNmNmUiLCJ0cmFuc1N0YXR1cyI6IlkifQ==' \
--data-urlencode 'method=checkPARes' \
--data-urlencode 'accessToken=fe82081303'
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'cres=eyJhY3NUcmFuc0lEIjoiZTg5YzNmNzQtNTlkOS00N2QxLTg3Y2EtZGZlMTQyMmI4MWMwIiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI5ZDE2MzUwZC1mZDdhLTRjODItYTYwOC1lMjgzZjdlNDNmNmUiLCJ0cmFuc1N0YXR1cyI6IlkifQ==' \ --data-urlencode 'method=checkPARes' \ --data-urlencode 'accessToken=fe82081303'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <threeDSStatusReason/>
  <responseMessage>Operation successful</responseMessage>
  <threeDSCavv>e1E3SN0xF1lDp9js723iASu3wrA=</threeDSCavv>
  <threeDSToken>ebfac7e662da4bd05c9e</threeDSToken>
  <responseCode>0</responseCode>
  <threeDSV2Version>2.1.0</threeDSV2Version>
  <threeDSServerTransID>2d1752a3-7564-4e1b-88f8-197a3f670e9c</threeDSServerTransID>
  <threeDSEci>05</threeDSEci>
  <threeDSStatus>Y</threeDSStatus>
</mwResponse>
Operation successful e1E3SN0xF1lDp9js723iASu3wrA= ebfac7e662da4bd05c9e 0 2.1.0 2d1752a3-7564-4e1b-88f8-197a3f670e9c 05 Y
{
    "threeDSStatusReason": "",
    "responseMessage": "Operation successful",
    "threeDSCavv": "e1E3SN0xF1lDp9js723iASu3wrA=",
    "threeDSToken": "ebfac7e662da4bd05c9e",
    "responseCode": 0,
    "threeDSV2Version": "2.1.0",
    "threeDSServerTransID": "2d1752a3-7564-4e1b-88f8-197a3f670e9c",
    "threeDSEci": "05",
    "threeDSStatus": "Y"
}
{ "threeDSStatusReason": "", "responseMessage": "Operation successful", "threeDSCavv": "e1E3SN0xF1lDp9js723iASu3wrA=", "threeDSToken": "ebfac7e662da4bd05c9e", "responseCode": 0, "threeDSV2Version": "2.1.0", "threeDSServerTransID": "2d1752a3-7564-4e1b-88f8-197a3f670e9c", "threeDSEci": "05", "threeDSStatus": "Y" }
Step 7 - processCard

The processCard method is used to process a transaction with a 3D Secure 2 authentication attached to it. The 3D Secure 2 fields that need to be submitted with a transaction are the tdsPayToken, tdsPayKey and threeDSToken.

If the issuer opted for a frictionless flow, you will have these values after completing Step 4. If the issuer opted for a challenge flow, you will have these values after completing Step 6.

Parameter Description
method

This field is case sensitive.
Example: processCard

accessToken

The accessToken obtained in Step 1.
Example: 2783a265a0

transactionCurrency

One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD

transactionAmount

The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00

transactionProduct

A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.

transactionReferenceID

This is a merchant’s unique reference ID for a transaction sent to Merchant Warrior. The main purpose of this ID is to verify the transaction via the queryCard method in the event a valid response is not received.
Example: A257240023321
Valid length: Up to 40 characters

customerName

This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters.
Example: Mr. Example Person
Valid length: Between 2 and 255 characters

customerCountry

Two letter ISO 3166-1 alpha-2 country code.
Example: AU
Valid length: 2 characters

customerState

Freeform field, keep consistent for your records and reporting.
Example: Queensland
Valid length: Up to 75 characters

customerPostCode

This can also accommodate ZIP/Post codes for international transactions.
Example: 4000
Valid length: Between 4 and 10 characters

customerCity

Freeform field, keep consistent for your records and reporting.
Example: Brisbane
Valid length: Up to 75 characters

customerAddress

Freeform field.
Example: 123 Test Street
Valid length: Up to 255 characters

custom1

Freeform field. Returned as <custom1> in the XML response.
Valid length: Up to 500 characters

custom2

Freeform field. Returned as <custom2> in the XML response.
Valid length: Up to 500 characters

custom3

Freeform field. Returned as <custom3> in the XML response.
Valid length: Up to 500 characters

tdsPayToken

Obtained from Step 4

tdsPayKey

Obtained from Step 4

threeDSToken

Obtained from Step 4 if frictionless was used, or Step 6 if challenge flow was used

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'MW-API-VERSION: 2.0' \
--data-urlencode 'method=processCard' \
--data-urlencode 'accessToken=0d8a130e1d' \
--data-urlencode 'transactionCurrency=AUD' \
--data-urlencode 'transactionAmount=1.00' \
--data-urlencode 'transactionProduct=Test Product' \
--data-urlencode 'customerName=Bob Jones' \
--data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481' \
--data-urlencode 'customerCountry=Australia' \
--data-urlencode 'customerState=QLD' \
--data-urlencode 'customerPostCode=4000' \
--data-urlencode 'customerCity=Brisbane' \
--data-urlencode 'customerAddress=123 Street' \
--data-urlencode 'custom1=iyqqgcm0e3' \
--data-urlencode 'custom2=1wzw49131m' \
--data-urlencode 'custom3=anghwydnmp' \
--data-urlencode 'transactionReferenceID=009vhidhne' \
--data-urlencode 'tdsPayToken=YIWT12204697802153' \
--data-urlencode 'tdsPayKey=dd768b6592aeb9d860d29d3a6587f3d5' \
--data-urlencode 'threeDSToken=3bbb998a9b10e39c7291'
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'MW-API-VERSION: 2.0' \ --data-urlencode 'method=processCard' \ --data-urlencode 'accessToken=0d8a130e1d' \ --data-urlencode 'transactionCurrency=AUD' \ --data-urlencode 'transactionAmount=1.00' \ --data-urlencode 'transactionProduct=Test Product' \ --data-urlencode 'customerName=Bob Jones' \ --data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481' \ --data-urlencode 'customerCountry=Australia' \ --data-urlencode 'customerState=QLD' \ --data-urlencode 'customerPostCode=4000' \ --data-urlencode 'customerCity=Brisbane' \ --data-urlencode 'customerAddress=123 Street' \ --data-urlencode 'custom1=iyqqgcm0e3' \ --data-urlencode 'custom2=1wzw49131m' \ --data-urlencode 'custom3=anghwydnmp' \ --data-urlencode 'transactionReferenceID=009vhidhne' \ --data-urlencode 'tdsPayToken=YIWT12204697802153' \ --data-urlencode 'tdsPayKey=dd768b6592aeb9d860d29d3a6587f3d5' \ --data-urlencode 'threeDSToken=3bbb998a9b10e39c7291'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <custom1>iyqqgcm0e3</custom1>
  <cardExpiryYear>39</cardExpiryYear>
  <custom2>1wzw49131m</custom2>
  <custom3>anghwydnmp</custom3>
  <responseMessage>Transaction approved</responseMessage>
  <transactionReferenceID>009vhidhne</transactionReferenceID>
  <cardType>mc</cardType>
  <responseCode>0</responseCode>
  <authCode>194827</authCode>
  <transactionAmount>1.00</transactionAmount>
  <authResponseCode>00</authResponseCode>
  <transactionID>533-a0a20def-58b2-11ec-abd4-005056b209e0</transactionID>
  <receiptNo>000066781583</receiptNo>
  <cardExpiryMonth>01</cardExpiryMonth>
  <feeAmount>0.19</feeAmount>
  <customHash>d3d9f05927055f723a0af7010f6688c5</customHash>
  <authSettledDate>2021-12-10</authSettledDate>
  <paymentCardNumber>512345XXXXXX2346</paymentCardNumber>
  <authMessage>Approved</authMessage>
</mwResponse>
iyqqgcm0e3 39 1wzw49131m anghwydnmp Transaction approved 009vhidhne mc 0 194827 1.00 00 533-a0a20def-58b2-11ec-abd4-005056b209e0 000066781583 01 0.19 d3d9f05927055f723a0af7010f6688c5 2021-12-10 512345XXXXXX2346 Approved
{
    "custom1": "iyqqgcm0e3",
    "cardExpiryYear": "39",
    "custom2": "1wzw49131m",
    "custom3": "anghwydnmp",
    "responseMessage": "Transaction approved",
    "transactionReferenceID": "009vhidhne",
    "cardType": "mc",
    "responseCode": 0,
    "authCode": "194827",
    "transactionAmount": "1.00",
    "authResponseCode": "00",
    "transactionID": "533-a0a20def-58b2-11ec-abd4-005056b209e0",
    "receiptNo": "000066781583",
    "cardExpiryMonth": "01",
    "feeAmount": "0.19",
    "customHash": "d3d9f05927055f723a0af7010f6688c5",
    "authSettledDate": "2021-12-10",
    "paymentCardNumber": "512345XXXXXX2346",
    "authMessage": "Approved"
}
{ "custom1": "iyqqgcm0e3", "cardExpiryYear": "39", "custom2": "1wzw49131m", "custom3": "anghwydnmp", "responseMessage": "Transaction approved", "transactionReferenceID": "009vhidhne", "cardType": "mc", "responseCode": 0, "authCode": "194827", "transactionAmount": "1.00", "authResponseCode": "00", "transactionID": "533-a0a20def-58b2-11ec-abd4-005056b209e0", "receiptNo": "000066781583", "cardExpiryMonth": "01", "feeAmount": "0.19", "customHash": "d3d9f05927055f723a0af7010f6688c5", "authSettledDate": "2021-12-10", "paymentCardNumber": "512345XXXXXX2346", "authMessage": "Approved" }
Authorization Only processCard

The Authorization Only processCard method should be used when you are performing a 3D Secure 2 authorization via your own MPI provider. After the authentication is complete you should receive the equivalent of a threeDSEci, threeDSXid, threeDSCavv, threeDSStatus and threeDSV2Version that you will use to process the transaction.

Parameter Description
method

This field is case sensitive.
Example: processCard

accessToken

The accessToken obtained in Step 1.
Example: 2783a265a0

transactionCurrency

One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD

transactionAmount

The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00

transactionProduct

A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.

transactionReferenceID

This is a merchant’s unique reference ID for a transaction sent to Merchant Warrior. The main purpose of this ID is to verify the transaction via the queryCard method in the event a valid response is not received.
Example: A257240023321
Valid length: Up to 40 characters

customerName

This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters.
Example: Mr. Example Person
Valid length: Between 2 and 255 characters

customerCountry

Two letter ISO 3166-1 alpha-2 country code.
Example: AU
Valid length: 2 characters

customerState

Freeform field, keep consistent for your records and reporting.
Example: Queensland
Valid length: Up to 75 characters

customerPostCode

This can also accommodate ZIP/Post codes for international transactions.
Example: 4000
Valid length: Between 4 and 10 characters

customerCity

Freeform field, keep consistent for your records and reporting.
Example: Brisbane
Valid length: Up to 75 characters

customerAddress

Freeform field.
Example: 123 Test Street
Valid length: Up to 255 characters

custom1

Freeform field. Returned as <custom1> in the XML response.
Valid length: Up to 500 characters

custom2

Freeform field. Returned as <custom2> in the XML response.
Valid length: Up to 500 characters

custom3

Freeform field. Returned as <custom3> in the XML response.
Valid length: Up to 500 characters

threeDSEci

The electronic commerce indicator returned after the 3D Secure authentication attempt.
Example: 05

threeDSXid

The 3D Secure transaction identifier.
Example: 2d1752a3-7564-4e1b-88f8-197a3f670e9c

threeDSCavv

The cardholder authentication value returned after the 3D Secure authentication attempt.
Example: e1E3SN0xF1lDp9js723iASu3wrA=

threeDSStatus

The status of the 3D Secure authentication attempt.
Example: Y

threeDSV2Version

The version that was used during the 3D Secure authentication attempt.
Example: 2.2.0

Copy
curl --location --request POST 'https://api.merchantwarrior.com/post/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'MW-API-VERSION: 2.0' \
--data-urlencode 'method=processCard' \
--data-urlencode 'accessToken=0d8a130e1d' \
--data-urlencode 'transactionCurrency=AUD' \
--data-urlencode 'transactionAmount=1.00' \
--data-urlencode 'transactionProduct=Test Product' \
--data-urlencode 'customerName=Bob Jones' \
--data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481' \
--data-urlencode 'customerCountry=Australia' \
--data-urlencode 'customerState=QLD' \
--data-urlencode 'customerPostCode=4000' \
--data-urlencode 'customerCity=Brisbane' \
--data-urlencode 'customerAddress=123 Street' \
--data-urlencode 'custom1=iyqqgcm0e3' \
--data-urlencode 'custom2=1wzw49131m' \
--data-urlencode 'custom3=anghwydnmp' \
--data-urlencode 'transactionReferenceID=009vhidhne' \
--data-urlencode 'threeDSEci=05' \
--data-urlencode 'threeDSXid=2d1752a3-7564-4e1b-88f8-197a3f670e9c' \
--data-urlencode 'threeDSCavv=e1E3SN0xF1lDp9js723iASu3wrA=' \
--data-urlencode 'threeDSStatus=Y' \
--data-urlencode 'threeDSV2Version=2.2.0' 
curl --location --request POST 'https://api.merchantwarrior.com/post/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'MW-API-VERSION: 2.0' \ --data-urlencode 'method=processCard' \ --data-urlencode 'accessToken=0d8a130e1d' \ --data-urlencode 'transactionCurrency=AUD' \ --data-urlencode 'transactionAmount=1.00' \ --data-urlencode 'transactionProduct=Test Product' \ --data-urlencode 'customerName=Bob Jones' \ --data-urlencode 'hash=8caaaf6691331f8637f1a24c1b720481' \ --data-urlencode 'customerCountry=Australia' \ --data-urlencode 'customerState=QLD' \ --data-urlencode 'customerPostCode=4000' \ --data-urlencode 'customerCity=Brisbane' \ --data-urlencode 'customerAddress=123 Street' \ --data-urlencode 'custom1=iyqqgcm0e3' \ --data-urlencode 'custom2=1wzw49131m' \ --data-urlencode 'custom3=anghwydnmp' \ --data-urlencode 'transactionReferenceID=009vhidhne' \ --data-urlencode 'threeDSEci=05' \ --data-urlencode 'threeDSXid=2d1752a3-7564-4e1b-88f8-197a3f670e9c' \ --data-urlencode 'threeDSCavv=e1E3SN0xF1lDp9js723iASu3wrA=' \ --data-urlencode 'threeDSStatus=Y' \ --data-urlencode 'threeDSV2Version=2.2.0'
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy
<?xml version="1.0"?>
<mwResponse>
  <custom1>iyqqgcm0e3</custom1>
  <cardExpiryYear>39</cardExpiryYear>
  <custom2>1wzw49131m</custom2>
  <custom3>anghwydnmp</custom3>
  <responseMessage>Transaction approved</responseMessage>
  <transactionReferenceID>009vhidhne</transactionReferenceID>
  <cardType>mc</cardType>
  <responseCode>0</responseCode>
  <authCode>194827</authCode>
  <transactionAmount>1.00</transactionAmount>
  <authResponseCode>00</authResponseCode>
  <transactionID>533-a0a20def-58b2-11ec-abd4-005056b209e0</transactionID>
  <receiptNo>000066781583</receiptNo>
  <cardExpiryMonth>01</cardExpiryMonth>
  <feeAmount>0.19</feeAmount>
  <customHash>d3d9f05927055f723a0af7010f6688c5</customHash>
  <authSettledDate>2021-12-10</authSettledDate>
  <paymentCardNumber>512345XXXXXX2346</paymentCardNumber>
  <authMessage>Approved</authMessage>
</mwResponse>
iyqqgcm0e3 39 1wzw49131m anghwydnmp Transaction approved 009vhidhne mc 0 194827 1.00 00 533-a0a20def-58b2-11ec-abd4-005056b209e0 000066781583 01 0.19 d3d9f05927055f723a0af7010f6688c5 2021-12-10 512345XXXXXX2346 Approved
{
    "custom1": "iyqqgcm0e3",
    "cardExpiryYear": "39",
    "custom2": "1wzw49131m",
    "custom3": "anghwydnmp",
    "responseMessage": "Transaction approved",
    "transactionReferenceID": "009vhidhne",
    "cardType": "mc",
    "responseCode": 0,
    "authCode": "194827",
    "transactionAmount": "1.00",
    "authResponseCode": "00",
    "transactionID": "533-a0a20def-58b2-11ec-abd4-005056b209e0",
    "receiptNo": "000066781583",
    "cardExpiryMonth": "01",
    "feeAmount": "0.19",
    "customHash": "d3d9f05927055f723a0af7010f6688c5",
    "authSettledDate": "2021-12-10",
    "paymentCardNumber": "512345XXXXXX2346",
    "authMessage": "Approved"
}
{ "custom1": "iyqqgcm0e3", "cardExpiryYear": "39", "custom2": "1wzw49131m", "custom3": "anghwydnmp", "responseMessage": "Transaction approved", "transactionReferenceID": "009vhidhne", "cardType": "mc", "responseCode": 0, "authCode": "194827", "transactionAmount": "1.00", "authResponseCode": "00", "transactionID": "533-a0a20def-58b2-11ec-abd4-005056b209e0", "receiptNo": "000066781583", "cardExpiryMonth": "01", "feeAmount": "0.19", "customHash": "d3d9f05927055f723a0af7010f6688c5", "authSettledDate": "2021-12-10", "paymentCardNumber": "512345XXXXXX2346", "authMessage": "Approved" }
postMessage Notifications

You may want to perform other actions such as hiding your iframes after you perform a device fingerprint (Step 3) or perform a challenge (Step 5). If this is the case you should implement a message event on the page that holds your iframe(s), that listens for a postMessage.

Listener Example

window.addEventListener("message", (e) => {
    // The URL below is the URL that holds your iframe(s)
    if (e.origin === CHANGE_THIS_TO_YOUR_DOMAIN) {
        const eventData = e.data;

        // After you perform a device fingerprint (Step 3 - 3DS Method Data)
        if (eventData.hasOwnProperty('threeDSServerTransID')) {
            // Proceed to Step 4 - checkTDSAuth
            checkTDSAuth(eventData.threeDSServerTransID);
        }

        // After you perform a challenge (Step 5 - Challenge)
        if (eventData.hasOwnProperty('cres')) {
            // Proceed to Step 6 - checkPARes
            checkPARes(eventData.cres);
        }

        // Perform other actions here (such as adding loading animations, hiding iframes etc)
        otherActions();
    }
});

Server Side

When your notifyURL receives a callback from us you should respond to the callback with valid javascript. A sample of what you should send is below.

<script type="text/javascript">
    // For Step 3 - 3DS Method Data
    const data = {
        threeDSServerTransID: request.threeDSServerTransID
    };

    // For Step 5 - Challenge
    const data = {
        cres: request.cres;
    };

    window.parent.postMessage(data, CHANGE_THIS_TO_YOUR_DOMAIN);
</script>
3DS Transaction Statuses

The table below lists all possible values for the threeDSStatus and their definitions.

Status Definition
Y Authentication/ Account Verification Successful
N Not Authenticated /Account Not Verified; Transaction denied
U Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq
A Attempts Processing Performed; Not Authenticated/Verified , but a proof of attempted authentication/verification is provided
C Challenge Required; Additional authentication is required using the CReq/CRes
R Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.

The table below lists all possible values for the threeDSStatusReason and their definitions.

Status Reason Definition
01 Card authentication failed
02 Unknown Device
03 Unsupported Device
04 Exceeds authentication frequency limit
05 Expired card
06 Invalid card number
07 Invalid transaction
08 No Card record
09 Security failure
10 Stolen card
11 Suspected fraud
12 Transaction not permitted to cardholder
13 Cardholder not enrolled in service
14 Transaction timed out at the ACS
15 Low confidence
16 Medium confidence
17 High confidence
18 Very High confidence
19 Exceeds ACS maximum challenges
20 Non-Payment transaction not supported
21 3RI transaction not supported
80 (mastercard) Identity Check Insights
80 (visa) Error Connecting to ACS
81 (visa) ACS Timed Out
82 (visa) Invalid Response from ACS
83 (visa) System Error Response from ACS
84 (visa) Internal Error While Generating CAVV
85 (visa) VMID not eligible for requested program
86 (visa) Protocol Version Not Supported by ACS
87 (visa) Transaction is excluded from Attempts Processing (includes non- reloadable pre-paid cards and Non- Payments (NPA))
88 (visa) Requested program not supported by the ACS