--- 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(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 { { "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)