Authentication API Integration for PSD2 SCA
This page describes the integration effort to support PSD2 SCA compliance and exemptions for an Authentication API integration. Before you proceed to build your integration, it is recommended that you familiarize yourself with PSD2 SCA Compliance and Exemptions.
Supported exemptions
The gateway currently has support for the following exemptions:
- Low Risk
- Low Value
- Whitelisting
- Recurring Payments
- Secure Corporate Payments
Prerequisites
To comply with PSD2 SCA requirements, you need to integrate with the gateway for 3-D Secure Authentication.
To use the PSD2 SCA exemptions functionality via the gateway:
- Your merchant profile on the gateway must be enabled and configured for the PSD2 exemptions you want to use by your payment service provider.
- You must not configure any 3-D Secure Transaction Filtering rules.
- You must have an integration to the gateway's Authentication API.
You should submit as much payer and transaction information as possible when initiating the authentication. This will raise the probability of an exemption being granted or applied by the issuer. - You must integrate with API version 57 or above.
Requesting payer authentication
You can submit the authentication request without claiming an exemption. In this case, you do not need to make any changes to your integration with the gateway's Authentication API.
If PSD2 SCA applies to the transaction, the issuer will either present the payer with the 3DS challenge or apply an issuer exemption where the payer will experience a frictionless checkout flow. In both cases, the required authentication details are contained in the response, and you can proceed to the payment in the standard way.
Claiming an exemption when requesting payer authentication
If the Initiate Authentication response indicates that 3DS is available for the card, that is, authentication.version with value 3DS2 or 3DS1, you can claim an exemption when submitting the Authenticate Payer request by adding the field authentication.psd2.exemption with one of the following values:
- LOW_RISK
- LOW_VALUE_PAYMENT
- SECURE_CORPORATE_PAYMENT
authentication.challengePreference=NO_CHALLENGEYou can claim an exemption for all the cases listed below:
- 3DS2 or 3DS1 are available for the card, that is, the Initiate Authentication response returned
authentication.versionwith value 3DS2 or 3DS1.- If 3DS2 is available, the gateway will request the exemption during the authentication.
- If 3DS1 is available, the gateway will bypass the authentication and advise you to proceed to the payment. The gateway will automatically request the exemption when submitting the payment for processing to the acquirer.
- Your acquirer supports PSD2 exemptions. If the acquirer does not support exemptions, the gateway will automatically request the authentication without asking for an exemption.
- The issuer supports PSD2 exemptions for authentications. If the issuer does not support PSD2 exemptions, the gateway will bypass the authentication and advise you to proceed to the payment. The gateway will automatically request the exemption when submitting the payment for processing to the acquirer.
Example authenticate payer request
A sample Authenticate Payer request in REST showing how to request for a Low-Risk acquirer exemption.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation":"AUTHENTICATE_PAYER",
"authentication":{
"challengePreference":"NO_CHALLENGE",
"redirectResponseUrl":"<your_host_name_and_path>",
"psd2":{
"exemption":"LOW_RISK"
}
},
"correlationId":"123456789012345678",
"device":{
"browser":"MOZILLA",
"browserDetails":{
"3DSecureChallengeWindowSize":"FULL_SCREEN",
"acceptHeaders":"application/json",
"colorDepth":24,
"javaEnabled":true,
"language":"en-US",
"screenHeight":640,
"screenWidth":480,
"timeZone":273
},
"ipAddress":"123.4.5.6"
},
"order":{
"amount":"100",
"currency":"EUR"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"5506900140100107",
"expiry":{
"month":"1",
"year":"39"
}
}
}
}
}
Example Authenticate Payer Response
A sample Authenticate Payer response showing Low Risk acquirer exemption being granted by the issuer.
{
"authentication":{
"3ds":{
"acsEci":"06",
"authenticationToken":"kNyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"088d2f19-ecef-47c6-ae27-6db0a1e09278"
},
"3ds2":{
"acsTransactionId":"10c1b4e3-fadc-472b-88a3-73df73722f1e",
"directoryServerId":"A999999999",
"dsTransactionId":"088d2f19-ecef-47c6-ae27-6db0a1e09278",
"methodSupported":"NOT_SUPPORTED",
"protocolVersion":"2.2.0",
"requestorId":"<your_requestor_ID>",
"requestorName":"<your_requestor_name>",
"statusReasonCode":"81",
"transactionStatus":"N"
},
"payerInteraction":"NOT_REQUIRED",
"psd2":{
"exemption":"LOW_RISK"
},
"redirect":{
"customized":{
"3DS":{
"acsUrl":"<ACS_host_and path>",
"cReq":"e30="
}
}
},
"redirectHtml":"<div id=\"threedsFrictionLessRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"challengeFrame\" name=\"challengeFrame\"> </iframe> <form id=\"threedsFrictionLessRedirectForm\" method=\"POST\" action=\"<your host and path>\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"order.id\" value=\"27bc3847-3a16-4ad7-8566-6b1be559b337\" /> <input type=\"hidden\" name=\"transaction.id\" value=\"1\" /> <input type=\"hidden\" name=\"response.gatewayRecommendation\" value=\"PROCEED\" /> <input type=\"hidden\" name=\"result\" value=\"SUCCESS\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsFrictionLessRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version":"3DS2"
},
"correlationId":"123456789012345678",
"device":{
"browser":"MOZILLA",
"ipAddress":"123.4.5.6"
},
"lineOfBusiness":"Online",
"merchant":"<your_merchant_ID>",
"order":{
"amount":100,
"authenticationStatus":"AUTHENTICATION_EXEMPT",
"creationTime":"2020-06-01T05:32:49.982Z",
"currency":"EUR",
"id":"27bc3847-3a16-4ad7-8566-6b1be559b337",
"lastUpdatedTime":"2020-07-22T08:44:28.148Z",
"merchantCategoryCode":"1234",
"status":"AUTHENTICATION_NOT_NEEDED",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0,
"valueTransfer":{
"accountType":"NOT_A_TRANSFER"
}
},
"response":{
"gatewayCode":"APPROVED",
"gatewayRecommendation":"PROCEED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"expiry":{
"month":"1",
"year":"39"
},
"number":"5506900140100107",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2020-07-22T08:44:28.148Z",
"timeOfRecord":"2020-06-01T05:32:49.982Z",
"transaction":{
"acquirer":{
"merchantId":"9808"
},
"amount":100,
"authenticationStatus":"AUTHENTICATION_EXEMPT",
"currency":"EUR",
"id":"1",
"type":"AUTHENTICATION"
},
"version":"57"
}
If you are not enabled for the requested exemption, the request is processed as if you did not request an exemption. The issuer may:
- grant the exemption you have requested,
- apply an issuer exemption, or
- deny the exemption you have requested and not apply an issuer exemption.
Special handling is applied if your acquirer or the scheme does not support exemptions.
| Scenario | Description |
|---|---|
| Issuer Grants Acquirer Exemption | If the issuer grants the exemption that you have requested:
|
| Issuer Applies Issuer Exemption | If the issuer applies an issuer exemption:
|
| Issuer Does not Grant or Apply an Exemption | If the issuer did not grant the exemption that you have requested and did not apply an issuer exemption:
|
| Acquirer Does Not have Support for PSD2 Exemptions | If the acquirer (that will subsequently be used to process the payment) does not have support for PSD2 exemptions, the gateway will process the authentication as if no exemption were requested.
|
| PSD2 Exemptions Not Supported for this Scheme | Requesting exemptions when performing the authentication is currently only supported for Mastercard and Visa. If the gateway does not have support to request PSD2 exemptions for a scheme, the gateway will proceed without performing 3DS.
|
Proceeding with a Payment
If the response does not contain response.gatewayRecommendation=PROCEED we do not recommend that you proceed with the payment. Ask the payer for another set of payment details.
If the Authenticate Payer response indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), proceed with the payment by submitting an Authorize or Pay request. For details see Implementing a 3DS Integration using the Authentication API (Step 3).
Fallback to 3DS1
If the card does not support 3DS2, the gateway may fall back to 3DS1. In this case, where you have requested an exemption, the gateway behavior depends on the acquirer support for PSD2 exemption. See table below for details.
| Scenario | Description |
|---|---|
| Acquirer has Support for PSD2 Exemptions | The gateway will proceed without performing 3DS.
The response will not contain any 3DS details (indicating that 3DS was not performed). When you proceed with the payment, the gateway will automatically request the exemption when submitting the payment for processing with the acquirer. |
| Acquirer Does Not have Support for PSD2 Exemptions | If the acquirer (that will subsequently be used to process the payment) does not have support for PSD2 exemptions, the gateway will process the authentication as if no exemption were requested.
|
Proceeding with a payment after a successful authentication
If you have successfully performed an authentication, that is, the Authenticate Payer response contains response.gatewayRecommendation=PROCEED, proceed with the payment by submitting an Authorize or Pay request.
For details, see Implementing a 3DS Integration using the Authentication API (Step 3). The gateway will automatically add the 3DS authentication details to the transaction request submitted to the issuer.
Claiming an exemption when submitting a payment
If you did not perform an authentication, you can claim an exemption on the Authorize or Pay request. Add the field authentication.psd2.exemption to the request with one of the following values:
- LOW_RISK
- LOW_VALUE_PAYMENT
- SECURE_CORPORATE_PAYMENT
Example pay request
A sample Pay request in REST showing how to request for a Low-Risk acquirer exemption.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation":"PAY",
"authentication":{
"psd2":{
"exemption":"LOW_RISK"
}
},
"order":{
"amount":"100",
"reference":"<your_order_ID>",
"currency": "EUR",
"merchantCategoryCode": "1234"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"5506900140100107",
"expiry":{
"month":"1",
"year":"39"
}
}
},
"type":"CARD"
},
"transaction":{
"source":"INTERNET"
}
}
Example pay response
A sample Pay response where the issuer did not grant or apply an exemption and rejected the request (because SCA is required).
{
"authentication":{
"psd2":{
"exemption":"LOW_RISK"
}
},
"authorizationResponse":{
"commercialCard":"888",
"commercialCardIndicator":"3",
"financialNetworkCode":"777",
"posData":"1025104006600",
"posEntryMode":"812",
"processingCode":"003000",
"responseCode":"65",
"stan":"101123",
"transactionIdentifier":"123456789"
},
"currencyConversion":{
"uptake":"NOT_REQUIRED"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"<your_order_ID>",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_REQUIRED",
"certainty":"FINAL",
"chargeback":{
"amount":0,
"currency":"EUR"
},
"creationTime":"2020-07-24T06:49:21.703Z",
"currency":"EUR",
"id":"<your_order_ID>",
"lastUpdatedTime":"2020-07-24T06:49:22.019Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"EUR",
"reference":"f1dc3211-ea25-46af-b72d-93828f0c6964",
"status":"FAILED",
"totalAuthorizedAmount":0.00,
"totalCapturedAmount":0.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"65",
"acquirerMessage":"SCA required under PSD2",
"gatewayCode":"DECLINED",
"gatewayRecommendation":"ATTEMPT_WITH_AUTHENTICATION"
},
"result":"FAILURE",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"INTERNATIONAL CARD SERVICES BV",
"number":"510029xxxxxx2909",
"scheme":"MASTERCARD",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2020-07-24T06:49:22.019Z",
"timeOfRecord":"2020-07-24T06:49:21.813Z",
"transaction":{
"acquirer":{
"batch":20200724,
"date":"0724",
"id":"SYSTEST_ACQ_S2I",
"merchantId":"9808",
"transactionId":"123456789"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_REQUIRED",
"currency":"EUR",
"id":"<your_transaction_ID>",
"receipt":"020606101123",
"source":"INTERNET",
"stan":"101123",
"terminal":"0002",
"type":"PAY"
},
"version":"57"
}
If you are not enabled for the requested exemption, the request will be rejected by the gateway. Contact your payment service provider to ensure they have enabled you for using the PSD2 SCA exemptions functionality on all your merchant-acquirer links.
The issuer may:
- grant the exemption you have requested,
- apply an issuer exemption, or
- deny the exemption you have requested and not apply an issuer exemption.
Special handling is applied if your acquirer or the scheme does not support exemptions.
| Scenario | Description |
|---|---|
| Issuer Grants Acquirer Exemption | If the issuer grants the exemption that you have requested, the payment is exempt from the PSD2 SCA mandate and will proceed without any authentication details. If the transaction is successful, the response will contain:
|
| Issuer Applies Issuer Exemption | If the issuer applies an issuer exemption, the payment is exempt from the PSD2 SCA mandate and will proceed without any authentication details. If the transaction is successful, the response will contain:
|
| Issuer Does not Grant or Apply an Exemption | If the issuer does not grant the exemption that you have requested and does not apply an issuer exemption, the issuer will reject the transaction.
The response code returned by the issuer will indicate that the transaction was rejected, because SCA under the PSD2 mandate is required. The Authorize or Pay response will contain:
|
| Acquirer Does Not have Support for PSD2 Exemptions | If your acquirer does not have support for PSD2 exemptions, the gateway will process the payment as if no exemption were requested. |
| PSD2 Exemptions Not Supported for this Scheme | Support for exemptions is currently only supported for Mastercard and Visa. If the gateway does not have support to request PSD2 exemptions for a scheme, the gateway will process the payment as if no exemption were requested. |
Submitting a payment without claiming an exemption
If you did not perform an authentication, you can submit an Authorize or Pay request without claiming an exemption. The issuer may either apply an issuer exemption or reject the payment because it does not comply with the PSD2 SCA mandate.
| Scenario | Description |
|---|---|
| Issuer Applies Issuer Exemption | If the issuer applies an issuer exemption, the payment is exempt from the PSD2 SCA mandate and will proceed without any authentication details. If the transaction is successful, the response will contain:
|
| Issuer Does not Grant or Apply an Exemption | If you have not requested an acquirer exemption and the issuer does not apply an issuer exemption, the issuer will reject the transaction. The response code returned by the issuer will indicate that the transaction was rejected, because SCA under the PSD2 mandate is required. The Authorize or Pay response will contain:
You can proceed with the payment by performing payer authentication and resubmitting the payment request with the authentication details. To enforce payer authentication, submit an Authenticate Payer request with the authentication.challengePreference=CHALLENGE_MANDATED field.
|
Whitelisting exemption
You can ask the issuer to offer the payer to add you to their whitelist (for the card), by adding authentication.challengePreference=REQUEST_WHITELISTING to the Authenticate Payer request.
authentication.challengePreference=REQUEST_WHITELISTING also contains the authentication.psd2.exemption field, the gateway ignores the authentication.psd2.exemption field. You can request this either:
- when you submit a payment (Initiate Authentication request contains
authentication.purpose=PAYMENT_TRANSACTION) or - when you add or update the payer's card details (Initiate Authentication request contains
authentication.purpose=ADD_CARDorMAINTAIN_CARD).
Where the payer has agreed to add you to their whitelist, the Authenticate Payer response contains authentication.psd2.whitelistStatus=WHITELISTED. Otherwise, or in cases where the issuer does not support whitelisting, the Authenticate Payer response contains authentication.psd2.whitelistStatus=NOT_WHITELISTED.
You will need to keep track of the fact that the payer has whitelisted you so you can request the whitelisting exemption on any subsequent payments for this payer.
Request the application of the whitelisting exemption by adding authentication.psd2.exemption=WHITELISTED_MERCHANTto the request.
The issuer will validate that the payer has whitelisted you and either:
- grant the exemption (frictionless flow for the payer) and return authentication details for a successful authentication, or
- not grant the exemption and present the payer with the challenge flow.
If the payer has whitelisted you, and you proceed to the payment without authenticating the payer, the issuer may grant the exemption or reject the transaction request. To proceed with the payment, you then must perform payer authentication and resubmit the payment request.
Recurring payments exemption
If you have an agreement with the payer for recurring payments, that is, a subscription with a fixed amount:
- You must perform SCA when you submit the initial cardholder-initiated payment in the series.
- You must correctly identify the initial cardholder-initiated payment in the series, see cardholder-initiated transactions.
- You must correctly identify all subsequent merchant-initiated payments in the series as a merchant-initiated payment, see merchant-initiated transactions.
- You must claim a recurring payment exemption for all subsequent merchant-initiated payments in the series.
- You must submit another cardholder-initiated payment and perform SCA for this payment if the amount or the card details for the agreement change.
Cardholder-initiated Payment
For the first payment in the series or where the amount or card details have changed, authenticate the payer and submit a cardholder-initiated payment.
Submit an Initiate Authentication request with authentication.purpose=PAYMENT_TRANSACTION.
Submit an Authenticate Payer request with:
authentication.challengePreference=CHALLENGE_MANDATEDorder.amountbeing set to the fixed amount per payment in the recurring payment seriesagreement.idagreement.type=RECURRINGagreement.expiryDate(optional)agreement.recurring.daysBetweenPayments(optional)
If the authentication was successful, submit an Authorize or Pay request on the same order with:
authentication.transactionIdreferencing the authentication transaction or submitting 3DS authentication details in theauthenticationparameter grouporder.amountmatching the authenticated amountagreement.idmatching the agreement ID on the authentication transactionsourceOfFunds.provided.card.storedOnFile=TO_BE_STOREDtransaction.sourceis set to a value other thanMERCHANT
Merchant-initiated Payment
For all subsequent merchant-initiated payments in the series, you do not need to authenticate the payer. You must correctly identify the payment as a merchant-initiated payment. See merchant-initiated transactions for details.
Submit an Authorize or Pay request with:
authentication.psd2.exemption=RECURRING_PAYMENTorder.amountmatching the order amount for the authentication transactionagreement.idmatching the agreement ID on the authentication transactiontransaction.source=MERCHANTsourceOfFunds.provided.card.storedOnFile=STORED
Merchant-initiated payments exemption
If you have an agreement with the payer for merchant-initiated payments, for example recurring, installment or unscheduled payments (excluding recurring payments with a fixed amount, see section Recurring Payments Exemptions using Authentication API):
- You must perform SCA when you submit the initial cardholder-initiated payment in the series.
- You must correctly identify all subsequent merchant-initiated payments in the series as a merchant-initiated payment, see merchant-initiated transactions.
- You must claim a merchant-initiated payment exemption for all subsequent merchant-initiated payments in the series.
- You must submit another cardholder-initiated payment and perform SCA for this payment if the card details for the agreement change.
Cardholder-initiated Payment
For the first payment in the series or where the card details have changed, authenticate the payer and submit a cardholder-initiated payment.
Submit an Initiate Authentication request with authentication.purpose=PAYMENT_TRANSACTION.
Submit an Authenticate Payer request with:
authentication.challengePreference=CHALLENGE_MANDATEDagreement.id
If the authentication was successful, submit an Authorize or Pay request on the same order with:
authentication.transactionIdreferencing the authentication transaction or submitting 3DS authentication details in theauthenticationparameter groupagreement.idmatching the agreement ID on the authentication transactionagreement.typeagreement.expiryDate(optional, only applicable for recurring payments)agreement.recurring.daysBetweenPayments(optional, only applicable for recurring payments). Set to "1" for variable time interval agreements.sourceOfFunds.provided.card.storedOnFile=TO_BE_STOREDtransaction.sourceis set to a value other thanMERCHANT
Merchant-initiated Payment
For all subsequent merchant-initiated payments in the series you do not need to authenticate the payer. You must correctly identify the payment as a merchant-initiated payment. See merchant-initiated transactions for details.
Submit an Authorize or Pay request with:
authentication.psd2.exemption=MERCHANT_INITIATED_PAYMENTagreement.idmatching the agreement ID on the authentication transactiontransaction.source=MERCHANTsourceOfFunds.provided.card.storedOnFile=STORED
Using the gateway for authentication only
If the response does not contain response.gatewayRecommendation=PROCEED we do not recommend that you proceed with the payment. Ask the payer for another set of payment details.
If the Authenticate Payer response indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), submit a payment request with the details provided in the Authentication Payer response. Depending on the authentication response details, you may need to provide the following details on the payment request.
| Scenario | Description |
|---|---|
| Issuer Grants Acquirer Exemption | If the issuer grants the exemption that you have requested, the response contains transaction.authenticationStatus=AUTHENTICATION_EXEMPT. In this case, do not request an exemption on the payment request. Submit the unaltered authentication token in the payment request, as provided in the authentication.3ds.authenticationToken field.
For Payer Authentication using Protocol Version 2.2.0 for Mastercard cards, the combination of:
for Visa cards, the combination of:
Where no payment is executed at the time the payer is authenticated, merchants can perform a Verification Only. However, Mastercard have advised that they are not returning an authentication token (cryptogram) in the response for EMV 3DS requests flagged as non-payment authentications ('ADD_CARD' or 'MAINTAIN_CARD'). For Non-Payment Authentication using Protocol Version 2.2.0 for Mastercard cards, the combination of:
|
| Issuer Applies Issuer Exemption | If the issuer applied an issuer exemption the response contains transaction.authenticationStatus=AUTHENTICATION_SUCCESSFUL. In this case, do not request an exemption on the payment request.
Submit the unaltered authentication token in the payment request, as provided in the authentication.3ds.authenticationToken. field.
The request may also contain the following fields:
|
| Issuer Does not Grant or Apply an Exemption | If the issuer did not apply an exemption and the 3DS authentication was successful, the response contains transaction.authenticationStatus=AUTHENTICATION_SUCCESSFUL. In this case, do not request an exemption on the payment request.
Submit the unaltered authentication token in the payment request, as provided in the authentication.3ds.authenticationToken field.
The request may also contain the following fields:
|
| Acquirer Does Not have Support for PSD2 Exemptions | If your acquirer does not have support for PSD2 exemptions, the gateway will process the authentication as if no exemption were requested. Note that this requires your merchant profile to be configured by your payment service provider accordingly.
If the 3DS authentication was successful, the response contains transaction.authenticationStatus=AUTHENTICATION_SUCCESSFUL. In this case, do not request an exemption on the payment request.
Submit the unaltered authentication token in the payment request, as provided in the authentication.3ds.authenticationToken. field. The request may also contain the following fields:
|
| PSD2 Exemptions Not Supported for this Scheme | Requesting exemptions when performing the authentication is currently only supported for Mastercard and Visa. If the gateway does not have support to request PSD2 exemptions for a scheme, the gateway will proceed without performing 3DS. The response will not contain any 3DS details (indicating, that 3DS was not performed). In this case, submit your payment request including the exemption. |
Payer authentication performed outside the gateway
If you have performed 3DS2 payer authentication outside the gateway and received authentication details that indicate that the issuer has granted an exemption, simply provide the authentication details when submitting the Authorize or Pay request, including:
- the unaltered authentication token in field
authentication.3ds.authenticationToken - the ECI provided by the ACS in field
authentication.3ds.acsEci - the value returned in the transaction status field from the issuer's Access Control Server (ACS), in the
authentication.3ds2.transactionStatusfield - the code indicating the reason for the transaction status in the
authentication.3ds2.statusReasonCodefield - the unaltered value for the unique identifier for the 3DS2 authentication transaction as assigned by the Directory Server in the
authentication.3ds.transactionIdfield
Testing your integration
You can test your integration using your test merchant profile (your merchant ID prefixed with "TEST"). This section provides details about the test card numbers that can be used to trigger a specific response.
Payer authentication
To trigger an Authenticate Payer response indicating that the issuer granted an exemption that you have requested, perform the following:
- Submit an Authentication Payer request with:
authentication.psd2.exemptionset to one of the following:
LOW_RISKLOW_VALUE_PAYMENTSECURE_CORPORATE_PAYMENT
sourceOfFunds.provided.card.number=5506900140100107 (Mastercard), 4532249999999388 (Visa)
- This will result in an Authenticate Payer response with:
authentication.psd2.exemptionset to the value provided in the request, that is, one of the following:
LOW_RISKLOW_VALUE_PAYMENTSECURE_CORPORATE_PAYMENT
transaction.authenticationStatus=AUTHENTICATION_EXEMPTresponse.gatewayRecommendation=PROCEEDresponse.gatewayCode=APPROVEDorder.status=AUTHENTICATION_NOT_NEEDEDauthentication.3ds2.transactionStatus=N(Mastercard) orN(Visa)authentication.3ds2.statusReasonCode=81(Mastercard only)authentication.3ds2.statusReasonCode=89(Visa only)authentication.3ds.acsEci=06(Mastercard) or07(Visa)authentication.3ds.authenticationToken
- Proceed with the payment by submitting an Authorize or Pay request on this order.
Payment transaction
To trigger an Authorize or Pay response indicating that the payment was declined by the issuer because SCA is required, perform the following:
- Submit an Authorize or Pay request with:
sourceOfFunds.provided.card.number=5506900140100503 (Mastercard), 4532249999994628 (Visa)
- This will result in an Authorize or Pay response with:
authentication.psd2.exemptionset to the value provided in the request, that is, one of the following:
LOW_RISKLOW_VALUE_PAYMENTSECURE_CORPORATE_PAYMENT
result=FAILUREresponse.gatewayRecommendation=ATTEMPT_WITH_AUTHENTICATIONresponse.gatewayCode=DECLINEDorder.authenticationStatus=AUTHENTICATION_REQUIRED
FAQs
I have existing payment agreements for recurring payments or other merchant-initiated payments. Do I need to perform payer authentication for all my agreements again?
You do not need to authenticate the payer for such an agreement again. The schemes have rules for the transition period.
How do I proceed if I am using a session and the session contains an exemption, but the payment was rejected by the issuer because it is not PSD2 SCA compliant?
The gateway will ignore the exemption contained in the session when the order has a payment that has been rejected by the issuer because it is not PSD2 SCA compliant. Hence, it is not required that you remove the exemption from the session before performing the 3DS authentication for the order and re-submit the payment.
How can I search and view PSD2 exemption details for orders and transactions in Merchant Administration?
When searching for an order or transaction in Merchant Administration via the Order and Transaction Search, you can use the search term:
- "Payer Authentication Status":"Authentication Successful" to find all successfully authenticated orders
- "Payer Authentication Status":"Authentication Exempt" to find all orders where an exemption was requested or applied
The authentication status of the order is displayed on the Order and Transaction Details page in Merchant Administration in the field "Payer Authentication Status" in the "Payer Authentication Details" section. The field will have the value "Authentication Exempt" if an exemption has been requested or applied to the order.
The authentication status of the transaction is displayed on the Order and Transaction Details page in Merchant Administration in the section "Transactions". Select "View" for the transaction you want to view. Field 'Payer Authentication - Authentication Status' will have the value 'Authentication Exempt' if an exemption has been requested or applied to the transaction.