3D Secure

Merchant Initiated Authentication (3RI)

Introduction

3DS Requestor Initiated (3RI) or Merchant-initiated authentications allow merchants to generate the necessary authentication data for authorization without the customer 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.

important
Starting October 18, 2024, the reuse of CAVV will not be allowed and 3RI will be mandatory.

Use Cases

1. Recurring

This use case is useful for services that require regular payments, such as subscriptions or bill payments. After an initial transaction is authenticated by the customer, the subsequent payments can be processed by referencing the authentication details of the initial transaction.

availability
The 3RI Recurring use case is currently only supported for MasterCard.

Example: Charging first payment up-front

A customer enrolls for a $15 per month subscription plan with a merchant. The first subscription payment is charged up-front.

During checkout, a customer-initiated 3DS is performed followed by a customer-initiated transaction (CIT):

3DS: $15
CIT: $15

After 1 month, a merchant-initiated 3DS (3RI) is performed followed by a merchant-initiated transaction (MIT):

3RI:^* $15
MIT:^* $15

^* Continues every 1 month till the customer terminates the subscription.

Example: Free Trial

A customer enrolls for a $100 per quarter subscription plan with a merchant. Let us say the first two months of subscription were free.

note
Performing a Transaction for $0 will result in a validation error. Merchants must perform a Verification in this scenario.

During checkout, a customer-initiated 3DS is performed followed by a Verification:

3DS: $100
Verification: $0

After 2 months, a merchant-initiated 3DS (3RI) is performed followed by a merchant-initiated transaction (MIT):

3RI:^* $100
MIT:^* $100

^* Continues every 3 months till the customer terminates the subscription

2. Split Shipment

This use case is useful for scenarios when an order needs to be divided into multiple shipments, often due to logistical constraints. The initial customer-initiated 3DS should be authenticated for the entire amount of the order and the merchant must then initiate separate 3RI requests for each subsequent shipment.

important
Currently the same CAVV is used multiple times. However, starting October 18, 2024, performing 3RI will be mandatory.

Example

A customer purchases 3 items from an e-commerce store- Item A worth $20, Item B worth $30 and Item C worth $50 dollars. Let us say that only Item A is available at the time of checkout. Item B will be shipped after 15 days and Item C will be shipped after 30 days.

During checkout, a customer-initiated 3DS is performed for the collective amount followed by a customer-initiated transaction (CIT) for Item A:

3DS: $100 (Collective amount)
CIT: $20 (Item A)

After 15 days, a merchant-initiated 3DS (3RI) and a merchant-initiated transaction (MIT) is performed for Item B:

3RI: $30
MIT: $30 (Item B)

After 30 days, a merchant-initiated 3DS (3RI) and a merchant-initiated transaction (MIT) is performed for Item C:

3RI: $50
MIT: $50 (Item C)

Note: The aggregated amount of 3RI requests should not exceed the amount of the original customer-initiated 3DS.

3. Delayed Shipment

The delayed shipment use case allows merchants to maintain liability protection beyond 90 days. A 3RI request can be performed to generate a new CAVV, which will be valid for another 90 days.

important
Currently the same CAVV is used multiple times. However, starting October 18, 2024, performing 3RI will be mandatory.

Example

A customer purchases an item worth $250 from an online store. But it is not available and can only be shipped after 120 days. Note that this exceeds the 90 days expiry of a regular 3DS CAVV.

note
Performing a Transaction for $0 will result in a validation error. Merchants must perform a Verification in this scenario.

During checkout, a customer-initiated 3DS is performed followed by a Verification:

3DS: $250
Verification: $0

Before 90 days^*, a merchant-initiated 3DS (3RI) is performed:

3RI: $250

^* 3RI must be performed before the CAVV from customer-initiated 3DS expires

After 120 days, a merchant-initiated transaction (MIT) is performed:

MIT: $250

4. 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.

important
Currently the same CAVV is used multiple times. However, starting October 18, 2024, performing 3RI will be mandatory. The merchant who performed the customer-initiated 3DS must now submit a unique 3RI request to obtain a unique CAVV for each merchant.

Example

A customer books a package on a travel agent website for a hotel stay worth $2500 and airline tickets costing $1000. Let us say that the travel agent charges $500 as commission. The travel agent must submit a unique 3RI request and obtain a unique CAVV for each merchant.

During checkout, a customer-initiated 3DS is performed for the collective amount followed by a customer-initiated transaction (CIT) for travel agent's commision:

3DS: $4000 (Collective amount)
CIT: $500 (Travel agent's commission)

Travel agent performs a merchant-initiated 3DS (3RI) to generate a new CAVV for the Hotel:

3RI: $2500

Hotel performs a merchant-initiated transaction (MIT) by embedding the CAVV generated by the Travel Agent:

MIT: $2500 (Hotel stay)

Travel agent performs a merchant-initiated 3DS (3RI) to generate a new CAVV for the Airline:

3RI: $1000

Airline performs a merchant-initiated transaction (MIT) by embedding the CAVV generated by Travel Agent:

MIT: $1000 (Airline ticket)

Integration Steps

availability
The 3RI functionality is currently only available in Java SDK (version 3.35 or later), DotNet SDK (version 5.26.0 or later), and GraphQL.

As shown in the above examples, there are four steps. First, the customer checks out using a customer-initiated 3DS and a customer-initiated transaction (CIT). At a later time, the merchant will perform merchant-initiated 3DS (3RI) and merchant-initiated transactions (MIT).

1. Customer-initiated 3DS

As a prerequisite step for perfoming 3RI, the appropriate authenticationIndicator value must be sent during the customer-initiated 3DS lookup:

Recurring: "02"
Split Shipment: "08"
Delayed Shipment: "09"
Payment with multiple merchants: "85"

important
For the Recurring use case, the recurringFrequency, recurringEnd and purchaseDate fields must be passed in.

JavaScript

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION,
  bin: BIN_FROM_INTEGRATION,
  additionalInformation: {
    authenticationIndicator: "08"
  },
  onLookupComplete: function (data, next) {
    // use 'data' here, then call 'next()'
    next();
  }
}, function (err, response) {
  var liabilityShifted = response.liabilityShifted; // true || false
  var liabilityShiftPossible =  response.liabilityShiftPossible; // true || false
});

note
It is recommended to perform a challenge during customer-initiated 3DS by passing challengeRequested = true

2. Customer-initiated Transaction (CIT) or Verification

note
Performing a Transaction for $0 will result in a validation error. Merchants must perform a Verification in this scenario.

Customer-initiated Transaction (CIT)

3DS data can be embedded in the transaction either by passing a 3DS upgraded nonce or a authentication ID associated to the lookup.

Java

GraphQL

TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(nonceWithout3ds)
  .threeDSecureAuthenticationId(threeDSecureAuthenticationId)
  .options()
    .submitForSettlement(true)
    .done();

Result<Transaction> result = gateway.transaction().sale(request);

note
For the Recurring use case, it is recommended that merchants pass in transactionSource value of "recurring_first"

Verification

Merchants can create a new customer with a payment method by either passing a 3DS upgraded nonce or an authentication ID associated to the lookup. See the customer guide for more details.

Java

GraphQL

CustomerRequest request = new CustomerRequest()
  .paymentMethodNonce(nonceFromTheClient)
  .threeDSecureAuthenticationId(threeDSecureAuthenticationId)
  .firstName("Fred")
  .lastName("Jones")
  .creditCard()
    .options()
      .verifyCard(true)
      .done()
    .done();

Result<Customer> result = gateway.customer().create(request);

Alternatively, merchants can create a payment method for an existing customer by either passing a 3DS upgraded nonce or an authentication ID associated to the lookup. See the payment method guide for more details.

Java

GraphQL

PaymentMethodRequest request = new PaymentMethodRequest()
  .customerId("the_customer_id")
  .paymentMethodNonce(nonceFromTheClient)
  .threeDSecureAuthenticationId(threeDSecureAuthenticationId)
  .options()
    .verifyCard(true)
  .done();

Result<? extends PaymentMethod> result = gateway.paymentMethod().create(request);

3. Merchant-initiated 3DS (3RI)

A request needs to send the merchantInitiatedRequestType field to indicate the type of 3RI request.

Recurring: "recurring"
Split Shipment: "split_shipment"
Delayed Shipment: "delayed_shipment"
Payment with multiple merchants: "payment_with_multiple_merchants"

important
For the Payment with multiple merchants use case, the merchantOnRecordName field must be passed in. This is the Directory server name of the merchant on whose behalf the customer-initiated 3DS was performed.

Scenario: Customer-initiated 3DS was performed at Braintree

The authenticationId of customer-initiated 3DS performed at Braintree must be sent as the priorAuthenticationId in the 3RI lookup.

Java

GraphQL

ThreeDSecureLookupRequest request = new ThreeDSecureLookupRequest();
request.amount("10.00");
request.merchantInitiatedRequestType("split_shipment");
request.priorAuthenticationId(<PRIOR_AUTHENTICATION_ID>);

Result<ThreeDSecureLookupResponse> result = gateway.threeDSecure().lookup(request);

PaymentMethodNonce paymentMethod = result.getTarget().getPaymentMethod();
String authenticationId = paymentMethod.getThreeDSecureInfo().getThreeDSecureAuthenticationId();

Scenario: Customer-initiated 3DS was performed externally

The authentication details (DS Transaction ID, ACS transaction ID etc.) of the customer-initiated 3DS performed externally must be sent as the priorAuthenticationDetails in the 3RI lookup.

Java

GraphQL

Calendar authTime = Calendar.getInstance();
authTime.set(2024, Calendar.FEBRUARY, 10, 22, 45, 30);

ThreeDSecureLookupPriorAuthenticationDetails priorAuthenticationDetails = new ThreeDSecureLookupPriorAuthenticationDetails()
  .acsTransactionId("acs-transaction-id")
  .authenticationMethod("02")
  .authenticationTime(authTime)
  .dsTransactionId("ds-transaction-id");

ThreeDSecureLookupRequest request = new ThreeDSecureLookupRequest();
request.amount("10.00");
request.merchantInitiatedRequestType("split_shipment");
request.priorAuthenticationDetails(priorAuthenticationDetails);

Result<ThreeDSecureLookupResponse> result = gateway.threeDSecure().lookup(request);

PaymentMethodNonce paymentMethod = result.getTarget().getPaymentMethod();
String authenticationId = paymentMethod.getThreeDSecureInfo().getThreeDSecureAuthenticationId();

note
For the Recurring use case, the recurringFrequency, recurringEnd and purchaseDate fields must also be passed in.

authenticationMethod is the mechanism used to authenticate the customer-initiated 3DS. The possible values in the SDK are:

Frictionless: "01"
Challenge: "02"
AVS Verified: "03"
Other Issuer Method: "04"

4. Merchant-initiated Transaction (MIT)

The following transactionSource values must be passed to indicate that the transaction request is merchant-initiated:

Recurring: "recurring"
Split Shipment: "unscheduled"
Delayed Shipment: "unscheduled"
Payment with multiple merchants: "unscheduled"

Scenario: Recurring, Split Shipment or Delayed Shipment

3RI data can be embedded in a transaction either by passing a 3DS upgraded nonce or a authentication ID associated to the 3RI lookup.

Java

GraphQL

TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(nonceWithout3ds)
  .threeDSecureAuthenticationId(threeDSecureAuthenticationId)
  .transactionSource("unscheduled")
  .options()
    .submitForSettlement(true)
    .done();

Result<Transaction> result = gateway.transaction().sale(request);

Scenario: Payment with multiple merchants

The merchant on record must embed the newly generated CAVV (from the 3RI lookup) in the threeDSecurePassThru field of the transaction.

note
It is the responsibility of the agent (authenticating merchant) to pass the card details to the merchant on record. They can use Grant API or Forward API

Java

GraphQL

TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(nonceWithout3ds)
  .transactionSource("unscheduled")
  .threeDSecurePassThruRequest()
    .cavv(<CAVV_FROM_3RI>)
    .eciFlag("05")
    .dsTransactionId("some-ds-transaction-id")
    .authenticationResponse("some-auth-response")
    .directoryResponse("some-directory-response")
    .cavvAlgorithm("algorithm")
    .done()
  .options()
    .submitForSettlement(true)
    .done();

Result<Transaction> result = gateway.transaction().sale(request);

Next Page: Rules Manager →

3D Secure

Merchant Initiated Authentication (3RI)

Table of Contents

Introduction

Use Cases

1. Recurring

Example: Charging first payment up-front

Example: Free Trial

2. Split Shipment

Example

3. Delayed Shipment

Example

4. Payment with multiple merchants

Example

Integration Steps

1. Customer-initiated 3DS

2. Customer-initiated Transaction (CIT) or Verification

Customer-initiated Transaction (CIT)

Verification

3. Merchant-initiated 3DS (3RI)

Scenario: Customer-initiated 3DS was performed at Braintree

Scenario: Customer-initiated 3DS was performed externally

4. Merchant-initiated Transaction (MIT)

Scenario: Recurring, Split Shipment or Delayed Shipment

Scenario: Payment with multiple merchants