# Cartes Bancaires for Unified Payments API To accept Cartes Bancaires payments, you must: 1. Confirm the card branch choice 2. Request authentication 3. Request a payment ## Confirm the card brand choice European regulation (EU IFR Regulation 2015/751 article 8) mandates merchants and acquirers to follow consumers’ card brand choice for payments made with co-badged cards. For example, cards branded with both Visa and Mastercard and a local scheme such as Cartes Bancaires. In practice, this means that merchants must enable consumers to select their preferred brand in a payment form. This expectation comes from Cartes Bancaires guidelines directly. Any merchant accepting Cartes Bancaires payments should offer this "choix de la marque" during their checkout process. If you detect a co-badged card, you must present all supported brands for the customer to choose from. Contact your account manager for a secure file transfer protocol (SFTP) scheme BIN file to identify co-badged cards. When processing co-branded Cartes Bancaires cards through Apple Pay, you must order the `supportedNetworks` array in your front-end Apple Pay code to prioritize the default network for co-branded cards. For example, if Visa or Mastercard appears first, it takes priority over Cartes Bancaires and vice versa. --- ## Request authentication ### Exemptions To increase the likelihood of a frictionless transaction, request an exemption in your API request. You can request an exemption for transactions that must be [Strong Customer Authentication (SCA) compliant](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md#SCA_exemptions), provided it meets the listed possible exemptions. [Read more about exemptions and liability shift](https://www.checkout.com/docs/risk-management/3d-secure/sessions/hosted-sessions.md#Exemptions). Use of exemptions must be through authentication for transactions that are in scope for SCA, meaning your payment request must contain the `3ds.enabled` field set to `true`. If no exemption can be applied, then the `challenge_indicator` field will be set to `no_challenge_requested` and liability shift will not be applied. > **Information** > > To simulate different 3D Secure (3DS) authentication flows and results for testing, use the Cartes Bancaires [3DS test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md#3D_Secure_test_cards). ### Secure corporate payment Cartes Bancaires does not support the `secure_corporate_payment` exemption in the authentication flow as they deem it SCA exempt. If this exemption is used in the authentication flow, we'll automatically apply it in the authorization flow instead. ### Standalone authentication requirements If you are not using [Standalone (Sessions)](https://www.checkout.com/docs/risk-management/3d-secure/sessions.md) - our standalone Authentication solution - skip to the [Request a Payment](#Request_a_payment) section. To select the scheme to process the authentication with, set the `source.scheme` field to one of the following values: `visa`, `mastercard` or `cartes_bancaires`. To utilize exemptions, you'll need to submit the corresponding exemption in the `challenge_indicator` field. If no exemption can be applied, then the value `no_challenge_requested` will be used instead. If no exemption was applied to the authentication despite a frictionless `flow_type`, the value `none` will be returned in the response's `exemption.applied` field. In this scenario, do not include the `3ds.exemption` field when sending the authorization request. ### Endpoints For the full API specification, see the [API reference](https://api-reference.checkout.com/). > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/sessions` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions` Use the following examples as a reference on how to format the configuration. ### Request example ```json { "source": { "type": "card", "number": "", "scheme": "cartes_bancaires", "expiry_month": 3, "expiry_year": 2023, "name": "John Smith", "email": "john.smith@example.com", "billing_address": { "address_line_1": "123 High St.", "address_line_2": "Flat 456", "address_line_3": "", "postcode": "SW1A 1AA", "city": "London", "country": "GB" } }, "processing_channel_id": "pc_sbnb4buybxqujn5gqjd5af32wm", "amount": 5, "currency": "EUR", "authentication_type": "regular", "authentication_category": "payment", "challenge_indicator": "low_value", "reference": "ORD-5023-4E89", "transaction_type": "goods_service", "channel_data": { "channel": "browser", "accept_header": "Accept: *.*, q=0.1", "three_ds_method_completion": "U", "java_enabled": true, "language": "FR-fr", "color_depth": "16", "screen_height": "1080", "screen_width": "1920", "timezone": "60", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36", "ip_address": "1.12.123.255" }, "completion": { "type": "hosted", "success_url": "https://example.com/payments/success", "failure_url": "https://example.com/payments/failure" } } ``` ### Frictionless – response example ```json { "id": "sid_scapyqurerse5fagoqjxuv5bs4", "transaction_id": "42fc8090-2491-4e64-9406-74137a57a197", "amount": 5, "currency": "EUR", "authentication_type": "regular", "authentication_category": "payment", "status": "approved", "status_reason": "ares_status", "approved": true, "protocol_version": "2.1.0", "reference": "ORD-5023-4E89", "next_actions": [], "ds": { "reference_number": "3DS_LOA_DIS_GDCB_020100_00137", "transaction_id": "fdb5f954-3fbb-4731-b2e3-f3cbe01c6e05" }, "acs": { "reference_number": "3DS_LOA_ACS_EQWO_020200_00280", "transaction_id": "b0a86141-b156-4498-84f5-73f00d45f86a", "operator_id": "ACS-0008P-BPCE-EWL", "challenge_mandated": false }, "response_code": "Y", "challenged": false, "cryptogram": "", "transaction_type": "goods_service", "eci": "05", "session_secret": "", "scheme": "cartes_bancaires", "scheme_info": { "name": "cartes_bancaires", "avalgo": "2" }, "exemption": { "requested": "none", "applied": "none", "code": "AAAA" }, "authentication_date": "2022-05-20T15:17:30.0893493Z", "xid": "fdb5f954-3fbb-4731-b2e3-f3cbe01c6e05", "card": { "instrument_id": "src_ajshdroelu3u3grxgvhmd7ptmm", "fingerprint": "93206CDE658E580AC8643AD72AC9D6A8FBF6FED4BDF19FF9AC3F32E7BC18D617", "metadata": { "card_type": "DEBIT", "card_category": "CONSUMER", "issuer_name": "Test Bank", "issuer_country": "FR", "product_id": "F", "product_type": "Visa Classic" } }, "flow_type": "frictionless", "challenge_indicator": "no_preference", "customer_ip": "1.12.123.255", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/sessions/sid_scapyqurerse5fagoqjxuv5bs4" }, "success_url": { "href": "https://example.com/payments/success" }, "failure_url": { "href": "https://example.com/payments/failure" } } } ``` ### Pending challenge completion – response example ```json { "id": "sid_3tlg67seotkuhkrw7bicpblcxy", "transaction_id": "7e6fd6dc-7444-43d5-aa36-f850278562be", "amount": 5, "currency": "EUR", "authentication_type": "regular", "authentication_category": "payment", "status": "challenged", "status_reason": "ares_status", "protocol_version": "2.1.0", "reference": "ORD-5023-4E89", "next_actions": ["redirect_cardholder"], "ds": { "reference_number": "3DS_LOA_DIS_GDCB_020100_00137", "transaction_id": "64bffd02-9e4a-49e7-8319-cac119ad1adb" }, "acs": { "reference_number": "3DS_LOA_ACS_EQWO_020200_00280", "transaction_id": "77c226ef-6166-42a9-a5cf-54201efdc822", "operator_id": "ACS-0008P-BPCE-EWL", "url": "https://natixispaymentsolutions-3ds-vdm.wlp-acs.com/acs-challenge-browser-service/challenge/challengeRequest/browserBase", "challenge_mandated": true, "authentication_type": "01" }, "response_code": "C", "challenged": true, "transaction_type": "goods_service", "session_secret": "", "scheme": "cartes_bancaires", "authentication_date": "2022-05-20T15:13:47.1865419Z", "xid": "64bffd02-9e4a-49e7-8319-cac119ad1adb", "card": { "instrument_id": "src_brtjjnw3ynmebi37dk7kbtbxru", "fingerprint": "93206CDE658E580AC8643AD72AC9D6A8FBF6FED4BDF19FF9AC3F32E7BC18D617", "metadata": { "card_type": "DEBIT", "card_category": "CONSUMER", "issuer_name": "Test Bank", "issuer_country": "FR", "product_id": "F", "product_type": "Visa Classic" } }, "flow_type": "challenged", "challenge_indicator": "no_preference", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy" }, "redirect_url": { "href": "https://{prefix}.api.checkout.com/sessions-interceptor/sid_3tlg67seotkuhkrw7bicpblcxy" }, "success_url": { "href": "https://example.com/payments/success" }, "failure_url": { "href": "https://example.com/payments/failure" } } } ``` ### Challenge completed If you're using [hosted sessions](https://www.checkout.com/docs/risk-management/3d-secure/sessions/hosted-sessions.md), perform a `GET` request after the cardholder is redirected to your page. If you're using non-hosted sessions, follow our [example integration](https://www.checkout.com/docs/risk-management/3d-secure/sessions/non-hosted-sessions.md#Notification_of_outcome) when performing the `GET` request. #### Request example ``` curl --location --request GET 'https://{prefix}.api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ’ ``` #### Response example ```json { "id": "sid_3tlg67seotkuhkrw7bicpblcxy", "transaction_id": "7e6fd6dc-7444-43d5-aa36-f850278562be", "amount": 5, "currency": "EUR", "authentication_type": "regular", "authentication_category": "payment", "status": "approved", "status_reason": "rreq_status", "approved": true, "protocol_version": "2.1.0", "reference": "ORD-5023-4E89", "next_actions": [], "ds": { "reference_number": "3DS_LOA_DIS_GDCB_020100_00137", "transaction_id": "64bffd02-9e4a-49e7-8319-cac119ad1adb" }, "acs": { "reference_number": "3DS_LOA_ACS_EQWO_020200_00280", "transaction_id": "77c226ef-6166-42a9-a5cf-54201efdc822", "operator_id": "ACS-0008P-BPCE-EWL", "url": "https://natixispaymentsolutions-3ds-vdm.wlp-acs.com/acs-challenge-browser-service/challenge/challengeRequest/browserBase", "challenge_mandated": true, "authentication_type": "03" }, "response_code": "Y", "challenged": true, "cryptogram": "", "transaction_type": "goods_service", "eci": "05", "session_secret": "", "scheme": "cartes_bancaires", "scheme_info": { "name": "cartes_bancaires", "avalgo": "2" }, "authentication_date": "2022-05-20T15:13:47.1865419Z", "xid": "64bffd02-9e4a-49e7-8319-cac119ad1adb", "card": { "instrument_id": "src_brtjjnw3ynmebi37dk7kbtbxru", "fingerprint": "93206CDE658E580AC8643AD72AC9D6A8FBF6FED4BDF19FF9AC3F32E7BC18D617", "metadata": { "card_type": "DEBIT", "card_category": "CONSUMER", "issuer_name": "Test Bank", "issuer_country": "FR", "product_id": "F", "product_type": "Visa Classic" } }, "flow_type": "challenged", "challenge_indicator": "no_preference", "customer_ip": "1.12.123.255", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy" }, "success_url": { "href": "https://example.com/payments/success" }, "failure_url": { "href": "https://example.com/payments/failure" } } } ``` --- ## Request a payment When the customer has chosen their preferred brand, you must include it in the `processing.preferred_scheme` field in your payment request. To utilize exemptions, you'll need to submit the corresponding exemption in the `3ds.exemption` field. > **Information** > > To simulate a payment for testing, use the Cartes Bancaires [test card](https://www.checkout.com/docs/developer-resources/testing/test-cards.md#Default_cards_and_responses). ### Endpoints For the full specification, see our [API reference](https://api-reference.checkout.com). > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "card", "number": "4010050999999999904", "expiry_month": 11, "expiry_year": 2024 }, "3ds": { "enabled": true, "exemption": "low_value" }, "amount": 1000, "capture": false, "currency": "EUR", "processing_channel_id": "{{processing_channel_cb}}", "success_url": "https://example.com/payments/success", "failure_url": "https://example.com/payments/failure", "processing": { "preferred_scheme": "cartes_bancaires" } } ``` ### Recurring or merchant-initiated transactions If you process [recurring transactions or merchant-initiated transactions (MITs)](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details.md), the subsequent MITs must be processed using the same scheme as the initial cardholder-initiated transaction (CIT). You must set the `processing.preferred_scheme` as the customer-chosen scheme from the initial payment. ### 3D Secure payments with our standalone Authentication product If you use [Standalone (Sessions)](https://www.checkout.com/docs/risk-management/3d-secure/sessions.md) for authentication, you can use our [simplified integration](https://www.checkout.com/docs/payments/authenticate-payments.md#Standalone_sessions_authentication) and authorize payments by setting `"enabled": true` and using the identifier from the Standalone (Sessions) API response. Using this integration will also allow you to have a consolidated view that links the authentication to the payment in your Dashboard. ### 3D Secure payments with a third-party provider If you are authenticating the transaction prior to requesting a payment: - The `3ds.enabled` field must be set to `true`. - The `processing.preferred_scheme` field must be set to the scheme that authenticated the payment. Additional 3DS data is required by Cartes Bancaires for authorization, as specified by the field names in the following table. If you are using our Standalone (Sessions) authentication product, refer to the [Request authentication](#Request_authentication) section, as well as the table. The `eci` value is not required by the Cartes Bancaires scheme and it may not be present in the ARes (frictionless flow) or RReq (challenge flow) messages. For compatibility reasons, the access control server (ACS) may send it in the ARes message according to other payment schemes, particularly in the case of co-badged cards. | Field name | Description | Applicable to | Sessions response | | --- | --- | --- | --- | | `3ds.challenge_indicator`

`required` | The challenge indicator submitted in 3DS authentication. | Mandatory for Cartes Bancaires. | `challenge_indicator` | | `3ds.cryptogram`

`required` | The authentication value. | All schemes. | `cryptogram` | | `3ds.flow_type`

`required` | Indicates whether the 3DS authentication was challenged or frictionless. | Mandatory for Cartes Bancaires. | `flow_type` | | `3ds.version`

`required` | The protocol version for 3DS. | All schemes. | `protocol_version` | | `3ds.xid`

`required` | The DS transaction ID from 3DS. | All schemes. | `xid` | | `3ds.authentication_amount`

`conditional` | The authentication amount. | Mandatory for Cartes Bancaires. | `amount` | | `3ds.authentication_date`

`conditional` | The authentication date and time, in ISO-8601 format. | Mandatory for Cartes Bancaires. | `authentication_date` | | `3ds.exemption`

`conditional` | The exemption applied during a frictionless Fast'R authentication. | Required for Cartes Bancaires when `flow_type` is `frictionless` or `frictionless_delegated`.

Not required for Cartes Bancaires when `exemption.applied` = "none" in the Standalone (Sessions) response.

Do not send the `3ds.exemption` field in this scenario. | `exemption.applied` | | `3ds.status`

`conditional` | For 3DS, this is the transaction status of ARes or RReq. | All schemes. Mandatory for Cartes Bancaires. | `response_code` | | `payment_ip`

`conditional` | The IP address that is collected during authentication must be passed in the authorization message for Cartes Bancaires transactions. | Cartes Bancaires. Include for best performance. | `customer_ip` | | `3ds.cryptogram_algorithm`

`optional` | The algorithm used by the Issuer ACS to calculate the authentication cryptogram.

This is the AVALGO data returned in Cartes Bancaires authentication. | Cartes Bancaires. | `scheme_info.avalgo` | | `3ds.eci`

`optional` | The Electronic Commerce Indicator returned from authentication. | All schemes. Optional for Cartes Bancaires. However, include `eci` if available. | `eci` | | `3ds.score`

`optional` | The risk score calculated by the Fast'R Directory Server (DS). | Cartes Bancaires. | `scheme_info.score` | | `processing.preferred_scheme`

`optional` | The preferred scheme for co-badged card payment processing.

If using third-party authentication before requesting the payment, set the value to the scheme that authenticated the transaction.

If left unspecified, this defaults to Cartes Bancaires. | Cartes Bancaires co-badged card payments. | `source.scheme` | ### Request example ```json { "source": { "type": "card", "number": "4010056200000018", "expiry_month": "1", "expiry_year": "2030", "cvv": "123" }, "amount": 30, "currency": "EUR", "capture": true, "3ds": { "enabled": true, "eci": "05", "cryptogram": "ABADAhaHNAAAEFgmBYc0AAAAAAA=", "xid": "9cd6ae9a-6123-4dc9-b5ce-a3068de19bed", "version": "2.1.0", "authentication_date": "2022-05-19T09:42:44.2449933Z", "authentication_amount": "30", "challenge_indicator": "no_challenge_requested", "flow_type": "frictionless", "status": "Y", "exemption": "low_value", "score": "90", "cryptogram_algorithm": "1" }, "processing": { "preferred_scheme": "cartes_bancaires" }, "processing_channel_id": "pc_lpbekttn6uzu3gm6ecfdc3xxie" } ``` ### Response example ```json { "id": "pay_dafxh65xirdu7bpigwvumodbzi", "action_id": "act_pyy366dbghaevh7hlsudnexmtm", "amount": 30, "currency": "EUR", "approved": true, "status": "Authorized", "auth_code": "099565", "response_code": "10000", "response_summary": "Approved", "balances": { "total_authorized": 30, "total_voided": 0, "available_to_void": 30, "total_captured": 0, "available_to_capture": 30, "total_refunded": 0, "available_to_refund": 0 }, "risk": { "flagged": false }, "source": { "id": "src_vg6pj2d4bv5e7acl34fri27sjq", "type": "card", "expiry_month": 11, "expiry_year": 2022, "scheme": "Visa", "scheme_local": "cartes_bancaires", "last4": "6225", "fingerprint": "CF8F2166285885F45ECFA069581990B03D135352F91FB33623761715C243955F", "bin": "456100", "card_type": "DEFERRED DEBIT", "card_category": "CONSUMER", "issuer": "Test Bank", "issuer_country": "FR", "product_id": "P", "product_type": "Visa Gold", "avs_check": "U", "cvv_check": "Y" }, "processed_on": "2022-05-19T09:42:44.5813445Z", "eci": "05", "processing": { "acquirer_transaction_id": "039232", "retrieval_reference_number": "039232" }, "expires_on": "2022-06-18T09:42:44.5813445Z", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi" }, "actions": { "href": "https://{prefix}.api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/actions" }, "capture": { "href": "https://{prefix}.api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/captures" }, "void": { "href": "https://{prefix}.api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/voids" } } } ```