3D Secure

Merchant Initiated Authentication (3RI)anchor

Table of Contentsanchor

Introductionanchor

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 Casesanchor

1. Recurringanchor

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-frontanchor

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 Trialanchor

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 Shipmentanchor

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.

Exampleanchor

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 Shipmentanchor

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.

Exampleanchor

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 merchantsanchor

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.

Exampleanchor

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 Stepsanchor

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 3DSanchor

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

  1. Recurring: "02"
  2. Split Shipment: "08"
  3. Delayed Shipment: "09"
  4. Payment with multiple merchants: "85"
important

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

  1. 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 Verificationanchor

note

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

Customer-initiated Transaction (CIT)anchor

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

  1. Java
  2. C#
  3. GraphQL
TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(cvvOnlyNonce)
  .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"

Verificationanchor

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.

  1. Java
  2. C#
  3. 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.

  1. Java
  2. C#
  3. 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)anchor

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

  1. Recurring: "recurring"
  2. Split Shipment: "split_shipment"
  3. Delayed Shipment: "delayed_shipment"
  4. 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 Braintreeanchor

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

  1. Java
  2. C#
  3. GraphQL
ThreeDSecureLookupRequest request = new ThreeDSecureLookupRequest();
        request.amount("10.00");
        request.merchantInitiatedRequestType("split_shipment");
        request.priorAuthenticationId(<PRIOR_AUTHENTICATION_ID>);

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

Scenario: Customer-initiated 3DS was performed externallyanchor

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.

  1. Java
  2. C#
  3. 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> outerResult = gateway.threeDSecure().lookup(request);

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

  1. Frictionless: "01"
  2. Challenge: "02"
  3. AVS Verified: "03"
  4. Other Issuer Method: "04"

4. Merchant-initiated Transaction (MIT)anchor

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

  1. Recurring: "recurring"
  2. Split Shipment: "unscheduled"
  3. Delayed Shipment: "unscheduled"
  4. Payment with multiple merchants: "unscheduled"

Scenario: Recurring, Split Shipment or Delayed Shipmentanchor

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

  1. Java
  2. C#
  3. GraphQL
TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(cvvOnlyNonce)
  .threeDSecureAuthenticationId(threeDSecureAuthenticationId)
  .transactionSource("unscheduled")
  .options()
    .submitForSettlement(true)
    .done();

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

Scenario: Payment with multiple merchantsanchor

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

  1. Java
  2. C#
  3. GraphQL
TransactionRequest request = new TransactionRequest()
  .amount(new BigDecimal("10.00"))
  .paymentMethodNonce(cvvOnlyNonce)
  .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);