Authentication API Integration for PSD2 SCA

The gateway currently has support for the following exemptions:

• Low Risk
• Low Value
• Whitelisting
• Recurring Payments
• Secure Corporate Payments

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 tyro.
• 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 when initiating the authentication. This will raise the probability of an exemption being granted or applied by the issuer.
• You must integrate with Web Services Integration version 57 or above.

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.

If the Initiate Authentication response indicates that 3DS is available for the card, i.e., 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 

You can claim an exemption for all the cases listed below:

• 3DS2 or 3DS1 are available for the card, i.e. the Initiate Authentication response returned authentication.version with 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. 

{
   "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"
            }
         }
      }
   }
}
	

{
   "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.1.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. 

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.

If you have successfully performed an authentication, i.e., 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.

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 

{
  "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"
  }
}

{
   "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 tyro 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. 

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.

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. 

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_CARD or MAINTAIN_CARD).

Where the payer has agreed to add you to their whitelist, the Authenticate PayerAuthenticate 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 have to perform payer authentication and resubmit the payment request. 

If you have an agreement with the payer for recurring payments, i.e., 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 can 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_MANDATED
• order.amount being set to the fixed amount per payment in the recurring payment series
• agreement.id
• agreement.type=RECURRING
• agreement.expiryDate (optional) 
• agreement.recurring.daysBetweenPayments(optional) 

If the authentication was successful, submit an Authorize or Pay request on the same order with: 

• authentication.transactionId referencing the authentication transaction or submitting 3DS authentication details in the authentication parameter group
• order.amount matching the authenticated amount
• agreement.id matching the agreement ID on the authentication transaction
• sourceOfFunds.provided.card.storedOnFile=TO_BE_STORED
• transaction.source is set to a value other than MERCHANT

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_PAYMENT
• order.amount matching the order amount for the authentication transaction
• agreement.id matching the agreement ID on the authentication transaction
• transaction.source=MERCHANT
• sourceOfFunds.provided.card.storedOnFile=STORED

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_MANDATED
• agreement.id

If the authentication was successful, submit an Authorize or Pay request on the same order with: 

• authentication.transactionId referencing the authentication transaction or submitting 3DS authentication details in the authentication parameter group
• agreement.id matching the agreement ID on the authentication transaction
• agreement.type
• agreement.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_STORED
• transaction.source is set to a value other than MERCHANT

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_PAYMENT
• agreement.id matching the agreement ID on the authentication transaction
• transaction.source=MERCHANT
• sourceOfFunds.provided.card.storedOnFile=STORED

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.

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.transactionStatus field
• the code indicating the reason for the transaction status in the authentication.3ds2.statusReasonCode field
• the unaltered value for the unique identifier for the 3DS2 authentication transaction as assigned by the Directory Server in the authentication.3ds.transactionId field

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:

1. Submit an Authentication Payer request with:
   
   
   • authentication.psd2.exemption set to one of the following:
     
     • LOW_RISK
     • LOW_VALUE_PAYMENT
     • SECURE_CORPORATE_PAYMENT
   • sourceOfFunds.provided.card.number=5506900140100107 (Mastercard), 4532249999999388 (Visa)
2. This will result in an Authenticate Payer response with:
   
   
   • authentication.psd2.exemption set to the value provided in the request, i.e., one of the following:
     
     • LOW_RISK
     • LOW_VALUE_PAYMENT
     • SECURE_CORPORATE_PAYMENT
   • transaction.authenticationStatus=AUTHENTICATION_EXEMPT
   • response.gatewayRecommendation=PROCEED
   • response.gatewayCode=APPROVED
   • order.status=AUTHENTICATION_NOT_NEEDED
   • authentication.3ds2.transactionStatus=N (Mastercard) or N (Visa)
   • authentication.3ds2.statusReasonCode=81 (Mastercard only) 
   • authentication.3ds2.statusReasonCode=89 (Visa only) 
   • authentication.3ds.acsEci=06(Mastercard) or 07(Visa)
   • authentication.3ds.authenticationToken
3. 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:

1. Submit an Authorize or Pay request with:
   
   
   • sourceOfFunds.provided.card.number=5506900140100503 (Mastercard), 4532249999994628 (Visa)
2. This will result in an Authorize or Pay response with:
   
   
   • authentication.psd2.exemption set to the value provided in the request, i.e., one of the following:
     
     • LOW_RISK
     • LOW_VALUE_PAYMENT
     • SECURE_CORPORATE_PAYMENT
   • result=FAILURE
   • response.gatewayRecommendation=ATTEMPT_WITH_AUTHENTICATION
   • response.gatewayCode=DECLINED
   • order.authenticationStatus=AUTHENTICATION_REQUIRED

If you have an existing integration with the gateway using the gateway's legacy API for 3DS1, you need to upgrade to EMV 3-D Secure Authentication and then follow the integration steps described on this page. 

3DS 1 is only considered compliant with the PSD2 SCA mandate if the issuer sends a one-time password to the payer's phone when authenticating the payer, not where the issuer assigns a static password to the payer. 

As not all issuers use one-time passwords, it is not recommended to rely on 3DS1 if you are required to comply with the PSD2 SCA mandate. 

You do not need to authenticate the payer for such an agreement again. The schemes have rules for the transition period.

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's not required that you remove the exemption from the session before performing the 3DS authentication for the order and re-submit the payment.

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.