3D Secure
Merchant Initiated Authentication (3RI)
Table of Contents
- Introduction
- Use Cases
- Integration Steps
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.
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.
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.
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.
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.
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.
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.
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
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"
- 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
});
2. Customer-initiated Transaction (CIT) or Verification
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
- C#
- 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);
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
- C#
- 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
- C#
- 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"
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
- C#
- 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 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
- C#
- 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:
- 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
- C#
- 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 merchants
The merchant on record must embed the newly generated CAVV (from the 3RI lookup) in the threeDSecurePassThru
field of the transaction.
- Java
- C#
- 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);
Next Page: Rules Manager →