❗️

Beta version

The 3RI endpoints are in beta version and might be changed over time. Hence, there is also no API specification yet. Please follow the code snippets in this guide to build your 3RI request.

We are working on adding 3RI test scenarios to our 3D simulator on sandbox. Until then testing needs to be conducted directly on production environment.

Introduction

3DS Requestor Initiated (3RI) or Merchant-initiated authentications is a new function that was introduced as part of the EMV 3DS 2.1 specification and was further extended in EMV 3DS 2.2. It allows merchants to generate the necessary authentication data for authorization without the cardholder being directly involved, by referencing details from the initial customer-initiated authentication. Using 3RI can provide a liability shift, and may increase authorization rates for merchant-initiated transactions.

This new functionality can be used to enable a variety of payment use cases, for example:

• Use cases where multiple CAVVs associated with one single cardholder authentication may be
  required: e.g., multi-party travel bookings, multiple authorization associated with split
  shipments
• Use cases where it is required to extend liability protection beyond the validity date of an
  initial CAVV such as for shipments delayed by more than 90 days

📘

3RI support

Support for 3RI authentications depends on the card- and issuer country.

Use-cases

🚧

Supported use-cases

Currently only the multi-party commerce / Agent payment with multiple merchants use-case is supported.
Please reach out to us if you need to cover other 3RI related use-cases.

Multi-party commerce / Agent payment with multiple merchants

This use case allows multiple parties to process multiple authorizations from a single customer-initiated authentication. The merchant who performed the initial authentication (ie. the Agent) must submit separate 3RI requests for each additional merchant involved in fulfilling the order.

Example

A cardholder has booked on a travel website (Booking Agent) three items payable to
each individual travel suppliers (merchant 1, 2 and 3 in the authorization system). The Travel
website is not collecting any funds but only authenticating on behalf of the 3 travel suppliers:

• a flight for EUR 170 payable to the airline (supplier/merchant 1) at booking
• a hotel for which no deposit is due at time of booking (card details taken by hotel
  (supplier/merchant 2) in case of a No Show payment being required) and
• a car rental for which a deposit of EUR 50 is due to the rental company (seller/merchant 3) at time
  of booking

In this example, the booking agent performs an authentication about the full amount of 220 EUR. Following the initial authentication the booking agents must do three 3RI requests with the specific amount per supplier to obtain separat authentication data for each supplier.

Implementation guide:

1. Initial customer initiated 3D request

Start with authenticating the full amount while the cardholder is in session. Please refer to one of our existing 3D implementations for the initial 3D request.

📘

Enforce challenge

It's recommended to enforce a challenge in the customer initiated 3D request by passing "threeDSRequestorChallengeInd": "04"to increase the probability of a successful 3RI authentication.

2. Merchant-initiated 3DS (3RI)

To request new authentication values, use the transactionId from the response of the previous customer initiated 3D request and call the multipleAuthentication endpoint. The amount must not exceed the total amount sent in the initial request. The request can be repeated as many times as needed but only until the total amount limit is reached.

Sample request/response

curl -L -X POST 'https://api.datatrans.com/v1/transactions/3RI/multipleAuthentication/240929143430089264' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/json' \
--data-raw '{
    "refno": "3RItest",
    "currency": "EUR",
    "amount": 500
}'

{
    "transactionId": "241682106922344246",
    "3D": {
        "eci": "05",
        "xid": "213f3d94-7328-4f84-88de-ba1c761d4135",
        "threeDSTransactionId": "edeba639-2e2a-4d21-99b6-bc605a7d20e8",
        "cavv": "AJklkhCBHgkslKKKAH0l4MXdQAAAAA=",
        "threeDSVersion": "2.2.0",
        "directoryResponse": "Y",
        "authenticationResponse": "Y"
    }
}

Forward the new authentication data returned in the response for any subsequent authorisation to your payment provider.
Alternatively call the transaction status endpoint to access the new authentication values.