---
title: "Titres-restaurant for API only"
description: "Add Titres-restaurant payments to an existing API-only integration."
url: "https://docs.adyen.com/payment-methods/titres-restaurant/api-only"
source_url: "https://docs.adyen.com/payment-methods/titres-restaurant/api-only.md"
canonical: "https://docs.adyen.com/payment-methods/titres-restaurant/api-only"
last_modified: "2022-12-20T13:57:00+01:00"
language: "en"
---

# Titres-restaurant for API only

Add Titres-restaurant payments to an existing API-only integration.

[View source](/payment-methods/titres-restaurant/api-only.md)

Accept Titres-restaurant payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

## Requirements

| Requirement          | Description                                                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | Make sure that you have built an [API-only integration](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20Only).                                                                                                                                                                                                              |
| **Setup steps**      | Before you begin:- [Activate Titres-Restaurant](/payment-methods/titres-restaurant#activate) to get your *Carte de domiciliation CONECS*.
- [Add the meal voucher payment method in your Customer Area](/payment-methods/add-payment-methods), providing your SIRET (your business registration ID) and the Conecs MID from your *Carte de domiciliation CONECS*. |

## Build your payment form for Titres-restaurant

If you are using the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) request to show the available payment methods to your shopper, specify the following in your request:

* [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods): **FR**
* [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount): **EUR**

In the response, you receive the meal vouchers available to your shopper as elements in the `paymentMethods` array, for example:

**API response**

```bash
{
    {
        "name": "Up Titre-Restaurant",
        "type": "mealVoucher_FR_groupeup"
    },
    {
        "name": "Apetiz Titre-Restaurant",
        "type": "mealVoucher_FR_natixis"
    },
    {
        "name": "Sodexo Titre-Restaurant",
        "type": "mealVoucher_FR_sodexo"
    }
}
```

**Apetiz** and **mealVoucher\_FR\_natixis** refer to Bimpli, the commercial brand for Natixis.

Render [logos](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#downloading-logos) and names of the available brands for the shopper to choose. When the shopper selects a type of meal voucher, show the payment form.

## Check the balance

After the shopper enters the meal voucher details, check if the balance is enough to make a full payment.

1. Make a [/paymentMethods/balance](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods/balance) request including:

   | Field                       | Required                                                                                    | Description                                                                                                                                                             |
   | --------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `paymentMethod.type`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **mealVoucher\_FR**                                                                                                                                                     |
   | `paymentMethod.number`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The meal voucher number.                                                                                                                                                |
   | `paymentMethod.expiryMonth` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month of the meal voucher.                                                                                                                                       |
   | `paymentMethod.expiryYear`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year of the meal voucher.                                                                                                                                        |
   | `reference`                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your reference to uniquely identify the transaction. To provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters. |

   **/paymentMethods/balance request**

   #### curl

   ```bash
   curl https://checkout-test.adyen.com/v72/paymentMethods/balance \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'content-type: application/json' \
   -d '{
     "paymentMethod": {
       "type": "mealVoucher_FR",
       "number":"4242420100058007",
       "expiryMonth": "06",
       "expiryYear": "2023"
     },
     "reference": "YOUR_REFERENCE",
     "merchantAccount": "ADYEN_MERCHANT_ACCOUNT"
   }'
   ```

   #### Java

   ```java
   // Adyen Java API Library v27.0.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.model.checkout.*;
   import java.time.OffsetDateTime;
   import java.util.*;
   import com.adyen.model.RequestOptions;
   import com.adyen.service.checkout.*;

   // For the live environment, additionally include your liveEndpointUrlPrefix.
   Client client = new Client("ADYEN_API_KEY", Environment.TEST);

   // Create the request object(s)
   BalanceCheckRequest balanceCheckRequest = new BalanceCheckRequest()
     .reference("YOUR_REFERENCE")
     .merchantAccount("ADYEN_MERCHANT_ACCOUNT")
     .paymentMethod(new HashMap<String, String>(Map.of(
       "number", "4242420100058007",
       "expiryMonth", "06",
       "expiryYear", "2023",
       "type", "mealVoucher_FR"
     )));

   // Send the request
   OrdersApi service = new OrdersApi(client);
   BalanceCheckResponse response = service.getBalanceOfGiftCard(balanceCheckRequest, new RequestOptions().idempotencyKey("UUID"));
   ```

   #### PHP

   ```php
   // Adyen PHP API Library v19.0.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Model\Checkout\BalanceCheckRequest;
   use Adyen\Service\Checkout\OrdersApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_API_KEY");
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   $client->setEnvironment(Environment::TEST);


   // Create the request object(s)
   $balanceCheckRequest = new BalanceCheckRequest();
   $balanceCheckRequest
     ->setReference("YOUR_REFERENCE")
     ->setMerchantAccount("ADYEN_MERCHANT_ACCOUNT")
     ->setPaymentMethod(
       array(
         "number" => "4242420100058007",
         "expiryMonth" => "06",
         "expiryYear" => "2023",
         "type" => "mealVoucher_FR"
       )
     );

   $requestOptions['idempotencyKey'] = 'UUID';

   // Send the request
   $service = new OrdersApi($client);
   $response = $service->getBalanceOfGiftCard($balanceCheckRequest, $requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v17.0.0
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.Checkout;
   using Adyen.Service.Checkout;

   // For the live environment, additionally include your liveEndpointUrlPrefix.
   var config = new Config()
   {
       XApiKey = "ADYEN_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Create the request object(s)
   BalanceCheckRequest balanceCheckRequest = new BalanceCheckRequest
   {
     Reference = "YOUR_REFERENCE",
     MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
     PaymentMethod = new Dictionary<string, string>
     {

       { "number", "4242420100058007" },
       { "expiryMonth", "06" },
       { "expiryYear", "2023" },
       { "type", "mealVoucher_FR" }
     }
   };

   // Send the request
   var service = new OrdersService(client);
   var response = service.GetBalanceOfGiftCard(balanceCheckRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v18.0.0
   // Require the parts of the module you want to use
   const { Client, CheckoutAPI } = require('@adyen/api-library');
   // Initialize the client object
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Create the request object(s)
   const balanceCheckRequest = {
     paymentMethod: {
       type: "mealVoucher_FR",
       number: "4242420100058007",
       expiryMonth: "06",
       expiryYear: "2023"
     },
     reference: "YOUR_REFERENCE",
     merchantAccount: "ADYEN_MERCHANT_ACCOUNT"
   }

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.OrdersApi.getBalanceOfGiftCard(balanceCheckRequest, { idempotencyKey: "UUID" });
   ```

   #### Go

   ```go
   // Adyen Go API Library v10.4.0
   import (
     "context"
     "github.com/adyen/adyen-go-api-library/v9/src/common"
     "github.com/adyen/adyen-go-api-library/v9/src/adyen"
     "github.com/adyen/adyen-go-api-library/v9/src/checkout"
   )
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   client := adyen.NewClient(&common.Config{
     ApiKey:      "ADYEN_API_KEY",
     Environment: common.TestEnv,
   })

   // Create the request object(s)
   balanceCheckRequest := checkout.BalanceCheckRequest{
     Reference: common.PtrString("YOUR_REFERENCE"),
     MerchantAccount: "ADYEN_MERCHANT_ACCOUNT",
     PaymentMethod: &map[string]string{
       "number": "4242420100058007",
       "expiryMonth": "06",
       "expiryYear": "2023",
       "type": "mealVoucher_FR",
     },
   }

   // Send the request
   service := client.Checkout()
   req := service.OrdersApi.GetBalanceOfGiftCardInput().IdempotencyKey("UUID").BalanceCheckRequest(balanceCheckRequest)
   res, httpRes, err := service.OrdersApi.GetBalanceOfGiftCard(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v12.5.1
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = "ADYEN_API_KEY"
   # For the live environment, additionally include your liveEndpointUrlPrefix.
   adyen.client.platform = "test" # The environment to use library in.

   # Create the request object(s)
   json_request = {
     "paymentMethod": {
       "type": "mealVoucher_FR",
       "number": "4242420100058007",
       "expiryMonth": "06",
       "expiryYear": "2023"
     },
     "reference": "YOUR_REFERENCE",
     "merchantAccount": "ADYEN_MERCHANT_ACCOUNT"
   }

   # Send the request
   result = adyen.checkout.orders_api.get_balance_of_gift_card(request=json_request, idempotency_key="UUID")
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v9.5.1
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_API_KEY'
   # For the live environment, additionally include your liveEndpointUrlPrefix.
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   request_body = {
     :paymentMethod => {
       :type => 'mealVoucher_FR',
       :number => '4242420100058007',
       :expiryMonth => '06',
       :expiryYear => '2023'
     },
     :reference => 'YOUR_REFERENCE',
     :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT'
   }

   # Send the request
   result = adyen.checkout.orders_api.get_balance_of_gift_card(request_body, headers: { 'Idempotency-Key' => 'UUID' })
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v18.0.0
   // Require the parts of the module you want to use
   import { Client, CheckoutAPI, Types } from "@adyen/api-library";
   // Initialize the client object
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Create the request object(s)
   const balanceCheckRequest: Types.checkout.BalanceCheckRequest = {
     reference: "YOUR_REFERENCE",
     merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
     paymentMethod: {
       "number": "4242420100058007",
       "expiryMonth": "06",
       "expiryYear": "2023",
       "type": "mealVoucher_FR"
     }
   };

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.OrdersApi.getBalanceOfGiftCard(balanceCheckRequest, { idempotencyKey: "UUID" });
   ```

   The response includes the balance of the meal voucher.

   **/paymentMethods/balance response**

   ```json
   {
     "balance": {
        "currency": "EUR",
        "value": 2500
    },
     "pspReference": "ZQXDPCQ8HXSKGK82",
     "resultCode": "Success"
   }
   ```

2. If the balance amount is equal to or greater than the full payment amount, then continue to [make a payment](#make-a-payment).

   If the balance is less than the full payment amount, [create an order](/online-payments/partial-payments) and ask the shopper to make partial payments with the meal voucher and a different payment method.

## Make a payment

From your server, make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, specifying:

| Field                       | Required                                                                                    | Description                                 |
| --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `paymentMethod.type`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **mealVoucher\_FR**.                        |
| `paymentMethod.number`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The meal voucher number without separators. |
| `paymentMethod.expiryMonth` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The expiry month of the meal voucher.       |
| `paymentMethod.expiryYear`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The expiry year of the meal voucher.        |
| `paymentMethod.cvc`         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The CVC of the meal voucher.                |

#### curl

```bash
curl https://checkout-test.adyen.com/v68/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod": {
     "type": "mealVoucher_FR",
     "number":"2345678910111213",
     "expiryMonth": "06",
     "expiryYear": "2023",
     "cvc": "123"
   },
  "merchantAccount":"ADYEN_MERCHANT_ACCOUNT"
}'
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v16.1.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');

// Initialize the client object
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object
const paymentRequest = {
  amount: {
    currency: "EUR",
    value: 1000
  },
  reference: "YOUR_ORDER_NUMBER",
  paymentMethod: {
    type: "mealVoucher_FR",
    number: "2345678910111213",
    expiryMonth: "06",
    expiryYear: "2023",
    cvc: "123"
  },
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT"
}

// Make the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

#### Python

```py
# Adyen Python API Library v12.0.0
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment to use library in.

json_request = {
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "mealVoucher_FR",
    "number": "2345678910111213",
    "expiryMonth": "06",
    "expiryYear": "2023",
    "cvc": "123"
  },
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT"
}

result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.1.0
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # Set to "live" for live environment

request_body = {
  :amount => {
    :currency => 'EUR',
    :value => 1000
  },
  :reference => 'YOUR_ORDER_NUMBER',
  :paymentMethod => {
    :type => 'mealVoucher_FR',
    :number => '2345678910111213',
    :expiryMonth => '06',
    :expiryYear => '2023',
    :cvc => '123'
  },
  :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT'
}

result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

The [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains:

* [pspReference](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/payments__resParam_pspReference): Our unique identifier for the transaction.
* `resultCode`: Use this to [present the payment result to your shopper](#present-the-payment-result).
* `merchantReference`: The `reference` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request.

## Present the payment result

Use the [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response to present the payment result to your shopper.

You will also receive the outcome of the payment asynchronously in a [webhook](/development-resources/webhooks). For Titres-restaurant payments, you can receive the following `resultCode` values:

| resultCode     | Description                                                                                                                                               | Action to take                                                                                                                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authorised** | The payment was successful.                                                                                                                               | Inform the shopper that the payment has been successful. If you are using [manual capture](/online-payments/capture#manual-capture), you also need to [capture](/online-payments/capture) the payment. |
| **Cancelled**  | The shopper cancelled the payment.                                                                                                                        | Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.                                                                                        |
| **Error**      | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment.                                                                                                                                   |
| **Refused**    | The payment was refused. For more information, check the [`refusalReason` ](/development-resources/refusal-reasons)field.                                 | Ask the shopper to try the payment again using a different payment method.                                                                                                                             |

## Test and go live

To test Titres-restaurant payments, you must get test credentials directly from the meal voucher issuer (Bimpli, Sodexo, or Up Déjeuner).

Before you can accept live payments, you must contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to activate Titres-restaurant in your live environment.

## See also

* [API-only integration guide](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20only)
* [Webhooks](/development-resources/webhooks)
* [API Explorer](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview)
