- Introduction
- 3DS 2 Authentication Flows
- Step 1 - getAccessToken
- Step 2 - checkEnrollment
- Step 3 - 3DS Method Data
- Step 4 - checkTDSAuth
- Step 5 - Challenge
- Step 6 - checkPARes
- Step 7 - processCard
- Card Tokens
- Authorization Only processCard
- postMessage Notifications
- 3DS Transaction Statuses
- Troubleshooting
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.
A sample of the full manual implementation can be found here - https://jsfiddle.net/merchantwarrior/nt1fpq9g/137/
A sample of performing a tokenized payment with 3DSv2 with our WebSDK can be found here - https://jsfiddle.net/merchantwarrior/dmgzsth9/3/
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.
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.
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. |
merchantUUID | The value of this parameter is provided to you by Merchant Warrior. |
apiKey | The value of this parameter is provided to you by Merchant Warrior. |
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. |
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. |
notifyURL | Asynchronous POST notifications will be sent to this URL. |
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. |
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. |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?xml version="1.0"?>
<mwResponse>
<responseCode>0</responseCode>
<responseMessage>Operation successful</responseMessage>
<token>51acb2b7b7</token>
</mwResponse>
{
"responseCode": 0,
"responseMessage": "Operation successful",
"token": "51acb2b7b7"
}
{
"responseCode": 0,
"responseMessage": "Operation successful",
"token": "51acb2b7b7"
}
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. |
accessToken | The accessToken obtained in Step 1. |
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. |
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. |
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. |
paymentCardNumber | Do not send separators with the card number (e.g. 1234-5678… or 1234 5678). |
paymentCardExpiry | This must be MMYY format. The month must be zero padded if it is less than 10. |
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. |
notifyURL | Asynchronous POST notifications will be sent to this URL. |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?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>
{
"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"
}<?xml version="1.0"?>
<mwResponse>
<responseCode>0</responseCode>
<responseMessage>Operation successful</responseMessage>
<acsURL/>
<paReq/>
<enrolled>N</enrolled>
<eci>1</eci>
<error/>
</mwResponse>
{
"responseCode": 0,
"responseMessage": "Operation successful",
"acsURL": "",
"paReq": "",
"enrolled": "N",
"eci": 1,
"error": ""
}
{
"responseCode": 0,
"responseMessage": "Operation successful",
"acsURL": "",
"paReq": "",
"enrolled": "N",
"eci": 1,
"error": ""
}The 3DS Method Data is used by issuers to gather a device fingerprint from your customer directly.
- Render a hidden HTML iframe in the cardholder's browser
- Create a form with an input field named threeDSMethodData
- This field must contain the paReq (retrieved from Step2 ) and be Base64-URL encoded
- 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.
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. |
accessToken | The accessToken obtained in Step 1. |
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. |
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. |
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. |
paymentCardNumber | Do not send separators with the card number (e.g. 1234-5678… or 1234 5678). |
paymentCardExpiry | This must be MMYY format. The month must be zero padded if it is less than 10. |
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. |
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. |
mobilePhone | The mobile phone number provided by the Cardholder. |
browserAcceptHeader | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. |
browserJavascriptEnabled | Boolean that represents the ability of the cardholder browser execute JavaScript. |
browserJavaEnabled | Boolean that represents the ability of the cardholder browser execute JavaScript. |
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. |
browserLanguage | Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. |
browserScreenHeight | Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. |
browserScreenWidth | Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property. |
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. |
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. |
purchaseDate | Date and time of the purchase expressed in UTC. |
billAddrLine1 | First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. |
billAddrCity | The city of the Cardholder billing address associated with the card used for this purchase. |
billAddrState | The ISO 3166-2 state or province of the Cardholder billing address associated with the card used for this purchase. |
billAddrCountry | Two letter ISO 3166-1 alpha-2 country code. |
billAddrPostCode | ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. |
threeDSCompInd | Indicates whether the 3DS Method (fingerprinting) successfully completed. This is either provided in Step 2 or determined in Step 3. |
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.
|
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.
|
threeDSRequestorURL | Your website URL that a customer can use to identify your business. |
threeDSServerTransID | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. |
notifyURL | Asynchronous POST notifications will be sent to this URL. |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?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>
{
"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"
}<?xml version="1.0"?>
<mwResponse>
<threeDSStatusReason/>
<responseMessage>Operation successful</responseMessage>
<threeDSXid>adddc6a0-2ee9-4d50-8d39-31bc358e2c8a</threeDSXid>
<authenticationFlow>frictionless</authenticationFlow>
<threeDSCavv>aj0Soeu1to535JdkUms9TPxzduk=</threeDSCavv>
<threeDSToken>e3ab4103b609278f20b6</threeDSToken>
<responseCode>0</responseCode>
<threeDSV2Version>2.1.0</threeDSV2Version>
<tdsPayToken>SZWP25289218540736</tdsPayToken>
<liabilityShift>Y</liabilityShift>
<tdsPayKey>93e468cdbdef3d3a762683e5db8dc5c9</tdsPayKey>
<threeDSEci>6</threeDSEci>
<threeDSStatus>A</threeDSStatus>
</mwResponse>
{
"threeDSStatusReason": "",
"responseMessage": "Operation successful",
"threeDSXid": "adddc6a0-2ee9-4d50-8d39-31bc358e2c8a",
"authenticationFlow": "frictionless",
"threeDSCavv": "aj0Soeu1to535JdkUms9TPxzduk=",
"threeDSToken": "e3ab4103b609278f20b6",
"responseCode": 0,
"threeDSV2Version": "2.1.0",
"tdsPayToken": "SZWP25289218540736",
"liabilityShift": "Y",
"tdsPayKey": "93e468cdbdef3d3a762683e5db8dc5c9",
"threeDSEci": 6,
"threeDSStatus": "A"
}
{
"threeDSStatusReason": "",
"responseMessage": "Operation successful",
"threeDSXid": "adddc6a0-2ee9-4d50-8d39-31bc358e2c8a",
"authenticationFlow": "frictionless",
"threeDSCavv": "aj0Soeu1to535JdkUms9TPxzduk=",
"threeDSToken": "e3ab4103b609278f20b6",
"responseCode": 0,
"threeDSV2Version": "2.1.0",
"tdsPayToken": "SZWP25289218540736",
"liabilityShift": "Y",
"tdsPayKey": "93e468cdbdef3d3a762683e5db8dc5c9",
"threeDSEci": 6,
"threeDSStatus": "A"
}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.
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. |
accessToken | The accessToken obtained in Step 1. |
cres | This is the |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?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>
<liabilityShift>Y</liabilityShift>
<threeDSEci>05</threeDSEci>
<threeDSStatus>Y</threeDSStatus>
</mwResponse>
{
"threeDSStatusReason": "",
"responseMessage": "Operation successful",
"threeDSCavv": "e1E3SN0xF1lDp9js723iASu3wrA=",
"threeDSToken": "ebfac7e662da4bd05c9e",
"responseCode": 0,
"threeDSV2Version": "2.1.0",
"threeDSServerTransID": "2d1752a3-7564-4e1b-88f8-197a3f670e9c",
"liabilityShift": "Y",
"threeDSEci": "05",
"threeDSStatus": "Y"
}
{
"threeDSStatusReason": "",
"responseMessage": "Operation successful",
"threeDSCavv": "e1E3SN0xF1lDp9js723iASu3wrA=",
"threeDSToken": "ebfac7e662da4bd05c9e",
"responseCode": 0,
"threeDSV2Version": "2.1.0",
"threeDSServerTransID": "2d1752a3-7564-4e1b-88f8-197a3f670e9c",
"liabilityShift": "Y",
"threeDSEci": "05",
"threeDSStatus": "Y"
}
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. |
accessToken | The accessToken obtained in Step 1. |
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. |
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. |
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. |
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. |
customerName | This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters. |
customerCountry | Two letter ISO 3166-1 alpha-2 country code. |
customerState | Freeform field, keep consistent for your records and reporting. |
customerPostCode | This can also accommodate ZIP/Post codes for international transactions. |
customerCity | Freeform field, keep consistent for your records and reporting. |
customerAddress | Freeform field. |
custom1 | Freeform field. Returned as |
custom2 | Freeform field. Returned as |
custom3 | Freeform field. Returned as |
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 |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?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>
{
"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"
}The 3DS 2.0 workflow also supports authenticating card token (cardID) based payments, as well as digitalWalletToken based payments.
When authenticating a card token or digitalWalletToken, simply removed the following fields, and substitute in your cardID or digitalWalletToken instead -
- paymentCardNumber
- paymentCardExpiry
- paymentCardName
The following 3DS 2.0 methods support this feature -
- Step 2 - checkEnrollment
- Step 4 - checkTDSAuth
- Step 7 - 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. |
accessToken | The accessToken obtained in Step 1. |
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. |
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. |
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. |
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. |
customerName | This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters. |
customerCountry | Two letter ISO 3166-1 alpha-2 country code. |
customerState | Freeform field, keep consistent for your records and reporting. |
customerPostCode | This can also accommodate ZIP/Post codes for international transactions. |
customerCity | Freeform field, keep consistent for your records and reporting. |
customerAddress | Freeform field. |
custom1 | Freeform field. Returned as |
custom2 | Freeform field. Returned as |
custom3 | Freeform field. Returned as |
threeDSEci | The electronic commerce indicator returned after the 3D Secure authentication attempt. |
threeDSXid | The 3D Secure transaction identifier. |
threeDSCavv | The cardholder authentication value returned after the 3D Secure authentication attempt. |
threeDSStatus | The status of the 3D Secure authentication attempt. |
threeDSV2Version | The version that was used during the 3D Secure authentication attempt. |
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 availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample availableNo sample available
No sample available<?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>
{
"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"
}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>
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 |
Q: I am getting an error The accessToken hash is mismatched on incorrect
. What am I doing wrong?
A: This error is returned under the following conditions -
- The urlHash has been calculated incorrectly
- The notifyURL in the request doesn't match the notifyURL used when generating the accessToken
- The transactionAmount in the request doesn't match the transactionAmount used when generating the accessToken