# EMV 3-D Secure with the Payer Authentication API source: https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md This topic outlines all the steps that are required to add EMV 3-D Secure 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 EMV 3-D Secure flow with the Payer Authentication API, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). After you have completed your integration, see [Testing your EMV 3-D Secure Integration](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/test-3ds-int/index.md) to test it. * [Step 1: Initiate Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#step-1-initiate-authentication) * [Step 2: Authenticate Payer](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#step-2-authenticate-payer) * [Step 3: Use the Authentication Result in a Payment Operation](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#step-3-use-the-authentication-result-in-a-payment) ## Prerequisites {#prerequisites} As a prerequisite for this implementation, you should have implemented a [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/integrate-direct-payment/index.md) integration. ## Step 1: Initiate Authentication {#step-1-initiate-authentication} The [Initiate Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) operation is used to determine the EMV 3-D Secure versions available to you for a given card, based on the following: * EMV 3-D Secure versions configured on your merchant profile. * Card type. * Preferences you have indicated in the request. * Outcome of requests the gateway has sent to the relevant authentication providers to check availability or support for the given card, and * Gateway's EMV 3-D Secure transaction filtering rules configured by you or your payment service provider (PSP). The EMV 3-D Secure feature of the gateway supports 3DS2 only. The gateway considers 3DS2 to include not only EMV 3-D Secure but also some proprietary schemes that are not strictly EMV 3DS-compliant but behave in a similar manner, such as Verve SafeToken. This approach allows merchants to accept these schemes without modifying their existing gateway integration. The operation also enables any background activities, such as an ACS Method call, to be carried out for purposes such as gathering additional payer data to support a subsequent [Authenticate Payer](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) operation. ### Initiate Authentication request {#initiate-authentication-request} You can initiate authentication by providing the following fields in the Initiate Authentication request: #### Initiate Authentication request fields {#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 the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#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: * **MERCHANT_REQUESTED** : If you are requesting authentication of a cardholder without the payer being available for interaction (for example, as part of processing of a recurring payment). This option is currently not supported. * **PAYER_BROWSER** : If the payer is interacting through a web browser (for example, with the merchant's e-commerce web-site). * **PAYER_APP** : If the payer is interacting through an app. The Mobile SDK sets this value for you. For more information, see [Mobile SDK Integration](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/index.md) for further information. | | `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?](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs) For a detailed list of use cases related to EMV 3-D Secure authentication, see [Cardholder-initiated Payments with EMV 3-D Secure](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/cit-mit/index.md). | | `authentication.acceptVersions` | Optional | EMV 3-D Secure 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. | Warning: To allow any ACS method call process to complete before you attempt the AUTHENTICATE PAYER operation, submit the INITIATE AUTHENTICATION operation at the earliest opportunity in your checkout process, and act on the response immediately. The earliest opportunity is typically when the payer completes entering their card number on the checkout page. For example, when the onBlur event of the card number input field is triggered, or when the payer selects a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least 10 seconds for the ACS method call to complete. 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. ### Method URL {#method-url} Method URL is a script that allows an issuing bank or ACS to obtain additional browser information from the cardholder or merchant for risk-based decisioning if it is supported by the card scheme. ### Adding Method URL to your integration {#adding-method-url-to-your-integration} * Merchant can provide their Method Notification URL to the gateway in the INITIATE AUTHENTICATION operation request. * The gateway receives notifications when the method is completed. The gateway then redirects the method completion notification to the merchant's URL. * On a successful redirect, the merchant gets a notification of the 'Method Completion'. Merchant can then proceed with the next step in the Authentication that is AUTHENTICATE PAYER. * If the method completion callback is delayed and received after an Authenticate Payer request, the gateway logs the Authenticate Payer request that has already occurred for this transaction and methodCompleted remains false. In this case, the gateway does not redirect to the Merchant Notification URL and Merchant does not get a notification of the Method completion. ### Validation for merchant method notification URL {#validation-for-merchant-method-notification-url} * Request parameter validation: The URL parameter is validated according to the Standard validation mechanism within the API for URLs. * Sanctions Screening: The new field needs to be passed to the Sanctions Service for screening as part of the flow for Initiate Authenticationrequests from Orchestrator. ### Method completion callback {#method-completion-callback} While redirecting the iframe to the merchant Method Notification URL, the HTTP POST parameters include the EMV 3-D Secure Server Transaction ID and encrypted session data. ### Session data encryption {#session-data-encryption} The usage of encrypted session data in the Method Completion Callback aids in preventing malicious users from viewing the data and any tampering of data. An AES256 key, which is generated as part of the merchant's payment session, is used to encrypt the data. This is similar to the Challenge CompletionFlow. The encrypted session data includes the following information: * OrderId * TransactionId * Initiate Authentication request sent by Merchant * Authentication Status ### Initiate Authentication response {#initiate-authentication-response} The gateway returns the following key fields in the Initiate Authentication response: * `authentication.version`: If EMV 3-D Secure 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.authenticationStatu`s: Check out this field if you want more details about the authentication status. * `response.gatewayRecommendation`: This field allows you to determine the next step. Note that this recommendation is only based on the EMV 3-D Secure transaction filtering rules configured by you or your payment service provider. * DO_NOT_PROCEED: Do not proceed with EMV 3-D Secure authentication for this card, but you may wish to proceed to payment without the EMV 3-D Secure data. Or, you can offer the payer the option to try another payment method. * PROCEED: You can [proceed to authenticate the payer](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#step-2-authenticate-payer) using the Authenticate Payer operation. * RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS: Ask the payer for alternative payment details. For example, a new card or another payment method, and resubmit the request with the new details. Do not resubmit the same request. This is applicable from API version 70 and later. * `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, ```js div.innerHTML = response.authentication.redirect.html; eval(document.getElementById('initiate-authentication-script').text); ``` Warning: If the gateway recommends you not to proceed, then inserting the content of this field into your webpage will not execute any functionality. ### Initiate Authentication request {#initiate-authentication-request-1} | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 | [Click here to download Postman Collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api) - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Frictionless Flow/1. INITIATE AUTHENTICATION ```json { "apiOperation": "INITIATE_AUTHENTICATION", "authentication": { "channel": "PAYER_BROWSER" }, "order": { "currency": "{{currency}}" }, "sourceOfFunds": { "provided": { "card": { "number": "{{fpan}}" } } } } ``` ```json { "authentication": { "3ds2": { "directoryServerId": "A999999999", "methodCompleted": false, "methodSupported": "SUPPORTED", "protocolVersion": "2.2.0", "requestorId": "test40Field@S^2sfds2ID", "requestorName": "test40Field@S^2sfds2Name" }, "acceptVersions": "3DS1,3DS2", "channel": "PAYER_BROWSER", "purpose": "PAYMENT_TRANSACTION", "redirect": { "customizedHtml": { "3ds2": { "methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==", "methodUrl": "" } }, "html": "
\" target=\"methodFrame\">
" }, "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" } ``` ## Step 2: Authenticate payer {#step-2-authenticate-payer} 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. Warning: Use the same API version for the AUTHENTICATE PAYER request as you used in the INITIATE AUTHENTICATION request. ### Authenticate Payer request {#authenticate-payer-request} 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 preceding ***INITIATE AUTHENTICATION*** 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 3-D Secure authentications support IPv4 and IPv6 addresses from the API version 79. IPv6 is only used in the EMV 3-D Secure 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 | Optional | Billing address of the payer. It is recommended that you include this in your request whenever available. | | `shipping.address` object | Optional | Shipping address of the payer. It is recommended that you include this in your request whenever available. | | `customer` object | Optional | Payer's details. It is recommended that you include this in your request whenever available. | ### Authenticate Payer response {#authenticate-payer-response} The fields returned in the AUTHENTICATE PAYER response depend on the following: * Frictionless or challenge flow. * How the authentication request is initiated (`authentication.channel`). * The authentication mechanism for the request, session or certificate, or password. 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](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md). For fields returned for a certificate OR password authenticated request, see [Response Fields for a Certificate/Password-authenticated Request](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#response-fields-for-a-certificatepassword-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 EMV 3-D Secure transaction filtering rules configured by you or your PSP: * DO_NOT_PROCEED: Do not proceed with this card as authentication is declined or unavailable. However, you can proceed to payment without the EMV 3-D Secure data, or you can offer the payer the option to try another payment method. * PROCEED: You can proceed to complete the authentication process, also known as the challenge flow, or proceed to complete the payment, also known as the frictionless flow. * DO_NOT_PROCEED_ABANDON_ORDER: Do not submit the same request again. The payment service provider, scheme or issuer requires you to abandon the order. This recommendation is applicable from API version 70 and later. * RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS: Ask the payer for alternative payment details. For example, a new card or another payment method, and resubmit the request with the new details. Do not resubmit the same request. This recommendation is applicable from API version 70 and later. * `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: ```js div.innerHTML = response.authentication.redirect.html; eval(document.getElementById('authenticate-payer-script').text); ``` Warning: If the gateway recommends you not to proceed, inserting the content of this field into your webpage executes no functionality. The gateway recommends you to proceed: * If the ACS has selected a frictionless flow for the payer, it redirects the payer's browser back to your website, and you can proceed to step 3 to submit a subsequent payment to the gateway. The gateway obtains the authentication data related to the payment and ensures that payments are processed only if all the EMV 3-D Secure transaction filtering rules, configured by you or your PSP, have passed. * If the ACS has selected a challenge flow for the payer, redirect the payer to the ACS using the `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. Do 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 that the response is successful. ### Response fields for a Certificate or Password-authenticated request {#response-fields-for-a-certificate-or-password-authenticated-request} The following table lists the AUTHENTICATE PAYER response fields returned for a certificate or 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](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md#frequently-asked-questions). Warning: The fields marked with \* are returned based on the used EMV 3-D Secure version and flow from frictionless or challenge. For example, `authentication.3ds.authenticationToken` is not provided if a frictionless flow is used. #### Response Fields for a Certificate or Password-authenticated Request {#response-fields-for-a-certificate-or-password-authenticated-request-1} | 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` | \* | ### Authenticate Payer response fields {#authenticate-payer-response-fields} The fields returned in the Authentication Payer response depend on: * The flow is in effect, that is, frictionless vs challenge. * How the authentication request was initiated (**authentication.channel**) * The authentication mechanism for the request, such as a session or certificate or password. The following fields are returned for a certificate or password authenticated request. 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 Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/secure-int-pw-cert/index.md#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.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` | \* | Warning: `*` Where applicable, based on the EMV 3-D Secure version and flow, such as frictionless versus challenge, are in effect. ### Authenticate Payer request and response example {#authenticate-payer-request-and-response-example} | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 | [Click here to download Postman Collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api) - the path to this operation is **/Security and Fraud Prevention/3D Secure Authentication/Frictionless Flow/4. AUTHENTICATE PAYER** ```json { "apiOperation": "AUTHENTICATE_PAYER", "sourceOfFunds": { "provided": { "card": { "number": "{{fpan}}", "expiry": { "month": "{{expMonth}}", "year": "{{expYear}}" } } } }, "order": { "amount": "100", "currency": "{{currency}}" }, "authentication": { "redirectResponseUrl": "https://{{host}}/api/documentation/integrationGuidelines/index.html" }, "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" } } ``` ```json { "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.2.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": "", "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9" } }, "domainName": "", "html": "
\" target=\"challengeFrame\">
" }, "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" } ``` ## Step 3: Use the authentication results in a payment {#step-3-use-the-authentication-results-in-a-payment} When the result of the AUTHENTICATE PAYER operation indicates that you can proceed with the payment `response.gatewayRecommendation=PROCEED`, you can initiate an [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) 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. ### PAY request and response example {#pay-request-and-response-example} | HTTP Method | URL | |-------------|--------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/merchant/\/order/\/transaction/\ | ```json { "apiOperation": "PAY", "authentication": { "transactionId": "" }, "order": { "amount": "100", "currency": "AUD", "reference": "" }, "sourceOfFunds": { "provided": { "card": { "number": "", "expiry": { "month": "1", "year": "39" } } }, "type": "CARD" }, "transaction": { "reference": "" } } ``` ```json { "authentication": { "3ds": { "acsEci": "02", "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId": "39c25b96-7bc3-4586-bee8-056479fed3af" }, "3ds2": { "dsTransactionId": "39c25b96-7bc3-4586-bee8-056479fed3af", "protocolVersion": "2.2.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": "", "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": "", "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" } ``` ## Frequently asked questions {#frequently-asked-questions} 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. * Client-side API: First establish the authentication channel where your merchant server must communicate with the gateway server to for create the session on the gateway. Once the session is created, you can use it to authenticate all the subsequent API operations needed for managing the EMV 3-D Secure integration flows directly from the browser using the [EMV 3-D Secure JavaScript API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md) or using your own library. * Server-side API: Perform all the operations needed for managing the EMV 3-D Secure integration flows directly from your merchant server to the gateway server. You can support all authentication transaction modes through the Payer Authentication API. * In Authentication Only mode, use the INITIATE AUTHENTICATION and AUTHENTICATE PAYER operations.Authentication Only: Perform Initiate Authentication and Authenticate Payer. * In Authentication and payment transaction mode, use the INITIATE AUTHENTICATION, AUTHENTICATE PAYER, and AUTHORIZE/PAY operations. * In pre-authenticated payment transaction mode, use the AUTHORIZE/PAY operations using the authentication details from an external provider. For more information about EMV 3-D Secure general FAQs, see [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs).