Skip to content

Cartes Bancaires Beta

Last updated: October 12, 2022

Cartes Bancaires (CB) is the predominant card scheme in the French market. The majority of CB cards are co-branded with either Visa or Mastercard, meaning you can process these cards over either CB or the Visa or Mastercard networks.


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 CB.

In practice, this means that merchants must enable consumers to select their preferred brand in a payment form. This expectation comes from CB guidelines directly. Any merchant accepting CB 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. You have two options:

  • Use our front-end iframe solution, Frames
  • Manage your own front-end solution – contact your Customer Success Manager for a secure file transfer protocol (SFTP) scheme BIN file to identify co-badged cards

Use Frames

To enable scheme choice using Frames, specify schemeChoice: true in the Frames initializion. Once this is configured and Frames detects a co-badged card, it will automatically render the consumer choice of card scheme selection.

Use the following examples as a reference for how to format the configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    Frames.init({
    publicKey: "pk_sbox_XXXX",
    modes: [ ],
    frameSelector: ".card-frame",
    localization: "EN-GB",
    debug: false,
    schemeChoice: true
    });

    Once the customer selects Pay, Frames will tokenize the card, and you will see the preferred_scheme field within the cardTokenized event. The preferred_scheme field honors the selection the user makes on the front-end.

    If you'd like to render Frames with custom text input, you can specify your own localization settings.


    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, provided it meets the listed possible exemptions. Read more about exemptions and liability shift.

    Use of exemptions must be through authentication for transactions that are in scope for SCA, meaning your payment request must contain 3ds.enabled=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.

    Secure corporate payment

    CB 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 Sessions - our standalone Authentication solution - skip to the 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 utilise 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.

      post

      https://api.checkout.com/sessions

      Copied!

      Use the following examples as a reference on how to format the configuration.

      Request example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      {
      "source": {
      "type": "card",
      "number": "<CARD_NUMBER>",
      "scheme": "cartes_bancaires",
      "expiry_month": 3,
      "expiry_year": 2023,
      "name": "Cardholder Name",
      "email": "cardholder@checkout.com",
      "billing_address": {
      "address_line_1": "14 Tottenham Court Road",
      "address_line_2": "High St",
      "address_line_3": "",
      "postcode": "W1T 1JY",
      "city": "London",
      "state": "",
      "country": "GB"
      }
      },
      "processing_channel_id": "pc_sbnb4buybxqujn5gqjd5af32wm",
      "amount": 5,
      "currency": "USD",
      "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://google.com",
      "failure_url": "https://bbc.com"
      }
      }

      Frictionless – response example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      {
      "id": "sid_scapyqurerse5fagoqjxuv5bs4",
      "transaction_id": "42fc8090-2491-4e64-9406-74137a57a197",
      "amount": 5,
      "currency": "USD",
      "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": "<authentication value>",
      "transaction_type": "goods_service",
      "eci": "05",
      "session_secret": "<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": "BPCE",
      "issuer_country": "FR",
      "product_id": "F",
      "product_type": "Visa Classic"
      }
      },
      "flow_type": "frictionless",
      "challenge_indicator": "no_preference",
      "_links": {
      "self": {
      "href": "https://api.checkout.com/sessions/sid_scapyqurerse5fagoqjxuv5bs4"
      },
      "success_url": {
      "href": "https://google.com/"
      },
      "failure_url": {
      "href": "https://bbc.com/"
      }
      }
      }

      Pending challenge completion – response example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      {
      "id": "sid_3tlg67seotkuhkrw7bicpblcxy",
      "transaction_id": "7e6fd6dc-7444-43d5-aa36-f850278562be",
      "amount": 5,
      "currency": "USD",
      "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": "<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": "BPCE",
      "issuer_country": "FR",
      "product_id": "F",
      "product_type": "Visa Classic"
      }
      },
      "flow_type": "challenged",
      "challenge_indicator": "no_preference",
      "_links": {
      "self": {
      "href": "https://api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy"
      },
      "redirect_url": {
      "href": "https://api.checkout.com/sessions-interceptor/sid_3tlg67seotkuhkrw7bicpblcxy"
      },
      "success_url": {
      "href": "https://google.com/"
      },
      "failure_url": {
      "href": "https://bbc.com/"
      }
      }
      }

      Challenge completed

      If you're using hosted sessions, perform a GET request after the cardholder is redirected to your page. If you're using non-hosted sessions, follow the integration here when performing the GET request.

      Request example

      1
      2
      3
      curl --location --request GET 'https://api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <Token>’

      Response example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      {
      "id": "sid_3tlg67seotkuhkrw7bicpblcxy",
      "transaction_id": "7e6fd6dc-7444-43d5-aa36-f850278562be",
      "amount": 5,
      "currency": "USD",
      "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": "<authentication value>",
      "transaction_type": "goods_service",
      "eci": "05",
      "session_secret": "<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": "BPCE",
      "issuer_country": "FR",
      "product_id": "F",
      "product_type": "Visa Classic"
      }
      },
      "flow_type": "challenged",
      "challenge_indicator": "no_preference",
      "_links": {
      "self": {
      "href": "https://api.checkout.com/sessions/sid_3tlg67seotkuhkrw7bicpblcxy"
      },
      "success_url": {
      "href": "https://google.com/"
      },
      "failure_url": {
      "href": "https://bbc.com/"
      }
      }
      }

      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 utilise exemptions, you'll need to submit the corresponding exemption in the 3ds.exemption field.

      Endpoints

      For the full specification, see our API reference.

        post

        https://api.checkout.com/payments

        Copied!

        Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        {
        "source": {
        "type": "card",
        "number": "4010050999999999904",
        "expiry_month": 11,
        "expiry_year": 2024
        },
        "3ds": {
        "enabled": true,
        "exemption": "low_value"
        },
        "amount": 20000,
        "capture":false,
        "currency": "EUR",
        "processing_channel_id": "{{processing_channel_cb}}",
        "success_url": "http://success.com",
        "failure_url": "http://failure.com",
        "processing": {
        "preferred_scheme": "cartes_bancaires"
        }
        }

        Recurring or merchant-initiated transactions

        If you process recurring transactions or merchant-initiated transactions (MITs), 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 Sessions for authentication, you can use our simplified integration and authorize payments by setting "enabled": true and using the identifier from the 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, 3ds.enabled must be set to true and processing.preferred_scheme must be set to the scheme that authenticated the payment.

        Additional 3DS2 data is required by CB for authorization, as specified by the field names in the following table. If you are using our Sessions authentication product, refer to the Request authentication section, as well as the table.

        The eci value is not required by the CB 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 nameDescriptionApplicable toSessions response

        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 CB.

        CB co-badged card payments.

        source.scheme

        3ds.eci

        optional

        The Electronic Commerce Indicator returned from authentication.

        All schemes. Optional for CB, however, include eci if available.

        eci

        3ds.cryptogram

        required

        The authentication value.

        All schemes.

        cryptogram

        3ds.xid

        required

        The DS transaction ID from 3DS2, or the XID from 3DS1.

        All schemes.

        xid

        3ds.version

        required

        The protocol version for 3DS.

        All schemes.

        protocol_version

        3ds.status

        conditional

        For 3DS2, this is the transaction status of ARes or RReq.

        All schemes. Mandatory for CB.

        response_code

        3ds.exemption

        conditional

        The exemption applied during a frictionless Fast'R authentication.

        Required for CB when flow_type is frictionless or frictionless_delegated. Not required for CB when exemption.applied = "none"in the Sessions response. Do not send the3ds.exemption` field in this scenario.

        exemption.applied

        3ds.authentication_date

        conditional

        The authentication date and time, in ISO-8601 format.

        Mandatory for CB.

        authentication_date

        3ds.authentication_amount

        conditional

        The authentication amount.

        Mandatory for CB.

        amount

        3ds.flow_type

        required

        Indicates whether the 3DS2 authentication was challenged or frictionless.

        Mandatory for CB.

        flow_type

        3ds.challenge_indicator

        required

        The challenge indicator submitted in 3DS2 authentication.

        Mandatory for CB.

        challenge_indicator

        3ds.score

        optional

        The risk score calculated by the Fast'R Directory Server (DS).

        CB.

        scheme_info.score

        3ds.cryptogram_algorithm

        optional

        The algorithm used by the Issuer ACS to calculate the authentication cryptogram. This is the AVALGO data returned in CB authentication.

        CB.

        scheme_info.avalgo

        Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        {
        "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",
        "crytogram_algorithm": "1"
        },
        "processing": {
        "preferred_scheme": "cartes_bancaires"
        },
        "processing_channel_id": "pc_lpbekttn6uzu3gm6ecfdc3xxie"
        }

        Response example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
        49
        50
        51
        52
        53
        54
        55
        56
        57
        58
        59
        60
        61
        62
        63
        {
        "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": "HSBC CONTINENTAL EUROPE",
        "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://api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi"
        },
        "actions": {
        "href": "https://api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/actions"
        },
        "capture": {
        "href": "https://api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/captures"
        },
        "void": {
        "href": "https://api.checkout.com/payments/pay_dafxh65xirdu7bpigwvumodbzi/voids"
        }
        }
        }