Version 2.2 of 3D Secure (3DS) introduced Requestor-Initiated (3RI) authentications, also known as merchant-initiated authentications. With 3RI authentications, merchants can generate the necessary authentication data for authorization without the customer being directly involved with the transaction. They also allow merchants to reference a previous authentication where the customer was involved.
Use cases
Some of the use cases for 3RI authentications include:
- Partial split shipment — Where ordered products are not all available at the same time, and the merchant decides to ship and charge for them separately.
- Agent payment with multiple merchants — This involves one authentication with the customer present and multiple authorizations for each merchant involved in the transaction. For example, a travel agent managing an order of both hotel and airline for different merchants.
- Unknown final amount before purchase — Where the final amount is not known, for example, potential extra costs for a car rental like damages, missed return date, and so forth.
- Replacement (re-authorization) of a refunded purchase — Where a merchant offers free refunds on items the customer does not want. If the returned items do not include everything purchased, the merchant has to charge the customer again.
In this guide, we focus on a partial split shipment use case. We start with an authentication involving the customer for the full amount of the order. The first authorization is then submitted as fully authenticated for the amount of the first shipment. At this point, we are storing the card number with Global Payments Card Storage. For more information on how to store a card, see our Card Storage article.
When the next item is to be shipped and charged for, the customer is not present, so we execute a 3RI authentication. The request must include the DS Transaction ID of the initial authentication regardless of whether it was a frictionless or challenge flow. The value must be submitted in the 3DS Requestor Prior Transaction Authentication Data field.
Providing the data from the previous authentication will increase the chances that the Issuer will approve the transaction without requiring additional authentication. If this is required, Decoupled Authentication is used as a method to authenticate the customer. For more information, see our Decoupled Authentication article.
Step 1: Authentication for the full order amount
In our example, the full order amount is £100 for two items, one of which is in stock while the other is not. We start by processing a standard 3D Secure 2 authentication for the full amount. For more information on the Initiate Authentication request, see the API Reference for 3D Secure 2.
curl https://api.sandbox.globalpay-ecommerce.com/3ds2/authentications
-H "Content-type: application/json"
-H "X-GP-VERSION: 2.2.0"
-H "Authorization: securehash abafc599cfa60c94b8f41d0668dac5ed6b0a21f7"
-X POST
-d '{
"request_timestamp": "2019-07-30T08:52:44.991911",
"authentication_source": "BROWSER",
"authentication_request_type": "PAYMENT_TRANSACTION",
"message_category": "PAYMENT_AUTHENTICATION",
"message_version": "2.2.0",
"challenge_request_indicator":"NO_PREFERENCE",
"server_trans_id": "ad0fffeb-bfff-44d0-881f-b857fe77c5a2",
"merchant_id": "MerchantId",
"account_id": "internet",
"card_detail": {
"number": "4263970000005262",
"scheme": "VISA",
"expiry_month": "10",
"expiry_year": "25",
"full_name": "James Mason"
},
"order": {
"date_time_created": "2019-07-60T08:52:44.991911Z",
"amount": "10000",
"currency": "GBP",
"id": "3400dd37-101d-4940-be15-3c963b6109b3",
"address_match_indicator": "false",
"shipping_address": {
"line1": "Apartment 852",
"line2": "Complex 741",
"line3": "House 963",
"city": "Chicago",
"postal_code": "50001",
"state": "IL",
"country": "840"
}
},
"payer": {
"email": "james.mason@example.com",
"billing_address": {
"line1": "Flat 456",
"line2": "House 456",
"line3": "Unit 4",
"city": "Halifax",
"postal_code": "W5 9HR",
"country": "826"
},
"mobile_phone": {
"country_code": "44",
"subscriber_number": "7123456789"
}
},
"challenge_notification_url": "https://www.example.com/challengeNotificationUrl",
"method_url_completion": "YES",
"browser_data": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"color_depth": "TWENTY_FOUR_BITS",
"ip": "123.123.123.123",
"java_enabled": "true",
"javascript_enabled": "true",
"language": "en-US",
"screen_height": "1080",
"screen_width": "1920",
"challenge_window_size": "FULL_SCREEN",
"timezone": "0",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36"
},
"merchant_contact_url": "https://www.example.com/about"
}'Step 2: Authorization for the first shipment
When the authentication is complete, we then process an authorization for the amount of the first shipment, which in this example is £50. It is at this point that you would store the card with Global Payments Card Storage for future use.
<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20190730085244">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>AWfoT2k9TzuA0wn8Ze_IIQ</orderid>
<amount currency="GBP">5000</amount>
<card>
<number>4263970000005262</number>
<expdate>1025</expdate>
<chname>James Mason</chname>
<type>VISA</type>
<cvn>
<number>123</number>
<presind>1</presind>
</cvn>
</card>
<autosettle flag="1"/>
<mpi>
<eci>5</eci>
<ds_trans_id>c272b04f-6e7b-43a2-bb78-90f4fb94aa25</ds_trans_id>
<authentication_value>ODQzNjgwNjU0ZjM3N2JmYTg0NTM=</authentication_value>
<message_version>2.2.0</message_version>
</mpi>
<sha1hash>c87e5fa0858671510a02477d146ef744233e4ba8</sha1hash>
</request>Step 3: 3RI authentication for the remaining shipment
In this step, we process an authentication for the remaining £50 of the order using the card we stored in the previous step. In this request, we specify that we're performing a 3DS Requestor/Merchant-Initiated Authentication. As part of the message body, we must also include the authentication data from Step 1: Prior 3D Secure Authentication Data.
In the response, the Issuer might determine that additional authentication is required. If this is required, decoupled authentication will be used. For more information, see our Decoupled Authentication article.
curl https://api.sandbox.globalpay-ecommerce.com/3ds2/authentications
-H "Content-type: application/json"
-H "X-GP-VERSION: 2.2.0"
-H "Authorization: securehash abafc599cfa60c94b8f41d0668dac5ed6b0a21f7"
-X POST
-d '{
"request_timestamp":"2019-08-02T09:43:41",
"authentication_source":"STORED_RECURRING",
"message_category":"PAYMENT_AUTHENTICATION",
"message_version":"2.2.0",
"server_trans_id":"485002c2-4975-4d63-aa76-bcc3f3f8ca93",
"merchant_id":"MerchantId",
"account_id":"internet",
"merchant_initiated_request_type":"SPLIT_OR_DELAYED_SHIPMENT",
"payer_prior_three_ds_authentication_data":{
"authentication_method":"FRICTIONLESS_AUTHENTICATION",
"authentication_timestamp":"2019-07-30T08:52:44.991911Z",
"acs_transaction_id":"26c3f619-39a4-4040-bf1f-6fd433e6d615",
"authentication_data":"string"
},
"card_detail":{
"payer_reference":"e193c21a-ce64-4820-b5b6-8f46715de931",
"payment_method_reference":"10c3e089-fa98-4352-bc4e-4b37f7dcf108"
},
"order":{
"date_time_created":"2020-08-24T09:43:41Z",
"amount":"5000",
"currency":"GBP",
"id":"984244bd-29c6-46a2-8b63-cf65a11cee73",
"address_match_indicator":false,
"shipping_address":{
"line1":"Apartment 852",
"line2":"Complex 741",
"line3":"House 963",
"city":"Chicago",
"postal_code":"50001",
"state":"IL",
"country":"840"
}
},
"payer":{
"email":"james.mason@example.com",
"billing_address":{
"line1":"Flat 456",
"line2":"House 456",
"line3":"Unit 4",
"city":"Halifax",
"postal_code":"W5 9HR",
"country":"826"
},
"mobile_phone":{
"country_code":"44",
"subscriber_number":"7123456789"
}
},
"merchant_contact_url":"https://www.example.com/about"
}Step 4: Authorization for remaining shipment
Now that we've completed our 3RI authentication, we can proceed with authorizing the remaining amount of the order for this shipment using the previously stored card.
<?xml version="1.0" encoding="UTF-8"?>
<request type="receipt-in" timestamp="20180614095601">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<channel>ECOM</channel>
<orderid>AiCibJ5UR7utURy_slxhJw</orderid>
<amount currency="GBP">5000</amount>
<autosettle flag="1"/>
<payerref>e193c21a-ce64-4820-b5b6-8f46715de931</payerref>
<paymentmethod>10c3e089-fa98-4352-bc4e-4b37f7dcf108</paymentmethod>
<mpi>
<eci>5</eci>
<ds_trans_id>c272b04f-6e7b-43a2-bb78-90f4fb94aa25</ds_trans_id>
<authentication_value>ODQzNjgwNjU0ZjM3N2JmYTg0NTM=</authentication_value>
<message_version>2.2.0</message_version>
</mpi>
<sha1hash>f0b45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>