3-D Secure Authentication (3DS1 and 3DS2)
3-Domain Secure™ (3-D Secure or 3DS) authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before submitting an Authorization or Pay transaction. The Mastercard Gateway supports both 3DS versions — 3DS1 and EMV 3DS.
3DS1 is the legacy version that allows payers to authenticate at their issuer's Access Control Server (ACS) by entering a password previously registered with their card issuer. 3DS2 also accepts entering a password or a frictionless flow. Schemes supported for authentication include Mastercard, Visa, American Express, JCB, Discover, and Diners Club.
While your payment service provider can configure both 3DS1 and 3DS2 on your merchant profile with the gateway, you can restrict the versions you want to accept by specifying your choice in the authentication request. If both are accepted then the gateway uses 3DS2 (if supported by the issuer and the card) and will attempt to falls back to 3DS1 only in regulated markets. If both are not available, the authentication will not proceed. However, you can still proceed with the payment if the gateway recommends you to do so.
The following diagram illustrates the authentication flow for a payment where the gateway falls back to 3DS1 authentication because 3DS2 is not available for the card. The gateway will attempt 3DS1 in other cases too, for example, where you are only enabled for 3DS1, or have restricted the authentication version to only 3DS1 in the authentication request.
The authentication flow for a successful authentication is as follows:
- A payer browses your shop site, selects one or more products, proceeds to the payment page, and selects to pay with a card that supports 3DS1 but not 3DS2.
- Initiate Authentication: You ask the gateway to check with the card scheme if the card is enrolled for 3DS.
- If 3DS1 authentication of the payer is available, the gateway returns the card enrollment details in the response.
If the card supports both 3DS1 and 3DS2, then the gateway attempts 3DS2 first. See 3DS2 flow.
- Authenticate Payer: You ask the gateway to perform the initiated authentication.
- The gateway provides you with details of the authentication for a challenge flow (where the payer is required to respond to a challenge presented by the issuer).
- You redirect the payer’s web browser to the ACS, which presents its authentication UI. The issuer returns the authentication result to the gateway. The gateway redirects the payer directly to your website.
- Use the 3DS Authentication Transaction ID in a Payment Operation: You submit the payment for processing.
- You display the order confirmation page to the payer.
Here are some key terms that will be referenced throughout the 3DS1 integration documentation.
| Term | Description |
|---|---|
| Access Control Server (ACS) | A component that operates in the issuer domain, which verifies whether authentication is available for a card number and device type, and authenticates specific transactions. |
| ACS Method Call | Applies to 3DS2 authentication. It's a call that allows the ACS to gather additional data to determine the risk score for the payer. When 3DS2 is available and when the ACS call details are returned in the response after initiating the authentication, these details are passed to the payer's browser, which are submitted as a form post in a hidden iframe, so that the ACS can collect additional data. |
| Frictionless Flow | An authentication flow where the payer is not required to respond to a challenge because the ACS deems the payer as low risk. |
| Challenge Flow | An authentication flow where the payer is redirected to the ACS and is required to respond to a challenge to identify themselves, because the ACS does not have sufficient payer information to deem the payer as low risk. |
| Payment Session | A payment session, or simply session, is a temporary container for any request fields and values of operations that reference a session. You can use it in an operation to reference the request fields and values than providing them directly in the operation request. When the gateway receives an operation that references a session, it forms the final request by combining the request fields in the session and those supplied directly in the request. For more information, see payment session. |
| Session Authentication |
Authentication using a payment session. This authentication allows payers to provide their payment details directly to the gateway via a client-side interaction with the gateway, either through a payer's browser or an app on the payer's mobile device. It uses basic HTTP authentication mechanism (similar to password authentication) where you must provide 'merchant.<your gateway merchant ID>' in the userid portion and the session Id in the password portion. To use this authentication type, you must first create a session by submitting a session request (see Create session [REST][NVP]) from your server to the gateway server. |
| Merchant Authentication | A mechanism that allows the merchant to authenticate API requests to the gateway, for example, password/certificate/session authentication. |
| Authentication API | A server-side API consisting of two operations, Initiate Authentication and Authenticate Payer, that must be submitted from your server to the gateway server. It can also be used as a client-side API using session-based authentication. |
| 3DS JavaScript API | A client-side JavaScript API that allows you to initiate 3DS authentication from the payer's browser using session-based authentication. |
| Authentication Channel | Indicates where 3DS authentication is taking place, in the payer's browser, in an app on the payer's mobile device, or in your system with no payer present to interact. These have implications in terms of which authentication types and flows are available, for example, 3DS1 can only be supported in browser with a payer available for interaction with the ACS. |
| Authentication Purpose |
|
Fallback to 3DS1 for countries with extended 3DS1 support
Initiate authentication - 3DS1 fallback
The Initiate Authentication operation is used to determine which 3DS versions are available for a specific card. The existing 3-D Secure authentication version will fall back to 3DS1 if any of the following conditions are met.
- You have specified in your request that you only accept 3DS1, which includes authentication.acceptVersions=3DS1 or a combination of 3DS1 and EMV 3DS authentication methods, such as authentication.acceptVersions=3DS1, 3DS2, or not provided.
- Your payment service provider has configured the 3DS1 authentication in your merchant profile
- The card scheme supports 3DS1 payer authentication
- authentication.channel=PAYER_BROWSER
- authentication.purpose=PAYMENT_TRANSACTION, and
- The following are the outcome of request that the gateway submits to the relevant authentication providers.
- EMV 3DS is not available for this card, or
- EMV 3DS authentication is not available at issuer's Access Control Server (ACS), and you are located in a country where 3DS1 support is extended and 3DS1 fallback is preferred over EMV 3DS scheme stand-in authentication.
Supported countries and schemes
This table lists the countries and authentication schemes where 3DS1 fallback is attempted when EMV 3DS authentication is not available at the issuer's ACS.
| Authentication scheme | Merchant country |
|---|---|
| Mastercard Identity Check | India and Bangladesh |
| Visa Secure | India, Bangladesh, Sri Lanka, Bhutan, Maldives, and Nepal |
| American Express SafeKey | India |
Your country is identified from the country of your billing address configured in your profile.
For aggregators submitting the Initiate Authentication request on behalf of other merchants, the merchant country is provided in the
order.subMerchant.address.country request field. See Aggregator Support for more details.Examples
{
"authentication": {
"acceptVersions":"3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order": {
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "<card_number>"
}
}
},
"apiOperation": "INITIATE_AUTHENTICATION"
}
For example, merchant in country where 3DS1 support has been extended, and EMV 3DS authentication is not available at issuers ACS.
{
"authentication": {
"acceptVersions":"3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order": {
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "<card_number>"
}
}
},
"apiOperation": "INITIATE_AUTHENTICATION"
}
For example, cross-border transaction for merchant in country where 3DS1 support has been extended, and international issuers ACS supports EMV 3DS; or merchant in country where 3DS1 has been decommissioned and local issuers ACS supports EMV 3DS.
{
"authentication": {
"3ds2": {
"directoryServerId": "A999999999",
"methodSupported": "NOT_SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name"
},
"acceptVersions": "3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"html": "<script id=\"initiate-authentication-script\"></script>"
},
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TEST3DS12AUTH",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-11-03T08:22:17.087Z",
"currency": "USD",
"id": "Test1",
"lastUpdatedTime": "2022-11-03T08:23:17.905Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"fundingMethod": "DEBIT",
"number": "555555xxxxxx0018",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-11-03T08:23:17.905Z",
"timeOfRecord": "2022-11-03T08:22:17.087Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "70"
}
Integration methods
Please click here to see how to migrate from the Legacy 3DS1 operation to the Authentication API:3-D Secure Authentication Integration guide: Hosted Checkout integration page.
Step 1: Create and update session
3DS JS uses session-based authentication. As a first step, you must create a session, which you can then update with the request fields and values you wish to store in the session.
You can create a session using the Create Session call. This is a server-side API call and is a prerequisite for integrating with the JS API. It returns the following fields:
session.id: A unique session identifier which you must provide on subsequent requests to reference session contents.-
session.authenticationLimit: The limit on the number of transaction requests the payer's browser can submit. You can supply a value in the request or use the gateway's default. By default, the gateway sets it to 5 but you can provide a value up to 25. This limit prevents malicious users from using the authentication request as a potential carding attack, and from performing Denial of Service (DoS) attacks on your site by submitting large numbers of (potentially billable) transactions.
Note that any authentication retries you initiate will be checked against the authentication limit. session.aes256Key: The key you can use to decrypt sensitive data passed to your website via the payers's browser or mobile device.session.version: You can use this field to implement optimistic locking of the session content.session.updateStatus: A summary of the outcome of the last attempt to modify the session.
You can add or update fields in a session using the Update Session call. It allows you to add payment and payer data into a session that can subsequently become the input to determine the risk associated with a payer in an authentication operation. The following fields are required in a session:
| Parameter | Existence | Description |
|---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required |
Details of the card being used for the payment. Note that you can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see FAQs. |
order.amount |
Required | The total amount of the order. |
order.currency |
Required | The currency of the order. |
transaction.id |
Required | A unique identifier for this payment authentication. |
order.id |
Required | A unique identifier for this order. |
authentication.channel |
Required | The channel in which the authentication request is being initiated. You can specify one of the following:
|
authentication.redirectResponseUrl |
Optional | The URL to which you want to redirect the payer after completing the payer authentication process. You must provide this URL, unless you are certain that there will be no interaction with the payer. |
authentication.purpose |
Optional | By default, this field is set to "PAYMENT_TRANSACTION" to indicate that authentication is to be performed when processing a card payment. However, you can specify a different purpose to indicate non-payment authentication. See Submit a Non-Payment Authentication Request. |
authentication.acceptVersions |
Optional | The 3DS versions that you will accept for this payment. If you do not specify a version, both 3DS1 and 3DS2 will be accepted. The gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed. Note that the fall back scenarios will only apply to regulated markets. For more information about the fallback scenarios, see Initiate Authentication - 3DS1 Fallback. |
order.merchantCategoryCode |
Optional | Provide the Merchant Category Code if you want to override the default value configured on your acquirer link. |
Please note that you cannot remove fields from a session but can only overwrite values for existing fields.
Step 2: Initialize the API
Reference the 3DS JS API (threeDS.js) from the gateway servers. This will place a ThreeDS object into the window/global namespace.
Once you have created a session, initialize the API using the configure( ) method. This method should be called during the page load or when the DOM is in ready state. It should be called only once for the page load. After calling this method, 3DS JS will provide configuration values as member variables.
You can initialize the 3DS JS API by invoking the configure() method, with the following mandatory fields as arguments in a map object:
merchantId: Your merchant identifier on the gateway.sessionId: The session Id that you created using the Create Session call.containerId: The <div> id in your html where the API will inject a hidden iframe.callback: A function that will be invoked once the API has been initialized.configuration: JSON value supporting data elements like userLanguage(Optional), REST API version (wsVersion).
<html>
<head>
<script src="https://mtf.gateway.mastercard.com/static/threeDS/1.3.0/three-ds.min.js"
data-error="errorCallback"
data-cancel="cancelCallback">
</script>
<script type="text/javascript">
//The output of this call will return 'false', since the API is not configured yet
console.log(ThreeDS.isConfigured());
/**
Configure method with the configuration{} parameter set and demonstrates the state change of the ThreeDS object before and after the configure method is invoked.
*/
ThreeDS.configure({
merchantId: {merchantId},
sessionId: {sessionId},
containerId: "3DSUI",
callback: function () {
if (ThreeDS.isConfigured())
console.log("Done with configure");
},
configuration: {
userLanguage: "en-AU", //Optional parameter
wsVersion: 72
}
});
//The output of this call will return 'true', since the API is configured
console.log(ThreeDS.isConfigured());
//The output of the following code might look like "ThreeDS JS API Version : 1.2.0"
console.log("ThreeDS JS API Version : " + ThreeDS.version);
</script>
</head>
<body>
<div id="3DSUI"></div>
</body>
</html>
Step 3: Initiate authentication
Once all payer and payment data has been gathered into a session, you can initiate the authentication by invoking the initiateAuthentication() method. It determines the versions of payer authentication available to you for a given card, which will be based on the following:
- the 3DS versions configured on your merchant profile, for example, 3DS1 or 3DS2;
- the card type
- preferences you have indicated in the request
- the version of 3DS the card has been enrolled in
- the 3DS transaction filtering rules configured by you or your payment service provider.
The operation also enables any background activities (such as a 3DS2 ACS Call) to be carried out for purposes such as gathering additional payer data to support a subsequent authenticatePayer() method.
To allow any ACS call process to complete before you attempt the
authenticatePayer() method, it is recommended that you invoke the initiateAuthentication() method at the earliest opportunity in your checkout process, and act on the response immediately. This will typically be when the payer completes entering their card number on the checkout page, for example, 'onBlur' event of the Card Number input field, or when selecting a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least ten seconds for the ACS Method call to complete.You can initiate authentication by providing the following mandatory fields in the initiateAuthentication() method:
- transactionId: The unique identifier for this payment authentication.
- orderId: The unique identifier for this order.
- callback: The callback function.
- optionalParams: (Optional) argument with any additional Initiate Authentication REST API request fields such as correlationId.
If 3DS authentication of the payer is available, the following fields are returned in the data argument of the callback function. Otherwise, the response will include an error.
data.restApiResponse: Contains raw response from the Initiate Authentication REST API call.data.correlationId: The last correlation Id that was used for making the Initiate Authentication REST API call. It allows you to match the response to the request.data.gatewayRecommendationdata.authenticationVersion: Returns 3DS1 or 3DS2 if authentication is available. Note that the fall back scenarios will only apply to regulated markets. For more information about the fallback scenarios, see Initiate Authentication - 3DS1 Fallback.
To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
gatewayRecommendation |
Next step |
|---|---|
| DO_NOT_PROCEED | Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
| PROCEED | You can proceed to authenticate the payer using the authenticatePayer( ) method call. |
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
ThreeDS.initiateAuthentication({orderId}, {transactionId}, function (data) {
if (data && data.error) {
var error = data.error;
//Something bad happened, the error value will match what is returned by the Authentication API
console.error("error.code : ", error.code);
console.error("error.msg : ", error.msg);
console.error("error.result : ", error.result);
console.error("error.status : ", error.status);
} else {
console.log("After Initiate 3DS ", data);
//data.response will contain information like gatewayRecommendation, authentication version, etc.
console.log("REST API raw response ", data.restApiResponse);
console.log("Correlation Id", data.correlationId);
console.log("Gateway Recommendation", data.gatewayRecommendation);
console.log("HTML Redirect Code", data.htmlRedirectCode);
console.log("Authentication Version", data.authenticationVersion);
switch (data.gatewayRecommendation) {
case "PROCEED":
authenticatePayer();//merchant's method
break;
case "DO_NOT_PROCEED":
displayReceipt(data);//merchant's method, you can offer the payer the option to try another payment method.
break;
}
}
}, optionalParams);
{
"authentication":{
"3ds2":{
"methodCompleted":false,
"methodSupported":"SUPPORTED"
},
"redirect":{
"customized":{
"3DS":{
"methodPostData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==",
"methodUrl":"<method_url>"
}
}
},
"redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==\" /> </form> <script>document.getElementById(\"initiate3dsSimpleRedirectForm\").submit();</script> </div>",
"version":"3DS2"
},
"order":{
"currency":"AUD",
"status":"AUTHENTICATION_INITIATED"
},
"response":{
"gatewayCode":"AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation":"PROCEED_WITH_AUTHENTICATION"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"number":"512345xxxxxx0008"
}
},
"type":"CARD"
},
"transaction":{
"authenticationStatus":"AUTHENTICATION_AVAILABLE"
},
"version":"72"
}
{
"authentication":{
"redirect":{
"customized":{
"3DS":{
"methodPostData":"e30=",
"methodUrl":"<method_url>"
}
}
},
"redirectHtml": "<script id=\"initiate-authentication-script\"></script>",
"version": "3DS1"
},
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "EUR",
"status": "AUTHENTICATION_INITIATED"
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"number": "512345xxxxxx0008"
}
},
"type": "CARD"
},
"transaction": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE"
},
"version": "72"
}
Step 4: Authenticate payer
Where the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), you can invoke the authenticatePayer() method. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.
You must invoke the authenticatePayer() method by providing the following mandatory fields:
orderId: The same orderId as theinitiateAuthentication()method that preceded it.transactionId: The same transactionId as theinitiateAuthentication()method that preceded it.callback: The callback function.optionalParams: (Optional) argument with any additional Authenticate Payer REST API request fields such as billing and shipping.
The following fields are returned in the data argument of the callback function:
data.restApiResponse: Contains raw response from the Authentication Payer REST API call.data.correlationId: The last correlation Id that was used for making the Authentication Payer REST API call. It allows you to match the response to the request.data.gatewayRecommendationdata.htmlRedirectCode: The gateway always returns this field for insertion into the page displayed to the payer.
To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field returned in the callback. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
gatewayRecommendation |
Next step |
|---|---|
| DO_NOT_PROCEED | Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
| PROCEED | You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow). |
If the gateway recommends you to PROCEED, then paste content of the htmlRedirectCode response field into the page being displayed to the payer.
Frictionless Flow
This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.
Challenge Flow
This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.
- orderId
- transactionId
- gatewayRecommendation
- restApiResponse
You can determine the authentication outcome using the value returned in the gatewayRecommendation field. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
gatewayRecommendation |
Next step |
|---|---|
| DO_NOT_PROCEED | Do not proceed with this card as authentication is declined or unavailable. You can offer the payer the option to try another payment method. |
| PROCEED | You can proceed with the payment as authentication is granted. |
The fields returned in the restApiResponse depend on the flow in effect (frictionless vs challenge) and how the authentication request was initiated (authentication.channel).
For a session-authenticated request, the response is filtered to remove data that's not related to the payer and only whitelisted fields are returned. For more information, see Session Authenticated Operations.
Advanced Integrations
The request submitted by the payer’s browser to your website on completion of the authenticatePayer() method will be parameterized allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. See Advanced Payment Session Integrations.
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
ThreeDS.authenticatePayer({orderId}, {transactionId}, function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code", data.htmlRedirectCode);
displayReceipt(data);
}
}, optionalParams);
function displayReceipt(apiResponse) {
var responseBody = {
"apiResponse": apiResponse
};
var xhr = new XMLHttpRequest();
xhr.open('PUT', '3dsreceipt', true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onreadystatechange = function () {
if (xhr.readyState == XMLHttpRequest.DONE) {
document.documentElement.innerHTML = this.response;
}
}
xhr.send(JSON.stringify(responseBody));
}
{
"authentication":{
"3ds":{
"transactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91"
},
"3ds2":{
"3dsServerTransactionId":"8c4a911c-289a-46c2-a615-887e1cc01a6a",
"acsTransactionId":"2a8234c9-e8ac-449d-a693-97a113b491fc",
"directoryServerId":"A000000004",
"dsTransactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91",
"methodCompleted":false,
"methodSupported":"SUPPORTED",
"protocolVersion":"2.1.0",
"requestorId":"test2ID",
"requestorName":"test2Name",
"transactionStatus":"C"
},
"method":"OUT_OF_BAND",
"payerInteraction":"REQUIRED",
"redirect":{
"customized":{
"3DS":{
"acsUrl":"https://<host_name>/acs/v2/prompt",
"cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9"
}
},
"domainName":"<domain_name>"
},
"redirectHtml":"<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>",
"version":"3DS2"
},
"correlationId":"test",
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"merchant":"TEST_3DS2-1",
"order":{
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"creationTime":"2021-04-13T02:22:59.113Z",
"currency":"AUD",
"id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"lastUpdatedTime":"2021-04-13T02:44:07.161Z",
"merchantCategoryCode":"1234",
"status":"AUTHENTICATION_INITIATED",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0,
"valueTransfer":{
"accountType":"NOT_A_TRANSFER"
}
},
"response":{
"gatewayCode":"PENDING",
"gatewayRecommendation":"PROCEED"
},
"result":"PENDING",
"sourceOfFunds":{
"provided":{
"card":{
"expiry":{
"month":"1",
"year":"39"
},
"number":"512345xxxxxx0008",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:44:07.161Z",
"timeOfRecord":"2021-04-13T02:22:59.113Z",
"transaction":{
"acquirer":{
"merchantId":"99554411"
},
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"currency":"AUD",
"id":"42090084",
"type":"AUTHENTICATION"
},
"version":"60"
}
{
"authentication":{
"3ds1":{
"veResEnrolled":"Y"
},
"payerInteraction":"REQUIRED",
"redirect":{
"domainName":"<domain_name>"
},
"redirectHtml":"<div id=\"redirectTo3ds1AcsSimple\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"redirectTo3ds1Frame\" name=\"redirectTo3ds1Frame\" height=\"100%\" width=\"100%\" > </iframe> <form id =\"redirectTo3ds1Form\" method=\"POST\" action=\"https://<host_name>/acs/b6594e88-608f-4897-a8b5-dd491dc1e54d\" target=\"redirectTo3ds1Frame\"> <input type=\"hidden\" name=\"PaReq\" value=\"eAFVUd9vgjAQfjfxfyBkr6OlgENz1uDUaBadmZr9eFlYaYRFwNEi7r9fizC3e7rvu97Xu+9gdE4PxokXIsmzoWlb2DR4xvIoyfZDc7ed3frmiHY7sI0LzicbzsqCU1hyIcI9N5JI9XiuT8hdz6SwDp74F4VGjio1iwBqoeoqWBxmkkLIvsaLFbWbANQQkPJiMaGSCwnokkMWppxulo8P03dnslF6NQEsLzNZfFPs9AC1AMriQGMpjwOEqqqyRJrIWFgsTwHpEqDrDOtSTyPUNuckovPpYo484o53n1XwHK9Orx9sFvRexFs+BKRfQBRKTgm2+9gnvoGdgY0H2AVU8xCmeiAa7CbGjY2xhbHa6sLBUX8VXICq6dJfCpSphXK9XaZFwM/HPONKVW39mwO6Tn4/114yqTzzbOK4Xr8On7jKlKagVRJlFLGxV8toAEi3ouZgypX6nor5d+du5wf/BK8K\" /> <input type=\"hidden\" name=\"TermUrl\" value=\"https://<host_name>/callbackInterface/gateway/e91c0cc18c143f205a081cde25a3a8cec28b04bb90169115295beb29d0c1dc28\" /> <input type=\"hidden\" name=\"MD\" value=\"\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectTo3ds1Form\"); if (e) { e.submit(); e.remove(); } </script> </div>",
"version":"3DS1"
},
"correlationId":"test",
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"merchant":"TEST_3DS2-1",
"order":{
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"creationTime":"2021-04-13T02:52:24.532Z",
"currency":"AUD",
"id":"3bdbe65b-d0db-4a7d-a8a1-59ae3723da77",
"merchantCategoryCode":"1234",
"status":"AUTHENTICATION_INITIATED",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0,
"valueTransfer":{
"accountType":"NOT_A_TRANSFER"
}
},
"response":{
"gatewayCode":"PENDING",
"gatewayRecommendation":"PROCEED"
},
"result":"PENDING",
"sourceOfFunds":{
"provided":{
"card":{
"expiry":{
"month":"1",
"year":"39"
},
"number":"512345xxxxxx8246",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:54:19.182Z",
"timeOfRecord":"2021-04-13T02:52:24.532Z",
"transaction":{
"acquirer":{
"merchantId":"99554411"
},
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"currency":"AUD",
"id":"three",
"type":"AUTHENTICATION"
},
"version":"60"
}
Step 5: Use the authentication result in a payment operation
When the result of the authenticatePayer() method indicates that you can proceed with the payment (gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:
- order.id: Provide the
orderIdthat you supplied in theinitiateAuthentication()andauthenticatePayer()methods. - authentication.transactionId: Provide the
transactionIdthat you supplied in theinitiateAuthentication()andauthenticatePayer()methods. You do not need to include any of the fields in the authentication parameter group, as the gateway will use the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway will pass the required information to the acquirer.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation":"PAY",
"authentication":{
"transactionId":"<your_transaction_ID>"
},
"order":{
"amount":"100",
"currency":"AUD",
"reference":"<your_order_ID>"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>",
"expiry":{
"month":"1",
"year":"39"
}
}
},
"type":"CARD"
},
"transaction":{
"reference":"<your_order_ID>"
}
}
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
},
"3ds2":{
"dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
"protocolVersion":"2.1.0",
"transactionStatus":"Y"
},
"transactionId":"249213216",
"version":"3DS2"
},
"authorizationResponse":{
"posData":"1605S0100130",
"transactionIdentifier":"TidTest"
},
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_3DS2-1",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"chargeback":{
"amount":0,
"currency":"AUD"
},
"creationTime":"2021-04-13T02:11:06.102Z",
"currency":"AUD",
"id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"lastUpdatedTime":"2021-04-13T02:11:57.049Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"AUD",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"status":"CAPTURED",
"totalAuthorizedAmount":100.00,
"totalCapturedAmount":100.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"00",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"<issuer>",
"number":"512345xxxxxx0008",
"scheme":"Mastercard",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:11:57.049Z",
"timeOfRecord":"2021-04-13T02:11:56.973Z",
"transaction":{
"acquirer":{
"batch":1,
"id":"<acquirer_id>",
"merchantId":"99554411"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"authorizationCode":"028941",
"currency":"AUD",
"id":"1",
"receipt":"1908266016",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"source":"INTERNET",
"stan":"496",
"terminal":"1234",
"type":"PAYMENT"
},
"version":"60"
}
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"jHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"3nzQOuTJDVOsRLuDT9V671B8QkU="
},
"3ds1":{
"paResStatus":"Y",
"veResEnrolled":"Y"
},
"transactionId":"5791",
"version":"3DS1"
},
"authorizationResponse":{
"posData":"1605S0100130",
"transactionIdentifier":"TidTest"
},
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_3DS2-1",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"chargeback":{
"amount":0,
"currency":"AUD"
},
"creationTime":"2021-04-13T03:17:44.895Z",
"currency":"AUD",
"id":"f808076a-0bc6-4f1b-8100-cfe46e43676e",
"lastUpdatedTime":"2021-04-13T03:19:45.964Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"AUD",
"reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
"status":"CAPTURED",
"totalAuthorizedAmount":100.00,
"totalCapturedAmount":100.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"00",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"<issuer>",
"number":"512345xxxxxx8246",
"scheme":"Mastercard",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T03:19:45.964Z",
"timeOfRecord":"2021-04-13T03:19:45.703Z",
"transaction":{
"acquirer":{
"batch":1,
"id":"<acquirer_id>",
"merchantId":"99554411"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"authorizationCode":"003879",
"currency":"AUD",
"id":"1",
"receipt":"1908286018",
"reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
"source":"INTERNET",
"stan":"499",
"terminal":"1234",
"type":"PAYMENT"
},
"version":"60"
}
Step 1: Initiate authentication
The Initiate Authentication operation is used to determine the 3DS versions available to you for a given card, which will be based on
- the 3DS versions configured on your merchant profile, for example, 3DS1 or 3DS2
- the card type
- preferences you have indicated in the request
- the outcome of requests the gateway has sent to the relevant authentication providers to check availability or support for the given card, and
- the gateway's 3DS transaction filtering rules configured by you or your payment service provider.
The operation also enables any background activities (such as a ACS Method call) to be carried out for purposes such as gathering additional payer data to support a subsequent Authenticate Payer operation.
You can initiate authentication by providing the following fields in the Initiate Authentication request:
| Parameter | Existence | Description |
|---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required |
Details of the card being used for the payment. Note that you can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see FAQs. |
order.currency |
Required | The currency of the order. |
transaction.id |
Required | A unique identifier for this payment authentication. |
order.id |
Required | A unique identifier for this order. |
authentication.channel |
Required | The channel in which the authentication request is being initiated. You can specify one of the following:
|
authentication.purpose |
Optional | By default, this field is set to "PAYMENT_TRANSACTION" to indicate that authentication is to be performed when processing a card payment. However, you can specify a different purpose to indicate non-payment authentication. See Submit a Non-Payment Authentication Request. |
authentication.acceptVersions |
Optional | The 3DS versions that you will accept for this payment. If you do not specify a version, both 3DS1 and 3DS2 will be accepted. The gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed. |
order.merchantCategoryCode |
Optional | Provide the Merchant Category Code if you want to override the default value configured on your acquirer link. |
To allow any ACS Method call process to complete before you attempt the Authenticate Payer operation, it is recommended that you submit the Initiate Authentication operation at the earliest opportunity in your checkout process, and act on the response immediately. This will typically be when the payer completes entering their card number on the checkout page, for example, 'onBlur' event of the Card Number input field, or when selecting a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least ten seconds for the ACS Method call to complete.
When you submit the Authenticate Payer request before the ACS Method call completes, the gateway returns HTTP 503 response code. If this happens, pause for a few seconds and then resubmit the Authenticate Payer request as-is. Once the method call has been completed, or ten seconds have elapsed, the request will be allowed to proceed.
The gateway returns the following key fields in the Initiate Authentication response:
authentication.version: If 3DS authentication of the payer is available, this field shows the type 3DS1 or 3DS2. If both are available, 3DS2 is returned.authentication.3ds2.methodSupported: If 3DS2 is available and if the issuer's ACS supports a Method call, this field shows SUPPORTED. The Method call can be used by the ACS to gather additional data prior to the authentication request to increase the likelihood of frictionless authentication being available. The method call is triggered in a hidden iframe, so is invisible to the payer. It also does not provide any callback upon completion.transaction.authenticationStatus: Check out this field if you want more details about the authentication status.-
response.gatewayRecommendation: This field allows you to determine the next step. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
response.gatewayRecommendationNext step DO_NOT_PROCEED Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. PROCEED You can proceed to authenticate the payer using the Authenticate Payer operation. -
authentication.redirect.html: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a hidden DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,div.innerHtml= response.authentication.redirect.html; eval(document.getElementById('initiate-authentication-script').text)If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"authentication":{
"acceptVersions":"3DS1,3DS2",
"channel":"PAYER_BROWSER",
"purpose":"PAYMENT_TRANSACTION"
},
"correlationId":"test",
"order":{
"currency":"AUD"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>"
}
}
},
"apiOperation":"INITIATE_AUTHENTICATION"
}
{
"authentication": {
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name"
},
"acceptVersions": "3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customizedHtml": {
"3ds2": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==",
"methodUrl": "<method_url>"
}
},
"html": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"<method_url>" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TEST3DS12AUTH",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-06-24T06:57:32.714Z",
"currency": "USD",
"id": "TEST4",
"lastUpdatedTime": "2022-06-24T06:57:32.661Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"fundingMethod": "CREDIT",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T06:57:32.661Z",
"timeOfRecord": "2022-06-24T06:57:32.714Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
{
"authentication": {
"3ds1": {
"veResEnrolled": "Y"
},
"acceptVersions": "3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"html": "<script id=\"initiate-authentication-script\"></script>"
},
"version": "3DS1"
},
"correlationId": "test",
"merchant": "TEST3DS12AUTH",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-06-24T07:00:51.195Z",
"currency": "USD",
"id": "TEST5",
"lastUpdatedTime": "2022-06-24T07:00:51.126Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"fundingMethod": "CREDIT",
"number": "512345xxxxxx8246",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T07:00:51.126Z",
"timeOfRecord": "2022-06-24T07:00:51.195Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Step 2: Authenticate payer
Where the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), and once all payer and payment data has been gathered, you can submit the Authenticate Payer request. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.
Use the same API version as the Initiate Authentication request for the Authenticate Payer request.
Submit this operation by providing the following fields. If you only support 3DS1, the gateway ignores the fields specific to 3DS2.
| Parameter | Existence | Description |
|---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. |
order.amount |
Required | The total amount of the order. |
transaction.id |
Required | The same transaction.id as the Initiate Authentication operation that preceded it. |
order.id |
Required | The same order.id as the Initiate Authentication operation that preceded it. |
authentication.redirectResponseUrl |
Optional | The URL to which you want to redirect the payer after completing the payer authentication process. You must provide this URL, unless you are certain that there will be no interaction with the payer. |
order.merchantCategoryCode |
Optional | If you do not provide a value, the default configured on your merchant profile will be used. |
device.browser |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER. |
device.ipAddress |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation. |
device.browserDetails parameter group |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER. |
billing.address parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
shipping.address parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
customer parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
The gateway returns the following key fields in the Authenticate Payer response:
transaction.authenticationStatus: Check out this field if you want more details about the authentication status.-
response.gatewayRecommendation: This field allows you to determine whether you should proceed to a financial transaction or not. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
response.gatewayRecommendationNext step DO_NOT_PROCEED Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. PROCEED You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow). -
authentication.redirect.html: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,div.innerHtml= response.authentication.redirect.html; eval(document.getElementById('authenticate-payer-script').text)If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.
Frictionless Flow
This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.
Challenge Flow
This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.
- order.id
- transaction.id
- response.gatewayRecommendation
- result
You can determine the authentication outcome using the value returned in the response.gatewayRecommendation field. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
If you want additional response data, you can use the Retrieve Transaction operation.
response.gatewayRecommendation |
Next step |
|---|---|
| DO_NOT_PROCEED | Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
| PROCEED | You can proceed with the payment as authentication is granted. |
The fields returned in the Authentication Payer response depend on the flow in effect (frictionless vs challenge), how the authentication request was initiated (authentication.channel), and the authentication mechanism for the request (session or certificate or password).
The following fields are returned for a certificate/password authenticated request. For a session-authenticated operation, the response is filtered to remove data that's not related to the payer and only whitelisted fields are returned. For more information, see session-authentication.
* where applicable, based on the 3DS version and flow (frictionless vs challenge) in effect.
Response Field |
Merchant-authenticated |
|---|---|
| authentication.method | Yes |
| authentication.3ds.authenticationToken | * |
| authentication.3ds.acsEci | Yes |
| authentication.3ds.transactionId | Yes |
| authentication.3ds2.transactionStatus | * |
| authentication.3ds2.acsTransactionId | * |
| authentication.3ds2.dsTransactionId | * |
| authentication.3ds2.3dsServerTransactionId | * |
| authentication.3ds2.3dsServerTransactionId | * |
| authentication.3ds2.protocolVersion | * |
| authentication.3ds1.veResEnrolled | * |
| authentication.amount | Yes |
| authentication.redirect.html | Yes |
| authentication.time | Yes |
| response.gatewayRecommendation | Yes |
| transaction.type | Yes |
| version | Yes |
| timeOfRecord | Yes |
| result | Yes |
| response.debugInformation | * |
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"authentication":{
"redirectResponseUrl":"<host>/merchantSimulator/jsp/simple/output.jsp"
},
"correlationId":"test",
"device": {
"browser": "MOZILLA",
"browserDetails": {
"3DSecureChallengeWindowSize": "FULL_SCREEN",
"acceptHeaders": "application/json",
"colorDepth": 24,
"javaEnabled": true,
"language": "en-US",
"screenHeight": 640,
"screenWidth": 480,
"timeZone": 273
},
"ipAddress": "127.0.0.1"
},
"order":{
"amount":"100",
"currency":"AUD"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>",
"expiry":{
"month":"1",
"year":"39"
}
}
}
},
"apiOperation": "AUTHENTICATE_PAYER"
}
{
"authentication": {
"3ds": {
"transactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8"
},
"3ds2": {
"3dsServerTransactionId": "cf976f0d-cb19-454f-a5b3-3cf09ae07e38",
"acsTransactionId": "c8027c6a-94da-480d-9270-85098bc680d5",
"directoryServerId": "A999999999",
"dsTransactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8",
"methodSupported": "NOT_SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name",
"sdk": {
"timeout": 400,
"uiType": "TEXT"
},
"transactionStatus": "C"
},
"amount": 100.00,
"method": "OUT_OF_BAND",
"payerInteraction": "REQUIRED",
"redirect": {
"customizedHtml": {
"3ds2": {
"acsUrl": "<acs_url>",
"cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9"
}
},
"domainName": "<acs_domain>",
"html": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"<acs_url>" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"time": "2022-06-24T07:04:34.836Z",
"version": "3DS2"
},
"correlationId": "test",
"device": {
"browser": "mozilla",
"ipAddress": "127.0.0.1"
},
"merchant": "TEST3DS12AUTH",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2022-06-24T07:03:43.780Z",
"currency": "USD",
"id": "TEST6",
"lastUpdatedTime": "2022-06-24T07:04:34.795Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"number": "512345xxxxxx8212",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T07:04:34.795Z",
"timeOfRecord": "2022-06-24T07:03:43.780Z",
"transaction": {
"acquirer": {
"merchantId": "123456"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
{
"authentication": {
"3ds1": {
"veResEnrolled": "Y"
},
"amount": 100.00,
"payerInteraction": "REQUIRED",
"redirect": {
"domainName": "<acs_domain>",
"html": "<div id=\"redirectTo3ds1AcsSimple\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"redirectTo3ds1Frame\" name=\"redirectTo3ds1Frame\" height=\"100%\" width=\"100%\" > </iframe> <form id =\"redirectTo3ds1Form\" method=\"POST\" action=\"<acs_url>\" target=\"redirectTo3ds1Frame\"> <input type=\"hidden\" name=\"PaReq\" value=\"eAFVUctuwjAQvCPxD1HUG2rsmPDUYkSLaJH6UoEeuKXJNklFEnAcHn/fdQi09cHyzHrH41kYH9ONtUdVJHk2sl2H2xZmQR4mWTSyV8vZbd8ey2YDlrFCnC4wKBVKeMai8CO0kpB6uHD7XNgS3ibvuJNQq0kScwSwC6QmFcR+piX4we5u/iLdegGrCUhRzadSY6GBnc+Q+SlKs71+XQSAVSQEeZlpdZK83QV2AVCqjYy13hZDxg6Hg+MHKR6SMEJdOEGeAjMXgF3EyHZpfBX0rWMSytan6j6VD9/d/bpdfqx0PCha+7WaLXrRCJi5AaGvUQouBO8Kz+K9oesOPRdYxYOfGltytZhaNy7nDuf0vzMHW/PU5AyoZkp/KaB0FcV/kn2PSlcEeNzmGZIq5Xk9A/t1fv9oUg00pddxRdvrDKrVFx5FUxeMSkJxtQeczNYAmGll9egolWqwxPwbeLPxA6NgtIg=\" /> <input type=\"hidden\" name=\"TermUrl\" value=\"<callback_url>\" /> <input type=\"hidden\" name=\"MD\" value=\"\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectTo3ds1Form\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"time": "2022-06-24T07:12:00.966Z",
"version": "3DS1"
},
"correlationId": "test",
"device": {
"browser": "mozilla",
"ipAddress": "127.0.0.1"
},
"merchant": "TEST3DS12AUTH",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2022-06-24T07:11:40.804Z",
"currency": "USD",
"id": "TEST7",
"lastUpdatedTime": "2022-06-24T07:12:00.949Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"number": "512345xxxxxx8246",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T07:12:00.949Z",
"timeOfRecord": "2022-06-24T07:11:40.804Z",
"transaction": {
"acquirer": {
"merchantId": "123456"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Step 3: Use the authentication result in a payment operation
When the result of the Authenticate Payer operation indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:
- order.id: Provide the order.id that you supplied in the Initiate Authentication and Authenticate Payer operations.
- authentication.transactionId: Provide the transaction.id that you supplied in the Initiate Authentication and Authenticate Payer operations. You do not need to include any of the fields in the authentication parameter group, as the gateway will use the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway will pass the required information to the acquirer.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation":"PAY",
"authentication":{
"transactionId":"<your_transaction_ID>"
},
"order":{
"amount":"100",
"currency":"AUD",
"reference":"<your_order_ID>"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>",
"expiry":{
"month":"1",
"year":"39"
}
}
},
"type":"CARD"
},
"transaction":{
"reference":"<your_order_ID>"
}
}
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
},
"3ds2":{
"dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
"protocolVersion":"2.1.0",
"transactionStatus":"Y"
},
"transactionId":"249213216",
"version":"3DS2"
},
"authorizationResponse":{
"posData":"1605S0100130",
"transactionIdentifier":"TidTest"
},
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_3DS2-1",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"chargeback":{
"amount":0,
"currency":"AUD"
},
"creationTime":"2021-04-13T02:11:06.102Z",
"currency":"AUD",
"id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"lastUpdatedTime":"2021-04-13T02:11:57.049Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"AUD",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"status":"CAPTURED",
"totalAuthorizedAmount":100.00,
"totalCapturedAmount":100.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"00",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"<issuer>",
"number":"512345xxxxxx0008",
"scheme":"Mastercard",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:11:57.049Z",
"timeOfRecord":"2021-04-13T02:11:56.973Z",
"transaction":{
"acquirer":{
"batch":1,
"id":"<acquirer_id>",
"merchantId":"99554411"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"authorizationCode":"028941",
"currency":"AUD",
"id":"1",
"receipt":"1908266016",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"source":"INTERNET",
"stan":"496",
"terminal":"1234",
"type":"PAYMENT"
},
"version":"60"
}
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"jHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"3nzQOuTJDVOsRLuDT9V671B8QkU="
},
"3ds1":{
"paResStatus":"Y",
"veResEnrolled":"Y"
},
"transactionId":"5791",
"version":"3DS1"
},
"authorizationResponse":{
"posData":"1605S0100130",
"transactionIdentifier":"TidTest"
},
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_3DS2-1",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"chargeback":{
"amount":0,
"currency":"AUD"
},
"creationTime":"2021-04-13T03:17:44.895Z",
"currency":"AUD",
"id":"f808076a-0bc6-4f1b-8100-cfe46e43676e",
"lastUpdatedTime":"2021-04-13T03:19:45.964Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"AUD",
"reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
"status":"CAPTURED",
"totalAuthorizedAmount":100.00,
"totalCapturedAmount":100.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"00",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"<issuer>",
"number":"512345xxxxxx8246",
"scheme":"Mastercard",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T03:19:45.964Z",
"timeOfRecord":"2021-04-13T03:19:45.703Z",
"transaction":{
"acquirer":{
"batch":1,
"id":"<acquirer_id>",
"merchantId":"99554411"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"authorizationCode":"003879",
"currency":"AUD",
"id":"1",
"receipt":"1908286018",
"reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
"source":"INTERNET",
"stan":"499",
"terminal":"1234",
"type":"PAYMENT"
},
"version":"60"
}
FAQs
If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Authorize or Pay operation.
All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication version (3DS1 or 3DS2) and the status of the transaction. However, if you have the data it's recommended that you provide it.
authentication.3ds.acsEci: The Electronic Commerce Indicator that may be returned to you in the authentication response message.authentication.3ds.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.-
authentication.3ds.transactionId: A unique transaction identifier generated by the gateway for the 3DS authentication.
For 3DS1, this field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.
For 3DS2, this field corresponds to the identifier assigned by the scheme directory server. authentication.3ds1.paResStatus: Indicates the result of payer authentication with the issuer.authentication.3ds1.veResEnrolled: Indicates whether or not payer authentication is available for the card number you provided.authentication.amount: This is an optional field. It indicates the authentication amount. You need to provide values in this field when the authentication amount differs from theorder.amount. Please check with your payment service provider before providing values in this field.authentication.time: This is an optional field. It indicates the date and time of the payer's authentication. Please check with your payment service provider before providing values in this field.
For General FAQs and other 3DS options, see the Authentication FAQs page.
Testing your integration
Before going live, you must Test your integration to ensure correct functionality.