Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
This topic outlines all the steps that are required to add 3DS to your Mastercard Gateway integration using the Payer Authentication API, including how to use the authentication result to process a payment.
To view examples of the API requests and responses used in the 3DS flow with the Payer Authentication API, download the Postman collection.
After you have completed your integration, see Testing your 3DS Integration to test it.
As a prerequisite for this implementation, you should have implemented your basic Direct Payment integration.
The Initiate Authentication
operation is used to determine the 3DS versions available to you for a given card, based on the following:
The 3DS feature of the gateway supports 3DS2 only.
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:
Table: Initiate Authentication Request fields
Field | Required/Optional | Description |
---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. 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 | Currency of the order. |
transaction.id |
Required | Unique identifier for this payment authentication. |
order.id |
Required | A unique identifier for this order. |
authentication.channel |
Required | Channel in which the authentication request is being initiated. You can specify one of the following:
|
authentication.purpose |
Optional | Purpose of the authentication. 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. If you are establishing a payment agreement and not processing a payment along with it, provide ADD_CARD as the authentication purpose. For more information, see How can I submit a non-payment authentication request ? For a detailed list of use cases related to 3D Secure authentication, see Cardholder-initiated Payments with 3D Secure. |
authentication.acceptVersions |
Optional | 3DS versions that you accept for this payment. If you do not specify a version, 3DS2 is accepted. The gateway uses 3DS2, if supported by the issuer and the card. If 3DS2 is not available, the authentication does not proceed. |
order.merchantCategoryCode |
Optional | Merchant Category Code. Provide the Merchant Category Code if you want to override the default value configured on your acquirer link. |
If you submit the Authenticate Payer request before the ACS Method call completes, the Authenticate Payer request proceeds but the Authenticate Payer response contains authentication.3ds2.methodCompleted = false . If the issuer's ACS has successfully completed the method call to obtain additional information about the payer's browser, the authentication.3ds2.methodCompleted field the AUTHENTICATE PAYER response is true.
The gateway returns the following key fields in the Initiate Authentication response:
authentication.version
: If 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.authentication.redirect.html
: Insert the content of this field into the page being displayed to the payer, if authentication.3ds2.methodSupported = SUPPORTED. 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://test-nbkpayment.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" }
If the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), and when all payer and payment data has been gathered, submit the Authenticate Payer request when the payer clicks the Pay Now button on the checkout page.
Submit this operation by providing the following fields.
Authenticate Payer request fields
Field | Required/Optional | Description |
---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. Use the same details as in the preceding INITIATE AUTHENTICATION operation. |
order.amount |
Required | The total amount of the order. |
transaction.id |
Required | Transaction ID. Use the same transaction.id as in the preceding Initiate Authentication operation. |
order.id |
Required | Order ID. The same order.id as the Initiate Authentication operation that preceded it. |
device.ipAddress |
Optional | Required if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation. Required if you support ITMX Local Switch EMVCo authentications. EMV 3DS authentications support IPv4 and IPv6 addresses from the API version 79. IPv6 is only used in the EMV 3DS authentication, and not in any subsequent Authorize, Pay or other operation. |
sourceOfFunds.provided.card.nameOnCard |
Optional | Name on the card. Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.number |
Optional | Card number. Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.expiry |
Optional | Card expiration details. Required if you support ITMX Local Switch EMVCo authentications. |
authentication.redirectResponseUrl |
Required | URL to which you want to redirect the payer after completing the payer authentication process. You do not need to provide this URL if you are certain that there will be no interaction with the payer. |
device.browser |
Optional | User-Agent header of the payer’s browser. Required if authentication.channel = PAYER_BROWSER . |
device.browserDetails object |
Optional | Browser details. Required if authentication.channel = PAYER_BROWSER . |
billing.address object object |
Optional | Billing address of the payer. It is strongly recommended that you include this in your request whenever available. |
shipping.address object |
Optional | Shipping address of the payer. It is strongly recommended that you include this in your request whenever available. |
customer object |
Optional | Payer’s details. It is strongly recommended that you include this in your request whenever available. |
The fields returned in the AUTHENTICATE PAYER
response depend on the following:
For a session-authenticated operation, the response is filtered to remove data that is not related to the payer and only whitelisted fields are returned. For more information, see Session basics. For fields returned for a certificate/password authenticated request, see Response Fields for a Certificate/Password-authenticated Request.
The gateway returns the following key fields in the AUTHENTICATE PAYER
response:
transaction.authenticationStatus
:Details about the authentication status.response.gatewayRecommendation
: Recommendation on whether you should proceed to a financial transaction or not, based on the 3DS transaction filtering rules configured by you or your PSP: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)
The gateway recommends you to proceed:
authentication.redirect.html
field provided in the response. After the challenge is completed, the ACS redirects the payer back to your website and triggers a callback that contains the orderId, transactionId, response.gatewayRecommendation, and result fields.
Determine the outcome of the authentication based on the value returned in the response.gatewayRecommendation
field. The same rules apply as described above for the AUTHENTICATE PAYER
response. If the recommendation is PROCEED, continue with step 3.You should not rely on data returned in the browser to determine the next processing step. Ensure that either you handle the authenticate payer response in your server, or you perform a retrieve transaction operation from your server to ensure the response is successful.
The following table lists the AUTHENTICATE PAYER
response fields returned for a certificate/password authenticated request, that is, submitted with a merchant ID and API password from your server rather than with a session ID from your website or the payer’s browser. For more information, see Frequently asked questions.
authentication.3ds.authenticationToken
is not provided if a frictionless flow is used.Table: Response Fields for a Certificate/Password-authenticated Request
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.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 | * |
The fields returned in the Authentication Payer response depend on:
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://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<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 can initiate an Authorize or PAY operation. In addition to the standard fields, you must provide the following fields:
order.id
: Use the same order.id
that you supplied in the INITIATE AUTHENTICATION
and AUTHENTICATE PAYER
operations.authentication.transactionId
: Use the same 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
object, as the gateway uses the authentication.transactionId
to look up the authentication results that it stored when you asked it to perform authentication. The gateway passes the required information to the acquirer.URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<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 Payer Authentication API as a server-side API, or a client-side API on your web site or the payer’s browser.
INITIATE AUTHENTICATION
and AUTHENTICATE PAYER
operations.Authentication Only: Perform Initiate Authentication and Authenticate Payer.INITIATE AUTHENTICATION
, AUTHENTICATE PAYER
, and AUTHORIZE/PAY operations.For more information about 3-D Secure general FAQs, see FAQs.