This guide outlines all the steps that are required to add 3DS to your gateway integration using the Authentication API, including how to use the authentication result to process a payment.
The Initiate Authentication operation is used to determine the 3DS versions available to you for a given card, which will be based on
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). 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 Authenticate Payer request proceeds but the Authenticate Payer response indicates that the method complete indicator is set to "false". If the issuer's ACS has successfully completed the method call to obtain additional information about the payer's browser, the method complete indicator in the Authenticate Payer response will indicate "true".
The gateway returns the following key fields in the Initiate Authentication response:
authentication.version
: If EMV 3DS authentication is available for the payer, 3DS2 is returned. Otherwise, NONE
will be 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.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 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)
URL | https://evopaymentsmexico.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" }
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.
Submit this operation by providing the following fields.
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. |
device.ipAddress |
Optional | Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.nameOnCard |
Optional | Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.number |
Optional | Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.expiry |
Optional | Required if you support ITMX Local Switch EMVCo authentications. |
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 authentication.channel=PAYER_BROWSER. |
device.ipAddress |
Optional | Required if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation. |
device.browserDetails parameter group |
Optional | Required if authentication.channel=PAYER_BROWSER. |
billing.address parameter group |
Optional | It is strongly recommended that you include this in your request whenever available. |
shipping.address parameter group |
Optional | It is strongly recommended that you include this in your request whenever available. |
customer parameter group |
Optional | It is 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.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). |
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)
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.
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.
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.
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.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://evopaymentsmexico.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" }
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:
URL | https://evopaymentsmexico.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" }
You can use the Authentication API as a server-side or a client-side API.
For other general FAQs about the 3-D Secure, see Authentication FAQs.
For more information about the test your integration, see Test your integration.
Copyright © 2023 Mastercard