Request 3RI authentication
Beta

Last updated: March 20, 2024

3D requester-initiated authentications (3RI), also known as merchant-initiated authentications, allow you to submit data and authenticate a card-not-present (CNP) transaction. 3RI is a 3DS authentication message that enables processes such as account verification and re-authentication of recurring payments.

To generate the authentication data necessary for authorization, you'll need:

The cardholder's information, which you stored during a previous transaction
The details of a previous transaction

3RI benefits all parties in the payment ecosystem by facilitating better information flow between merchants and issuers. Additionally, 3RI:

Helps the issuer make informed authorization decisions while protecting customer data
Can shift liability away from you for merchant-initiated transactions (MITs) which can utilize 3RI, if necessary conditions are met
Decreases the chance of SCA-related declines during authorization, which could increase approval rates (AR)
3RI enables you to obtain authentication or applicable fraud liability protection for CNP transactions, if there are previously authenticated transactions. This includes:
- Delayed authorizations, including when the initial Cardholder Authentication Verification Value (CAVV) expires if later than 90 days - for example, preorders
- Split shipments - for example, orders containing multiple items, where part of the order is not available to ship yet
- To request CAVV as an authorized entity on behalf of a merchant, in a multi-party commerce scenario - for example, a travel agency requesting on behalf of another merchant

Note

Only Mastercard supports recurring 3RI MITs. If you request a recurring 3RI MIT with another scheme, it fails.

The customer-initiated transaction (CIT) referenced by your 3RI request must include:

3ds.enabled set to true
3ds.challenge_indicator set to challenge_requested_mandate
merchant_initiated set to false
payment_type set to recurring

If the CIT does not meet these requirements, you must perform a new CIT with the required fields and values.

To process a 3RI request in your MIT, you need to provide the payment ID for a transaction in which 3DS was successful in the previous_payment_id field. You should also verify that 3ds.enabled is set to true in the request.

If your 3RI request fails, either due to an unsupported use case or lack of issuer approval, then it'll automatically fall back to being processed as a non-3DS MIT during authorization.


1{
2  "source":{
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "merchant_initiated": true,
11  "previous_payment_id": "pay_xjpgyjfnlunu7ka5bbf5xff52a",
12  "3ds":{
13    "enabled": "true"
14  }
15}


1{
2  "source": {
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "merchant_initiated": true,
11  "previous_payment_id": "pay_xjpgyjfnlunu7ka5bbf5xff52a",
12  "3ds": {
13    "downgraded": false,
14    "enrolled": "Y",
15    "authentication_response": "Y",
16    "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
17    "xid": "6a4a9429-bb6c-4d82-ac7e-8c7ee4eba29d",
18    "version": "2.2.0",
19    "exemption": "none",
20    "challenged": false,
21    "exemption_applied": "none"
22  },
23  "eci": "07"
24}

If the response contains an eci field set to 07, the 3RI request was successful.

If you previously processed the CIT with Checkout.com, you can provide the CIT's session ID value (prefixed with sid_) to the 3RI request's initial_session_id field.

If not, you can either:

Perform a new CIT with Checkout.com to renew the MIT contract
Manually provide the initial_transaction data, using the following fields:
- acs_transaction_id
- authentication_method
- authentication_timestamp
- authentication_data

Note

For Mastercard 3RI requests, you must provide the Directory Server (DS) transaction ID in the authentication_data field.

If your 3RI request fails, either due to an unsupported use case or lack of issuer approval, you can choose to process the transaction as a non-3DS MIT for authorization.


1{
2  "source": {
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "channel_data": {
11    "channel": "merchant_initiated",
12    "request_type": "recurring_transaction"
13  },
14  "initial_transaction": {
15    "initial_session_id": "sid_xjpgyjfnlunu7ka5bbf5xff52a"
16  }
17}


1{
2  "source": {
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "channel_data": {
11    "channel": "merchant_initiated",
12    "request_type": "recurring_transaction"
13  },
14  "initial_transaction": {
15    "acs_transaction_id": "565ae1a9-85e6-41ef-bd21-ba7be0f46cee",
16    "authentication_method": "challenge_occurred",
17    "authentication_timestamp": "2023-08-24T14:15:22Z",
18    "authentication_data": "09ba347c-3e26-475a-a411-ce7c2e1931e8"
19  }
20}


1{
2  "id": "sid_vritznjoo65u3bmo6kduqwjl3i",
3  "transaction_id": "b53c51ac-772e-4dbb-858e-f28748592bda",
4  "amount": 6540,
5  "currency": "USD",
6  "completed": false,
7  "authentication_type": "recurring",
8  "authentication_category": "payment",
9  "status": "approved",
10  "status_reason": "ares_status",
11  "approved": true,
12  "protocol_version": "2.2.0",
13  "reference": "ORD-5023-4E89",
14  "next_actions": [
15    "complete"
16  ],
17  "ds": {
18    "reference_number": "65a5a4ec-cbd3-457b-9610-931ca39a",
19    "transaction_id": "92de3ccd-8266-423d-b264-c4b68d4b5265"
20  },
21  "certificates": {
22    "ds_public": "eyJrdHkiOiJSU0EiLCJuIjoieER6cGJnbUhMTW5UWXVheWtLUzhPU2x1cW9qc2pqaWxQNUU1WlowWFNmeDRzQjNEaUJqU2t1d2w1T0plLUhabkJZQlc2M3lJTWVZVXhtSy1iQkZwTm1lZkFQdkYycm90ZDRrSEwzNUktakVvc1pHajJoanZxNkM3Nmp0MndiZGNqaG92cy1SaUJHT1ZYYnpzSjYxUm1GM1BxRnN0d2NQb0xqcXFYdWdnZnFmQk5QZm9MeWk4UGY4LXlYMWlmaW1vVW80bGdBUHVRdXFIYWtrQWF3aFFSLTRpQXI5X0dpZm10RjBKSGZXNWxCeFR6c3RqYXd2RVRRbHB6U2lGX21NanJHYk9tUlViWklGR2Z2ZjhFc2ZucU9uOV9SXzRDeGhyUkF1QnFqVktST2o5ak43YkRnRThTTkVOeXVER0dNVGFEeWtITkcyNFlTcXphdGRNcXl6bDlRIiwiZSI6IkFRQUIiLCJhbGciOiJSU0EyNTYifQ",
23    "ca_public": "MIICCgKCAgEAxZF3nCEiT8XFFaq-3BPT0cMDlWE76IBsdx27w3hLxwVLog42UTasIgzmysTKpBc17HEZyNAqk9GrCHo0Oyk4JZuXHoW80goZaR2sMnn49ytt7aGsE1PsfVup8gqAorfm3IFab2_CniJJNXaWPgn94-U_nsoaqTQ6j-6JBoIwnFklhbXHfKrqlkUZJCYaWbZRiQ7nkANYYM2Td3N87FmRanmDXj5BG6lc9o1clTC7UvRQmNIL9OdDDZ8qlqY2Fi0eztBnuo2DUS5tGdVy8SgqPM3E12ftk4EdlKyrWmBqFcYwGx4AcSJ88O3rQmRBMxtk0r5vhgr6hDCGq7FHK_hQFP9LhUO91qxWEtMn76Sa7DPCLas-tfNRVwG12FBuEZFhdS_qKMdIYUE5Q6uwGTEvTzg2kmgJT3sNa6dbhlYnYn9iIjTh0dPGgiXap1Bhi8B9aaPFcHEHSqW8nZUINcrwf5AUi-7D-q_AG5ItiBtQTCaaFm74gv51yutzwgKnH9Q-x3mtuK_uwlLCslj9DeXgOzMWFxFguuwLGX39ktDnetxNw3PLabjHkDlGDIfx0MCQakM74sTcuW8ICiHvNA7fxXCnbtjsy7at_yXYwAd-IDS51MA_g3OYVN4M-0pG843Re6Z53oODp0Ymugx0FNO1NxT3HO1hd7dXyjAV_tN_GGcCAwEAAQ"
24  },
25  "acs": {
26    "reference_number": "dae51b83-33cc-4ba8-9f1f-0d68408b",
27    "transaction_id": "8455e890-82e4-4181-9a74-6ca2292a3f59",
28    "operator_id": "d98608cd-60b6-4214-9f3a-93c555ff",
29    "challenge_mandated": false
30  },
31  "response_code": "Y",
32  "challenged": false,
33  "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
34  "transaction_type": "goods_service",
35  "eci": "04",
36  "session_secret": "sek_oZi4z8WZf4t7dOxtcLbfLwiNS747iC2fG4fG1d8AjqE=",
37  "cardholder_info": "This is some information for the cardholder",
38  "scheme": "mastercard",
39  "exemption": {
40    "requested": "none",
41    "applied": "none"
42  },
43  "authentication_date": "2023-08-23T11: 34: 19.7360316Z",
44  "xid": "b53c51ac-772e-4dbb-858e-f28748592bda",
45  "card": {
46    "instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
47    "fingerprint": "instrument_fingerprint",
48    "metadata": {
49      "card_type": "CREDIT",
50      "card_category": "CONSUMER",
51      "issuer_name": "Test Bank",
52      "issuer_country": "US",
53      "product_id": "pr_ubfj2q76miwundwlk72vxt2i7q",
54      "product_type": "product_type"
55    }
56  },
57  "flow_type": "frictionless",
58  "challenge_indicator": "no_preference",
59  "_links": {
60    "self": {
61      "href": "https: //example.com/sid_vritznjoo65u3bmo6kduqwjl3i"
62    },
63    "complete": {
64      "href": "https: //example.com/sid_vritznjoo65u3bmo6kduqwjl3i/complete"
65    },
66    "callback_url": {
67      "href": "https: //exampleapi.com/callback"
68    }
69  }
70}

If a third-party authentication provider performed the initial CIT authentication, you must manually provide the initial_transaction data using the following fields:

acs_transaction_id
authentication_method
authentication_timestamp
authentication_data

Note

For Mastercard 3RI requests, you must provide the DS transaction ID in the authentication_data field.

If your 3RI request fails, either due to an unsupported use case or lack of issuer approval, then it'll automatically fall back to being processed as a non-3DS MIT during authorization.


1{
2  "source": {
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "merchant_initiated": true,
11  "3ds": {
12    "enabled": "true",
13    "acs_transaction_id": "565ae1a9-85e6-41ef-bd21-ba7be0f46cee",
14    "authentication_method": "challenge_occurred",
15    "authentication_timestamp": "2023-08-24T14:15:22Z"
16  }
17}


1{
2  "source": {
3    "type": "card",
4    "number": "5502347652054997",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "GBP",
10  "merchant_initiated" : true,
11  "3ds": {
12    "downgraded": false,
13    "3ri": true,
14    "enrolled": "Y",
15    "authentication_response": "Y",
16    "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
17    "xid": "6a4a9429-bb6c-4d82-ac7e-8c7ee4eba29d",
18    "version": "2.2.0",
19    "exemption": "none",
20    "challenged": false,
21    "exemption_applied": "none"
22  }
23}

Request 3RI authentication
Beta

Benefits

Note

Request 3RI for integrated authentication

Request example

Response example

Request 3RI for standalone authentication

Note

Request example

Response example

Request 3RI using a third party authenticated CIT

Note

Request example

Response example