Reach Checkout API Changes for 3D Secure v2 (3DS2) along with information on how to integrate and test the 3DS changes.

Possible 3DS2 flows

Challenge

The /checkout or /openContract endpoints can trigger a new Action of Challenge. You can use this URL to embed a 3D Secure v2 cardholder challenge within an iframe. When a /checkout or /openContract request returns a Challenge response and Strong Customer Authentication (SCA) is needed, the cardholder will engage with their bank interface presented in the iframe. The challenge() method provided by the Reach Checkout API SDK facilitates the display and management of this challenge. For full details, see the reach-sdk-checkout-web.

👍

Frictionless flow

Note that SCA is not always required in the case of a Challenge result, for example if the transaction is deemed to be low risk by the issuing bank. In this case, the challenge() method will call back with a result without displaying any iframe content. This is called the "frictionless" flow.

Challenge redirect Ooption

When a Challenge action is issued, it includes a Redirect action. Redirecting the browser to the specified URL will display the iframe within a web page hosted by Reach. While this offers a straightforward interim solution, integrating directly with the Challenge action is recommended for optimal user experience.

Fallback to 3D Secure v1

When SCA is required for a card not enrolled in 3DS2, the response returns a Redirect action. Using the Reach API, you can manage this in the same way as existing payment methods that require external authentication, such as PayPal.

Contract payments

Cardholder-initiated orders using a ContractId are subject to SCA, so the response may still return an Action of Redirect or Challenge.

Merchant-initiated orders using a ContractId, such as instalment payments, are not subject to SCA. Use the ViaAgent flag to identify these orders.

AuthenticationRequired error

Although ViaAgent orders are out of scope for SCA according to PSD2, it is possible that some issuing banks will not respect this and demand authentication. In this case, the response returns an AuthenticationRequired error. The merchant should contact the shopper and request they complete the payment using a cardholder-initiated order.

Testing 3DS2

Step 1. Ask Reach to enable 3DS2 for your account

Ask Reach to turn on 3DS2 for your merchant account. Reach will provide the configured currency/country/payment method combinations for 3DS2 testing.

Step 2. Update your code by sending API requests to support 3DS2

1. Include a Return URL in /checkout, /openContract and /authorize requests for card payments as well.

🚧

Important

A Return URL in the initial request is required to enable 3DS authentication.

2. Handle the possible Action responses that can be returned now for card transactions
   1. Display challenge using the Reach Checkout Web SDK on the frontend.
   2. Redirect

👍

The Checkout Web SDK is a JavaScript:

• Creates an iframe to interact with the issuing bank using the challenge URL.
• Calls the provided callback function with the final result.

Full full details, see the reach-sdk-checkout-web.

3. Test the 3DS2 flow

Challenge

To trigger a Challenge, use these test cards:

Use password: password to authenticate successfully

Frictionless

To trigger the Frictionless flow use EUR 120.02 as the total consumer amount in the /checkout or /authorize request.

Fallback to 3DS1

To trigger the SCA flow that requires a redirect for a card that is not enrolled in 3DS2, use this test card:

Use username: user and password: password to authenticate successfully

Sample

{
    "MerchantId": "e78e8cd0-24b8-4b0c-a922-87a1d8cc61c3",
    "ReferenceId": "1553817109050",
    "PaymentMethod": "VISA",
    "ConsumerCurrency": "EUR",
    "Capture": true,
    "Items": [{
        "Description": "Frying Pan",
        "ConsumerPrice": 100,
        "Quantity": 1,
        "Sku": "4383471583721"
    }],
    "Consumer": {
        "Name": "John Doe",
        "Email": "[email protected]",
        "Phone": "1234567890",
        "Address": "123 Any Street",
        "City": "Somewhere",
        "State": "AB",
        "PostalCode": "12345",
        "Country": "DE"
    },
    "DeviceFingerprint": "a598d668-f75d-4046-8e2f-ca0f6825ede0",
    "Return": "https://checkout-sandbox.gointerpay.net/return.php"
}

{
    "OrderId": "37b4194d-45a5-43d6-8cd1-ce7b1ef19f52",
    "UnderReview": false,
    "Expiry": "2019-04-07T23:52:47Z",
    "Authorized": false,
    "Completed": false,
    "Captured": false,
    "Action": {
        "Challenge": "https://sandbox.withreach.com/challenge/da68a9c2-1e26-4054-8543-27666faedfdd",
        "Redirect": "https://sandbox.withreach.com/renderChallenge/da68a9c2-1e26-4054-8543-27666faedfdd"
    }
}

window.rch.challenge("https://sandbox.withreach.com/challenge/da68a9c2-1e26-4054-8543-27666faedfdd", 1, document.getElementById("container"),  callbackFunction);

$ Cardholder challenge (sandbox)

{ "authorized": true }

Optional fields

👍

Increase the likelihood of frictionless flow

These optional fields can be sent along with the API request to increase the chance of a frictionless flow. It will be up to the bank to choose to use these fields when evaluating a transaction.

Detailed information can be found in the API Specification Guide.

To get more information about the order, in the /create and /checkout calls, these fields were added:
Items object

• PreorderDate​
• ​Reorder​
• GiftCard​​

Shipping object

• ​Timeframe​

In the Consumer object, a ConsumerProfile object was added with these fields:

• ConsumerProfileId (formerly Consumer.MerchantProfileId)
• OpenDate
• LastChange
• LastPasswordChange
• Purchases6Months
• AddCardAttempts24Hours
• Transactions24Hours
• Transactions1Year
• HadSuspiciousActivity

In the Consignee object these fields were added:

• ​AddedDate​ ​
• VerifiedAddress​

Additional information

• Enabling and implementing 3DS2 for PSD2 will also enable the 3DS2 flow for Maestro.
• The ContractId is now also returned in the challenge callback if a contract was opened with the authorization.

Credit Cards 3D Secure

3D Secure is a technical standard created by Visa and MasterCard to further secure CNP (Card-holder Not Present) transactions over the Internet.

3D Secure protects the shopper's credit card against fraud when shopping online. Shoppers validate transactions made over the internet through use of an additional password during the online purchase journey.

3D Secure also creates a liability shift for the merchant, meaning that the merchant is no longer liable for certain 3D Secure-related chargebacks.

Credit card payment flow

Technical considerations

• Similar to other card payments, the shopper will enter the card details on the merchant's site. However, after clicking "buy" or "purchase", the shopper will be directed to a 3D Secure login/authentication page as indicated by Reach. Once that interaction has completed, the shopper will be redirected back to the merchant's "Return" URL. The flow in the API is identical to that of PayPal.
• Although this is a card payment, authentication is required, thus an "Action" block containing a URL will be returned to the merchant, which must cause the shopper to be redirected. Once 3D Secure has completed, the shopper is directed to the merchant's "Return" URL. A notification of authorization will also be sent, and may arrive before or after the "Return" URL is fetched.
• Fingerprint is required for this payment method.
• This method is only available for Maestro and for local India processing.

FAQ

• 3D Secure is available for only certain required products and regions.
• Maestro is a debit card issued on the MasterCard network which requires 3D Secure authentication for all non-recurring transactions.
• Local India credit card processing requires 3D Secure authentication.

Best practices

• For anyone in retail, we always recommend that you do not ship before capture is complete.

Testing

• Testing is available through the Reach sandbox for the relevant products and markets.
  • For testing local India credit cards with 3DS in sandbox, the cardholder name needs to be specified as “PEND” to trigger the 3DS interaction.

Related information

• https://www.pymnts.com/news/security-and-risk/2017/3d-secure-2-0-psd2-payments-protocol-deadline/