# Request 3RI authentication 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](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials.md) - The details of a previous transaction --- ## Benefits 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. --- ## Request 3RI for integrated authentication 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. ### Request example ```json { "source":{ "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "merchant_initiated": true, "previous_payment_id": "pay_xjpgyjfnlunu7ka5bbf5xff52a", "3ds":{ "enabled": "true" } } ``` ### Response example ```json { "source": { "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "merchant_initiated": true, "previous_payment_id": "pay_xjpgyjfnlunu7ka5bbf5xff52a", "3ds": { "downgraded": false, "enrolled": "Y", "authentication_response": "Y", "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=", "xid": "6a4a9429-bb6c-4d82-ac7e-8c7ee4eba29d", "version": "2.2.0", "exemption": "none", "challenged": false, "exemption_applied": "none" }, "eci": "07" } ``` If the response contains an `eci` field set to `07`, the 3RI request was successful. ## Request 3RI for standalone authentication 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. ### Request example **CIT previously processed by Checkout.com** ```json { "source": { "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "channel_data": { "channel": "merchant_initiated", "request_type": "recurring_transaction" }, "initial_transaction": { "initial_session_id": "sid_xjpgyjfnlunu7ka5bbf5xff52a" } } ``` **CIT previously processed by third-party** ```json { "source": { "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "channel_data": { "channel": "merchant_initiated", "request_type": "recurring_transaction" }, "initial_transaction": { "acs_transaction_id": "565ae1a9-85e6-41ef-bd21-ba7be0f46cee", "authentication_method": "challenge_occurred", "authentication_timestamp": "2023-08-24T14:15:22Z", "authentication_data": "09ba347c-3e26-475a-a411-ce7c2e1931e8" } } ``` ### Response example ```json { "id": "sid_vritznjoo65u3bmo6kduqwjl3i", "transaction_id": "b53c51ac-772e-4dbb-858e-f28748592bda", "amount": 6540, "currency": "USD", "completed": false, "authentication_type": "recurring", "authentication_category": "payment", "status": "approved", "status_reason": "ares_status", "approved": true, "protocol_version": "2.2.0", "reference": "ORD-5023-4E89", "next_actions": [ "complete" ], "ds": { "reference_number": "65a5a4ec-cbd3-457b-9610-931ca39a", "transaction_id": "92de3ccd-8266-423d-b264-c4b68d4b5265" }, "certificates": { "ds_public": "eyJrdHkiOiJSU0EiLCJuIjoieER6cGJnbUhMTW5UWXVheWtLUzhPU2x1cW9qc2pqaWxQNUU1WlowWFNmeDRzQjNEaUJqU2t1d2w1T0plLUhabkJZQlc2M3lJTWVZVXhtSy1iQkZwTm1lZkFQdkYycm90ZDRrSEwzNUktakVvc1pHajJoanZxNkM3Nmp0MndiZGNqaG92cy1SaUJHT1ZYYnpzSjYxUm1GM1BxRnN0d2NQb0xqcXFYdWdnZnFmQk5QZm9MeWk4UGY4LXlYMWlmaW1vVW80bGdBUHVRdXFIYWtrQWF3aFFSLTRpQXI5X0dpZm10RjBKSGZXNWxCeFR6c3RqYXd2RVRRbHB6U2lGX21NanJHYk9tUlViWklGR2Z2ZjhFc2ZucU9uOV9SXzRDeGhyUkF1QnFqVktST2o5ak43YkRnRThTTkVOeXVER0dNVGFEeWtITkcyNFlTcXphdGRNcXl6bDlRIiwiZSI6IkFRQUIiLCJhbGciOiJSU0EyNTYifQ", "ca_public": "MIICCgKCAgEAxZF3nCEiT8XFFaq-3BPT0cMDlWE76IBsdx27w3hLxwVLog42UTasIgzmysTKpBc17HEZyNAqk9GrCHo0Oyk4JZuXHoW80goZaR2sMnn49ytt7aGsE1PsfVup8gqAorfm3IFab2_CniJJNXaWPgn94-U_nsoaqTQ6j-6JBoIwnFklhbXHfKrqlkUZJCYaWbZRiQ7nkANYYM2Td3N87FmRanmDXj5BG6lc9o1clTC7UvRQmNIL9OdDDZ8qlqY2Fi0eztBnuo2DUS5tGdVy8SgqPM3E12ftk4EdlKyrWmBqFcYwGx4AcSJ88O3rQmRBMxtk0r5vhgr6hDCGq7FHK_hQFP9LhUO91qxWEtMn76Sa7DPCLas-tfNRVwG12FBuEZFhdS_qKMdIYUE5Q6uwGTEvTzg2kmgJT3sNa6dbhlYnYn9iIjTh0dPGgiXap1Bhi8B9aaPFcHEHSqW8nZUINcrwf5AUi-7D-q_AG5ItiBtQTCaaFm74gv51yutzwgKnH9Q-x3mtuK_uwlLCslj9DeXgOzMWFxFguuwLGX39ktDnetxNw3PLabjHkDlGDIfx0MCQakM74sTcuW8ICiHvNA7fxXCnbtjsy7at_yXYwAd-IDS51MA_g3OYVN4M-0pG843Re6Z53oODp0Ymugx0FNO1NxT3HO1hd7dXyjAV_tN_GGcCAwEAAQ" }, "acs": { "reference_number": "dae51b83-33cc-4ba8-9f1f-0d68408b", "transaction_id": "8455e890-82e4-4181-9a74-6ca2292a3f59", "operator_id": "d98608cd-60b6-4214-9f3a-93c555ff", "challenge_mandated": false }, "response_code": "Y", "challenged": false, "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=", "transaction_type": "goods_service", "eci": "04", "session_secret": "sek_oZi4z8WZf4t7dOxtcLbfLwiNS747iC2fG4fG1d8AjqE=", "cardholder_info": "This is some information for the cardholder", "scheme": "mastercard", "exemption": { "requested": "none", "applied": "none" }, "authentication_date": "2023-08-23T11: 34: 19.7360316Z", "xid": "b53c51ac-772e-4dbb-858e-f28748592bda", "card": { "instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q", "fingerprint": "instrument_fingerprint", "metadata": { "card_type": "CREDIT", "card_category": "CONSUMER", "issuer_name": "Test Bank", "issuer_country": "US", "product_id": "pr_ubfj2q76miwundwlk72vxt2i7q", "product_type": "product_type" } }, "flow_type": "frictionless", "challenge_indicator": "no_preference", "_links": { "self": { "href": "https: //example.com/sid_vritznjoo65u3bmo6kduqwjl3i" }, "complete": { "href": "https: //example.com/sid_vritznjoo65u3bmo6kduqwjl3i/complete" }, "callback_url": { "href": "https: //exampleapi.com/callback" } } } ``` --- ## Request 3RI using a third party authenticated CIT 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. ### Request example ```json { "source": { "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "merchant_initiated": true, "3ds": { "enabled": "true", "acs_transaction_id": "565ae1a9-85e6-41ef-bd21-ba7be0f46cee", "authentication_method": "challenge_occurred", "authentication_timestamp": "2023-08-24T14:15:22Z" } } ``` ### Response example ```json { "source": { "type": "card", "number": "5502347652054997", "expiry_month": 1, "expiry_year": 2030 }, "amount": 100, "currency": "GBP", "merchant_initiated" : true, "3ds": { "downgraded": false, "3ri": true, "enrolled": "Y", "authentication_response": "Y", "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=", "xid": "6a4a9429-bb6c-4d82-ac7e-8c7ee4eba29d", "version": "2.2.0", "exemption": "none", "challenged": false, "exemption_applied": "none" } } ```