Gateway Integration for PSD2 SCA Compliance and Exemptions
This page describes the gateway Authentication API integration effort required to support PSD2 SCA compliance and exemptions for payments. Before you proceed to build your integration, it is recommended that you familiarize yourself with PSD2 SCA Compliance and Exemptions.
Prerequisites
To comply with PSD2 SCA Exemptions requirements, you must add 3-D Secure to your integration.
To use the PSD2 SCA exemptions functionality through the gateway:
- Your merchant profile on the gateway must be enabled and configured for the PSD2 exemptions you want to use by paymentServiceProvider.
- You must not configure any 3-D Secure Transaction Filtering rules.
- You must have an integration to the gateway's Authentication API.
Submit as much payer and transaction information as possible when initiating the authentication. This raises the probability of an exemption that the issuer grants or applies. - You must integrate with webServicesIntegration version 57 or later.
Supported PSD2 SCA Exemptions
The gateway currently has support for the following exemptions:
- Low Risk
- Low Value
- Trusted Beneficiaries
- Recurring Payments
- Secure Corporate Payments
- Merchant Initiated
- Authentication Outage
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 either presents the payer with the EMV 3-D Secure challenge or applies an issuer exemption where the payer experiences a frictionless checkout flow. In both cases, the response contains the required authentication details, 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 EMV 3-D Secure is available for the card, that is, authentication.version with value 3DS2, 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 following cases listed:
- EMV 3-D Secure is available for the card, that is, the Initiate Authentication response returned
authentication.versionwith value 3DS2.- If EMV 3-D Secure is available, the gateway requests the exemption during the authentication.
- Your acquirer supports PSD2 exemptions. If the acquirer does not support exemptions, the gateway automatically requests the authentication without asking for an exemption.
- The issuer supports PSD2 exemptions for authentications. If the issuer does not support PSD2 exemptions, the gateway bypasses the authentication and advises you to proceed to the payment. The gateway automatically requests 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://paymentsvcs.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 gateway processes the request as if you did not request an exemption. The issuer may:
- grant the exemption you have requested,
- apply for an issuer exemption, or
- deny the exemption you have requested and not apply for 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 is subsequently be used to process the payment) does not have support for PSD2 exemptions, the gateway processes the authentication as if no exemption were requested.
Merchant-initiated payments exemption |
| 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 proceeds without performing EMV 3-D Secure.
|
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).
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 automatically adds the EMV 3-D Secure 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://paymentsvcs.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 gateway rejects the request. Contact paymentServiceProvider 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 exempted from the PSD2 SCA mandate and proceeds without any authentication details. If the transaction is successful, the response contains:
|
| Issuer Applies Issuer Exemption | If the issuer applies an issuer exemption, the payment is exempted from the PSD2 SCA mandate and proceeds without any authentication details. If the transaction is successful, the response contains:
|
| 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 rejects the transaction.
The response code returned by the issuer indicates that the transaction is rejected, because SCA under the PSD2 mandate is required. The Authorize or Pay response contains:
|
| Acquirer Does Not have Support for PSD2 Exemptions | If your acquirer does not have support for PSD2 exemptions, the gateway processes 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 processes 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 exempted from the PSD2 SCA mandate and proceeds without any authentication details. If the transaction is successful, the response contains:
|
| 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 rejects the transaction. The issuer returns the response code that indicates that the transaction is rejected, because SCA under the PSD2 mandate is required. The Authorize or Pay response contains:
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.
|
Trusted beneficiaries exemption
Adding a merchant to trusted list
You can ask the issuer to offer the payer to add you to their trusted list (for the card) by adding authentication.challengePreference=REQUEST_WHITELISTING (up to API v69) or REQUEST_TRUSTED_MERCHANT_LISTING from API v70 and later in the Authenticate Payer request.
You can request this either:
- when you submit a payment authentication (Initiate Authentication request contains
authentication.purpose=PAYMENT_TRANSACTION) or - when you submit a non-payment authentication to add or update the payer's card details (Initiate Authentication request contains
authentication.purpose=ADD_CARDorMAINTAIN_CARD).
If a request for a payment authentication with authentication.challengePreference=REQUEST_WHITELISTING or REQUEST_TRUSTED_MERCHANT_LISTING also contains the authentication.psd2.exemption field, the gateway ignores the authentication.psd2.exemption field.
Where the payer has already agreed to add you to their trusted list, the Authenticate Payer response contains authentication.psd2.whitelistStatus=WHITELISTED (in API version up to 69) or authentication.psd2.trustedMerchantStatus=ON_LIST (in API version 70 and later). Otherwise, in cases, where the issuer does not support trusted beneficiaries, the Authenticate Payer response contains authentication.psd2.whitelistStatus=NOT_WHITELISTED (in API version up to 69) or authentication.psd2.trustedMerchantStatus=NOT_ON_LIST (in API version 70 and later).
Where the challenge is required to be added to trusted list, the Authenticate Payer response contains authentication.3ds2.transactionStatus=C. Complete the challenge following the 3DS integration guide.
Where payer successfully completed the challenge and added you to the trusted list, the Retrieve Transaction response contains authentication.psd2.whitelistStatus=WHITELISTED (in API version up to 69) or authentication.psd2.trustedMerchantStatus=ON_LIST (in API version 70 and later).
Claiming a trusted merchant exemption when submitting a payment payer authentication for a merchant added to trusted list
You need to keep track of the fact that the payer has added you to the trusted list so you can request the trusted merchant exemption on any subsequent payment authentication for this payer.
Request the application of the trusted merchant exemption
- When you submit a payment authentication (Initiate Authentication request contains
authentication.purpose=PAYMENT_TRANSACTION) - By adding
authentication.psd2.exemption=WHITELISTED_MERCHANT(in API version up to 69) or TRUSTED_MERCHANT(in API version 70 and later)to the Authenticate Payer request.
The issuer validates that the payer has added you to the trusted list 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.
Claiming a trusted merchant exemption when submitting a payment after a payment payer authentication
If the payer has added you to the trusted list, and you proceed to the payment by submitting an Authorize or Pay request without authentication.psd2.exemption referencing authentication.transactionId from the preceding section, the gateway automatically adds the trusted merchant exemption to the transaction request submitted to the issuer and the exemption granted outcome details.
Claiming a trusted exemption when submitting a payment without authentication
If the payer has added you to the trusted list, and you proceed to the payment by submitting an Authorize or Pay request without authentication.psd2.exemption=WHITELISTED_MERCHANT (in API version up to 69) or TRUSTED_MERCHANT (in API version 70 and later) without authenticating the payer, the issuer may approve or reject the transaction request. In case of rejection to proceed with the payment, you then must perform payer authentication and resubmit the payment request with authentication details.
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.expiryDateagreement.recurring.daysBetweenPaymentsup to API v60 oragreement.minimumDaysBetweenPaymentsfrom API v61 and lateragreement.amountVariability=FIXED
If the authentication was successful, submit an Authorize or Pay request on the same order with:
authentication.transactionIdreferencing the authentication transaction or submitting EMV 3-D Secure 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 EMV 3-D Secure 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
Authentication outage exemption
Authentication outage is a PSD2 exemption, which can be submitted when the authentication is not possible due to a technical outage.
The"May Submit PSD2 exemptions for Authentication outage" is a new privilege which is required for merchants to submit the Authentication outage exemption.
- You must integrate with DirectAPI version 85 or later.
- Authentication outage exemption's support is provided for Mastercard and Visa cards.
This exemption can not be submitted for the Recurring or Merchant-Initiated transactions.
The following table lists the various error codes and their results.
order.status "AUTHENTICATION_UNAVAILABLE", you can submit Authentication outage exemption in the subsequent Authorize or Pay request.
| Error Code | WS API Authenticate Payer Response
|
Result |
|---|---|---|
| 5001 | AUTHENTICATION_UNAVAILABLE |
FAILURE |
| 5002 | AUTHENTICATION_UNAVAILABLE |
FAILURE |
| 5100 | AUTHENTICATION_UNAVAILABLE |
FAILURE |
The following table lists the various recommended error scenarios, where the Authentication outage exemption can be submitted on the Authorize or Pay and Update Session WS API operations.
| Scenario | Description |
|---|---|
| The issuer does not grant acquirer an exemption | If the issuer does not grant the exemption that you have requested and does not apply an issuer exemption, the issuer rejects the transaction. The issuer’s response code indicates that the transaction is rejected.
The Authorize or Pay response contains:
|
| The issuer grants acquirer an exemption | The issuer grants the exemption that you have requested.
The Authorize or Pay response contains:
|
| PSD2 exemptions submitted for the Merchant-Initiated transaction | Authentication outage exemption cannot be submitted for the Merchant-Initiated transaction, the gateway processes the payment as if NONE exemptions are requested.
Request Payload
Response Payload
|
| PSD2 exemptions submitted for the Recurring transaction | Authentication outage exemption cannot be submitted for the Recurring transactions, the gateway processes the payment as if NONE exemptions are requested.
Request Payload
Response Payload
|
| PSD2 exemptions not supported for a scheme | Authentication outage exemption's support is provided for Mastercard and Visa cards.
If the gateway does not have support to request PSD2 exemptions for a scheme then the gateway processes the payment as if NONE exemptions are requested.
|
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 that 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 3-D Secure 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 EMV 3-D Secure 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 processes the authentication as if no exemption were requested. Note that paymentServiceProvider must configure your merchant profile accordingly for this to work.
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 proceeds without performing EMV 3-D Secure. The response does not contain any EMV 3-D Secure details (indicating, that EMV 3-D Secure was not performed). In this case, submit your payment request including the exemption. |
Payer authentication is performed outside the gateway
If you have performed EMV 3-D Secure 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. - The granted exemption in field authentication.psd2.exemption.
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 you can use 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 results 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 issuer declines the payment because SCA is required, perform the following:
- Submit an Authorize or Pay request with:
sourceOfFunds.provided.card.number=5506900140100503 (Mastercard), 4532249999994628 (Visa)
- This results 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 issuer rejects the payment because it is not PSD2 SCA compliant?
When an order has a payment that the issuer rejects due to noncompliance with PSD2 SCA, the gateway ignores the exemption specified in the session. Hence, it is not required that you remove the exemption from the session before performing the EMV 3-D Secure authentication for the order and resubmit the payment.
How can I search and view PSD2 exemption details for orders and transactions in merchantUI?
When searching for an order or transaction in merchantUI through 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 is requested or applied.
The authentication status of the order is displayed on the Order and Transaction Details page in merchantUI in the field "Payer Authentication Status" in the "Payer Authentication Details" section. The field has the value "Authentication Exempt" if an exemption is requested or applied to the order.
The authentication status of the transaction is displayed on the Order and Transaction Details page in merchantUI in the section "Transactions". Select "View" for the transaction you want to view. The field 'Payer Authentication - Authentication Status' have the value 'Authentication Exempt' if an exemption is requested or applied to the transaction.