Online payment: Ecommerce API

Overview

The Ecommerce API lets you generate a payment link, capture a payment (in full or in part), cancel a link, and read the current state of a checkout. You create a link for an order, redirect your customer to Yavin's secure checkout to pay by bank card (including American Express, with 3-D Secure and co-badge selection handled for you) or by meal voucher (Conecs, Swile, Edenred), and you are notified of the result by webhook. Choose it for any online payment: ecommerce, Click & Collect, Order & Pay or Pay at Table via QR code.

At a glance

Base URL	Production: `https://api.yavin.com/api/v5/ecommerce`. Sandbox: `https://api.sandbox.yavin.com/api/v5/ecommerce`
Authentication	API key in the `Yavin-Secret` header
Naming convention	Input accepts both camelCase and snake_case (`checkoutExternalId` and `checkout_external_id` both work). Responses use snake_case, except the query params appended to your return URLs which stay camelCase (`cartId`, `status`) for backwards compatibility
Current version	`v5`. New integrations must use `checkout_external_id` (the deprecated `cart_id` is only a backwards-compatible alias) and send `order_number`
Result delivery	Asynchronous: webhook on every checkout event, plus a customer redirect to your return URLs

Endpoints

Endpoint	Method	Purpose
`/generate_link/`	POST	Create a checkout and get a payment link
`/cancel_link/`	POST	Cancel a checkout
`/capture_transactions/`	POST	Capture authorised transactions (deferred capture)
`/get_cart_information/`	POST	Read the current state of a checkout

Before you start

Checkout. A checkout represents a single payment request, initiated by /generate_link/. It can contain one or more transactions: a customer can pay part with a meal voucher and top up the rest with a card. The checkout payload returned by most endpoints and by the webhook is documented as The Checkout object at the end of this page.

Checkout statuses. There is no 'failed' status: the customer can always retry on the payment page.

Status	Meaning
`pending`	Awaiting payment
`ok`	Fully paid and captured
`authorised`	Paid, but one or more transactions still require capturing
`ko`	The checkout has been cancelled

Amounts. Always integers in cents, always positive. Minimum checkout amount: 100 (1,00 €).

Sandbox. On the sandbox environment (api.sandbox.yavin.com), the payment page uses no test cards: the payment is validated as soon as the customer clicks Pay.

Payment link lifetime

Unused links (no payment attached) stay active for a maximum of 72 hours, then the checkout and the link are cancelled
Partially paid checkouts are systematically cancelled by the daily script, so funds are released back to the customer (particularly important for meal vouchers, which have hard spending limits)
If a payment is still needed after a link has been cancelled, generate a new link via /generate_link/

Deferred capture (is_instant_capture = false). Every day around 04:00 UTC a script:

Captures all transactions of fully paid checkouts with status authorised, once their capture_min_delay has elapsed
Cancels all transactions of partially paid checkouts (status pending), releasing funds back to the customers

Tips on multi-payment checkouts. A tip is added on top of the order and the order is paid first: on each payment, the order portion is covered first, and the tip is taken only from whatever room remains on that transaction. The tip therefore lands on whichever transaction still has capacity once the order is covered (typically the final top-up), not necessarily the first method. Each transaction reports its own gift_amount; the checkout-level gift_amount is the total.

Example. A 26 € checkout with a 1 € tip (27 € total) is paid 25 € by meal voucher, then 2 € by card. The voucher is capped at 25 € and spends it all on the order, so it carries no tip (gift_amount: 0); the card transaction covers the last 1 € of the order and the 1 € tip (gift_amount: 100).

A meal-voucher transaction can carry a tip only if the order and the tip both fit under its legal 25 € cap. If the order alone fills the cap, the tip moves to the next payment method.

Webhooks

If a webhook_url is provided at link generation, it is called via POST whenever an action takes place on the checkout. The body is a Checkout object with an extra action field.

Action	Meaning
`payment_received`	A payment was made, for part or all of the requested amount
`capture`	All transactions captured, checkout status is now `ok`. Under instant capture you receive `capture`; on a multi-payment checkout, the last transaction reports `capture` rather than `payment_received`
`cancel`	The checkout was cancelled

Yavin expects an HTTP 200 acknowledgement. Otherwise the webhook is retried with increasing back-off, up to 5 retries, then Yavin gives up. Return the 200 quickly and process asynchronously: slow responses count as failures and trigger retries.

Generate a payment link

POSThttps://api.yavin.com/api/v5/ecommerce/generate_link/

Creates a checkout and returns the payment link to which you redirect your customer.

Return URLs must be HTTPS. Custom schemes like appid:// are rejected: they do not prove ownership of the recipient, they can be intercepted by another application, and they do not meet the security requirements of banking and PSP actors. For automatic return into a mobile app, use Universal Links (iOS) or App Links (Android): both rely on HTTPS URLs, guarantee domain control, and open the app securely with a web fallback.

Parameters

checkout_external_idStringrequired

Merchant-unique ID linking the payment request to your order. Replaces the deprecated cart_id

order_numberStringrequired

Human-readable order number, unique per day or per service

amountIntegerrequired

Amount to collect, in cents. Minimum 100 (1,00 €)

return_url_successStringrequired

HTTPS URL to redirect to on successful payment

return_url_cancelledStringrequired

HTTPS URL to redirect to if the payment is cancelled

gift_amountInteger

Tip collected on your platform (not via our built-in tips feature), excluded from amount, so we report the correct turnover vs tips split in the backoffice

is_instant_captureBooleandefault true

true: funds collected instantly. false: transactions are pre-authorised and captured via /capture_transactions/ or the daily script

capture_min_delayIntegerdefault 0

Minimum hours to wait after full payment before the daily script captures. Only relevant with is_instant_capture = false. Accepted: 0 to 72 (higher values are clamped to 72)

order_sourceStringdefault ecommerce

One of pay_at_table, click_and_collect, delivery, ecommerce

amount_without_taxInteger

Amount excluding tax (excluding gift_amount)

tax_amountInteger

Tax amount (excluding gift_amount)

webhook_urlString

HTTPS URL for webhook notifications

messageString

Additional message shown on the payment page

datetimeString

Datetime of the checkout creation

currencyString

ISO 4217 code (eg EUR)

vendorVendor

Vendor details

Show Vendor parameters

vendor.software_nameString: Software name
vendor.software_versionString: Software version

customerCustomer

Customer details, required for share_by_email / share_by_sms

Show Customer parameters

customer.first_nameStringrequired: First name
customer.last_nameStringrequired: Last name
customer.emailString: Email (required for share_by_email)
customer.telephoneString: International format starting with + (required for share_by_sms)
customer.addressString: Address
customer.cityString: City
customer.postcodeString: Postcode

itemsArray of Item

Basket lines, required for meal-voucher eligibility rules

Show Item parameters

items.nameStringrequired

Item name

items.total_amountIntegerrequired

Total amount for the item, in cents

items.total_amount_without_taxInteger

Amount without tax

items.categoryString

Item category

items.eligible_titre_restaurantBoolean

Meal-voucher eligibility

items.free_noteString

Free-form note

items.quantityInteger

Quantity

items.unit_priceInteger

Unit price in cents

items.unit_price_without_taxInteger

Unit price without tax

items.taxTax

Tax breakdown for this item

Show Tax parameters

items.tax.amountIntegerrequired: Tax amount in cents
items.tax.rateIntegerrequired: Tax rate as a decimal integer (eg 20 for 20%)

items.itemsArray

Nested items

referenceString

Additional reference

client_referenceString

Client reference

featuresFeature

Feature toggles (tips, meal vouchers, link sharing)

Show Feature parameters

features.tipsBooleandefault true: Whether tips are active on the payment page
features.customer_contactsBooleandefault true: Whether company clients are active
features.meal_vouchersBooleandefault true: Whether meal vouchers are active
features.share_by_emailBooleandefault false: Send the payment link by email; requires a Customer with an email. Only one of email/SMS per request
features.share_by_smsBooleandefault false: Send the payment link by SMS; requires a Customer with a telephone. Only one of email/SMS per request

external_order_idString

Your order ID, echoed back in the checkout payload

external_order_numberString

Human-readable order number, echoed back. Only used with checkout_external_id

external_table_numberString

Table number (eg Pay at Table). Only used with checkout_external_id

marketplaceMarketplace

Split the payment across beneficiaries; ventilation amounts must sum to amount

Show Marketplace parameters

marketplace.ventilationsArrayrequired: List of objects, each with public_account_id (String) and ttc_amount (Integer, in cents). The ttc_amount values must sum to the checkout amount

Request

url = 'https://api.yavin.com/api/v5/ecommerce/generate_link/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}
params = {
  "checkout_external_id": "my_custom_checkout_id_001",
  "order_number": "A-1042",
  "amount": 3000,
  "amount_without_tax": 2400,
  "tax_amount": 600,
  "return_url_success": "https://mydomain.com/ecommerce/success",
  "return_url_cancelled": "https://mydomain.com/ecommerce/cancelled",
  "is_instant_capture": false,
  "capture_min_delay": 8,
  "order_source": "pay_at_table",
  "webhook_url": "https://mydomain.com/ecommerce/webhook",
  "message": "Thank you for shopping with us",
  "datetime": "2023-10-16 14:35:15",
  "currency": "EUR",
  "reference": "Luke",
  "client_reference": "aoj239uvn2ca"
}

curl -X POST 'https://api.yavin.com/api/v5/ecommerce/generate_link/' \
  -H 'Yavin-Secret: YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "checkout_external_id": "my_custom_checkout_id_001",
  "order_number": "A-1042",
  "amount": 3000,
  "amount_without_tax": 2400,
  "tax_amount": 600,
  "return_url_success": "https://mydomain.com/ecommerce/success",
  "return_url_cancelled": "https://mydomain.com/ecommerce/cancelled",
  "is_instant_capture": false,
  "capture_min_delay": 8,
  "order_source": "pay_at_table",
  "webhook_url": "https://mydomain.com/ecommerce/webhook",
  "message": "Thank you for shopping with us",
  "datetime": "2023-10-16 14:35:15",
  "currency": "EUR",
  "reference": "Luke",
  "client_reference": "aoj239uvn2ca"
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/ecommerce/generate_link/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({
      "checkout_external_id": "my_custom_checkout_id_001",
      "order_number": "A-1042",
      "amount": 3000,
      "amount_without_tax": 2400,
      "tax_amount": 600,
      "return_url_success": "https://mydomain.com/ecommerce/success",
      "return_url_cancelled": "https://mydomain.com/ecommerce/cancelled",
      "is_instant_capture": false,
      "capture_min_delay": 8,
      "order_source": "pay_at_table",
      "webhook_url": "https://mydomain.com/ecommerce/webhook",
      "message": "Thank you for shopping with us",
      "datetime": "2023-10-16 14:35:15",
      "currency": "EUR",
      "reference": "Luke",
      "client_reference": "aoj239uvn2ca"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import os
import requests

headers = {
    "Content-Type": "application/json",
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

payload = {
  "checkout_external_id": "my_custom_checkout_id_001",
  "order_number": "A-1042",
  "amount": 3000,
  "amount_without_tax": 2400,
  "tax_amount": 600,
  "return_url_success": "https://mydomain.com/ecommerce/success",
  "return_url_cancelled": "https://mydomain.com/ecommerce/cancelled",
  "is_instant_capture": False,
  "capture_min_delay": 8,
  "order_source": "pay_at_table",
  "webhook_url": "https://mydomain.com/ecommerce/webhook",
  "message": "Thank you for shopping with us",
  "datetime": "2023-10-16 14:35:15",
  "currency": "EUR",
  "reference": "Luke",
  "client_reference": "aoj239uvn2ca"
}

response = requests.post(
    "https://api.yavin.com/api/v5/ecommerce/generate_link/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
data = response.json()

Response

On success, the response carries payment_link (forward your customer to it), plus share_link when email/SMS sharing was requested (eg { "status": "success", "message": null }).

On validation error, the response carries errors, a JSON object keyed by field, eg "checkout_external_id": ["This checkout_external_id already exists"]:

This checkout_external_id already exists: a checkout already exists with this ID for your company
This field is required.: a required field (eg amount, order_number) is missing
Only https links are supported: a return URL or the webhook URL was not HTTPS

Timeout. Set a client-side timeout of at least 30 seconds, so a slow response does not lead you to generate a duplicate link.

Customer redirect. Once the checkout is fully paid or cancelled, the customer is redirected via GET to your return_url_success or return_url_cancelled, with cartId and status in the query params (kept camelCase for backwards compatibility; cartId carries your checkout_external_id):

https://mydomain.com/ecommerce/success?cartId=abcde12345&status=ok

There is no failed-payment redirect: customers can always retry. On cancellation, return_url_cancelled is invoked.

Never confirm an order on the browser redirect alone. The return URL is a client-side GET: it can be skipped (browser closed before redirect) or forged (parameters are visible to the customer). Always confirm on a server-side source: the webhook_url notification or a /get_cart_information/ call.

Cancel a link

POSThttps://api.yavin.com/api/v5/ecommerce/cancel_link/

Cancels a checkout. Possible only if the checkout is still cancellable: not paid in full, not already cancelled, and containing no non-cancellable transaction.

Parameters

checkout_external_idStringrequired: Checkout to cancel

Request

{ "checkout_external_id": "order_001" }

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/ecommerce/cancel_link/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({ "checkout_external_id": "order_001" }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import os
import requests

headers = {
    "Content-Type": "application/json",
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

payload = { "checkout_external_id": "order_001" }

response = requests.post(
    "https://api.yavin.com/api/v5/ecommerce/cancel_link/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
data = response.json()

Response

On success, a confirmation message plus webhook_data, a Checkout object with its transactions. On failure, an error among:

Cart has already been paid in full: checkout status is ok
Cart has already been cancelled: checkout status is ko
Cart contains a non-cancellable transaction: one or more transactions cannot be cancelled

The message and error strings are returned verbatim by the API and still use the word "cart" (legacy of the deprecated cart_id).

Capture transactions

POSThttps://api.yavin.com/api/v5/ecommerce/capture_transactions/

Captures the transactions of a checkout, in full or in part. Only available for links generated with is_instant_capture = false.

Partial capture is supported only when every transaction on the checkout allows it. Some meal-voucher issuers do not support partial capture: in that case the full authorised amount is captured instead.

Parameters

checkout_external_idStringrequired: Checkout to capture
amount_to_captureInteger: Amount to capture in cents, up to the originally requested amount (excluding gift_amount). 0 cancels the link, but prefer /cancel_link/ for that

Request

{
  "checkout_external_id": "order_001",
  "amount_to_capture": 2500
}

curl -X POST 'https://api.yavin.com/api/v5/ecommerce/capture_transactions/' \
  -H 'Yavin-Secret: YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "checkout_external_id": "order_001",
  "amount_to_capture": 2500
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/ecommerce/capture_transactions/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({
      "checkout_external_id": "order_001",
      "amount_to_capture": 2500
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import os
import requests

headers = {
    "Content-Type": "application/json",
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

payload = {
  "checkout_external_id": "order_001",
  "amount_to_capture": 2500
}

response = requests.post(
    "https://api.yavin.com/api/v5/ecommerce/capture_transactions/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
data = response.json()

Response

JSON

{
  "data": {
    "checkout_external_id": "order_001",
    "payment_link": "https://pay.yavin.com/p/abc123",
    "requested_amount": 3000,
    "asked_amount": 3000,
    "paid_amount": 2500,
    "service_fee": 0,
    "status": "ok",
    "transactions": [
      {
        "transaction_id": "trs_7f3a92c5",
        "total_amount": 2500,
        "gift_amount": 0,
        "currency_code": "EUR",
        "date_of_payment": "2026-06-30 14:35:15",
        "gateway": "NEPTING_ECOMMERCE",
        "issuer": "VISA",
        "pan": "4970********0001",
        "status": "ok"
      }
    ]
  }
}

Get checkout information

POSThttps://api.yavin.com/api/v5/ecommerce/get_cart_information/

Reads the current state of a checkout. Use it to reconcile, or to confirm a payment when you need certainty beyond the webhook.

The endpoint path is get_cart_information, a fixed identifier kept for backwards compatibility. The object it returns is the checkout payload.

Parameters

checkout_external_idStringrequired: Checkout to read

Request

{ "checkout_external_id": "order_001" }

curl -X POST 'https://api.yavin.com/api/v5/ecommerce/get_cart_information/' \
  -H 'Yavin-Secret: YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "checkout_external_id": "order_001" }'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/ecommerce/get_cart_information/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({ "checkout_external_id": "order_001" }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import os
import requests

headers = {
    "Content-Type": "application/json",
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

payload = { "checkout_external_id": "order_001" }

response = requests.post(
    "https://api.yavin.com/api/v5/ecommerce/get_cart_information/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
data = response.json()

Response

JSON

{
  "data": {
    "checkout_external_id": "order_001",
    "payment_link": "https://pay.yavin.com/p/abc123",
    "requested_amount": 3000,
    "asked_amount": 3000,
    "paid_amount": 3000,
    "service_fee": 0,
    "status": "ok",
    "transactions": [
      {
        "transaction_id": "trs_7f3a92c5",
        "total_amount": 3000,
        "gift_amount": 0,
        "currency_code": "EUR",
        "date_of_payment": "2026-06-30 14:35:15",
        "gateway": "NEPTING_ECOMMERCE",
        "issuer": "VISA",
        "pan": "4970********0001",
        "status": "ok"
      }
    ]
  }
}

The Checkout object

The central object of this API. Sent to your webhook on every event, and returned by /cancel_link/ (as webhook_data), /capture_transactions/ and /get_cart_information/ (as data).

Attributes

actionString

The action that triggered this webhook. Webhook only

reasonString

Additional context (eg cancellation reason). Usually empty when the action was triggered by an endpoint call

checkout_external_idString

The checkout_external_id you provided in the original request

cart_idString

Deprecated alias of checkout_external_id

external_order_idString

Your order ID, echoed back

external_order_numberString

Human-readable order number, echoed back

external_table_numberString

Table number, echoed back

payment_linkString

The payment link of this checkout

requested_amountInteger

Total requested: amount plus gift_amount if used, in cents

asked_amountInteger

The original amount (excluding gift_amount). Differs from requested_amount when a partial capture was done or a gift_amount was used

paid_amountInteger

Total paid by the customer, in cents

service_feeInteger

Service fee, in cents

gift_amountInteger

Total tip left by the customer, in cents

statusString

pending, ok, authorised, ko

transactionsArray of Transaction

The payments attached to this checkout

Show Transaction parameters

transactions.transaction_idString: Unique ID of this transaction
transactions.total_amountInteger: Amount paid in cents
transactions.gift_amountInteger: Tip carried by this transaction, in cents
transactions.currency_codeString: ISO 4217 code
transactions.date_of_paymentString: YYYY-MM-DD HH:MM:SS, GMT
transactions.gatewayString: Gateway used for this transaction
transactions.issuerString: Card issuer name
transactions.panString: First and last digits of the card, joined by asterisks
transactions.statusString: Transaction status

JSON

{
  "action": "payment_received",
  "reason": "",
  "checkout_external_id": "order_001",
  "cart_id": "order_001",
  "external_order_id": "order_uuid_123",
  "external_order_number": "A-1042",
  "external_table_number": "12",
  "payment_link": "https://pay.yavin.com/p/abc123",
  "requested_amount": 2700,
  "asked_amount": 2600,
  "paid_amount": 2700,
  "service_fee": 0,
  "gift_amount": 100,
  "status": "ok",
  "transactions": [
    {
      "transaction_id": "trs_1a2b3c4d",
      "total_amount": 2500,
      "gift_amount": 0,
      "currency_code": "EUR",
      "date_of_payment": "2026-06-30 14:35:15",
      "gateway": "CONECS",
      "issuer": "SWILE",
      "pan": "5061********1234",
      "status": "ok"
    },
    {
      "transaction_id": "trs_7f3a92c5",
      "total_amount": 200,
      "gift_amount": 100,
      "currency_code": "EUR",
      "date_of_payment": "2026-06-30 14:36:02",
      "gateway": "NEPTING_ECOMMERCE",
      "issuer": "VISA",
      "pan": "4970********0001",
      "status": "ok"
    }
  ]
}

The Transaction object

One payment attached to a checkout. A checkout can carry several, for example a meal voucher plus a card top-up.

Attributes

transaction_idString: Unique ID of this transaction
total_amountInteger: Amount paid in cents
gift_amountInteger: Tip carried by this transaction, in cents
currency_codeString: ISO 4217 code
date_of_paymentString: YYYY-MM-DD HH:MM:SS, GMT
gatewayString: Gateway used for this transaction
issuerString: Card issuer name
panString: First and last digits of the card, joined by asterisks
statusString: Transaction status

JSON

{
  "transaction_id": "trs_7f3a92c5",
  "total_amount": 2500,
  "gift_amount": 0,
  "currency_code": "EUR",
  "date_of_payment": "2026-06-30 14:35:15",
  "gateway": "NEPTING_ECOMMERCE",
  "issuer": "VISA",
  "pan": "4970********0001",
  "status": "ok"
}

The Customer object

Customer details attached to the checkout. Required when you ask Yavin to send the payment link by email or SMS through the Feature object.

Attributes

first_nameStringrequired: First name
last_nameStringrequired: Last name
emailString: Email (required for share_by_email)
telephoneString: International format starting with + (required for share_by_sms)
addressString: Address
cityString: City
postcodeString: Postcode

JSON

{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@yavin.com",
    "telephone": "+33612345678",
    "address": "66 Av. des Champs-Élysées",
    "city": "Paris",
    "postcode": "75008"
  }
}

The Feature object

Toggles what the payment page offers, and whether Yavin sends the link to the customer for you.

Attributes

tipsBooleandefault true: Whether tips are active on the payment page
customer_contactsBooleandefault true: Whether company clients are active
meal_vouchersBooleandefault true: Whether meal vouchers are active
share_by_emailBooleandefault false: Send the payment link by email; requires a Customer with an email. Only one of email/SMS per request
share_by_smsBooleandefault false: Send the payment link by SMS; requires a Customer with a telephone. Only one of email/SMS per request

JSON

{
  "features": {
    "tips": true,
    "meal_vouchers": true,
    "customer_contacts": false,
    "share_by_email": true,
    "share_by_sms": false
  }
}

The Item object

Basket lines attached to the checkout. Items drive the meal-voucher eligibility rules, so send them whenever the merchant accepts meal vouchers.

Attributes

nameStringrequired

Item name

total_amountIntegerrequired

Total amount for the item, in cents

total_amount_without_taxInteger

Amount without tax

categoryString

Item category

eligible_titre_restaurantBoolean

Meal-voucher eligibility

free_noteString

Free-form note

quantityInteger

Quantity

unit_priceInteger

Unit price in cents

unit_price_without_taxInteger

Unit price without tax

taxTax

Tax breakdown for this item

Show Tax parameters

tax.amountIntegerrequired: Tax amount in cents
tax.rateIntegerrequired: Tax rate as a decimal integer (eg 20 for 20%)

itemsArray

Nested items

JSON

{
  "items": [
    {
      "name": "Menu midi",
      "total_amount": 1590,
      "total_amount_without_tax": 1325,
      "quantity": 1,
      "unit_price": 1590,
      "category": "food",
      "eligible_titre_restaurant": true,
      "tax": { "amount": 265, "rate": 20 }
    }
  ]
}

The Tax object

Tax breakdown attached to an Item.

Attributes

amountIntegerrequired: Tax amount in cents
rateIntegerrequired: Tax rate as a decimal integer (eg 20 for 20%)

JSON

{
  "tax": { "amount": 265, "rate": 20 }
}

The Vendor object

Identifies the merchant and the software behind the checkout.

Attributes

software_nameString: Software name
software_versionString: Software version

JSON

{
  "vendor": {
    "software_name": "my_software",
    "software_version": "1.0"
      }
}

The Store object

The physical store behind the checkout, nested in the Vendor object.

Attributes

store_idStringrequired

Store identifier

addressAddress

Store address

Show Address parameters

address.addressStringrequired: Street address
address.cityStringrequired: City
address.postcodeStringrequired: Postcode

JSON

{
  "store": {
    "store_id": "store_8",
    "address": {
      "address": "66 Av. des Champs-Élysées",
      "city": "Paris",
      "postcode": "75008"
    }
  }
}

The Address object

Postal address, nested in the Store object.

Attributes

addressStringrequired: Street address
cityStringrequired: City
postcodeStringrequired: Postcode

JSON

{
  "address": {
    "address": "66 Av. des Champs-Élysées",
    "city": "Paris",
    "postcode": "75008"
  }
}

The Marketplace object

Splits a payment across several beneficiaries. See Marketplace ventilation and Foodcourt ventilation for the onboarding and the accounting side.

Attributes

ventilationsArrayrequired: List of objects, each with public_account_id (String) and ttc_amount (Integer, in cents). The ttc_amount values must sum to the checkout amount

JSON

{
  "marketplace": {
    "ventilations": [
      { "public_account_id": "azertyuiop", "ttc_amount": 1000 },
      { "public_account_id": "qsdfghjklm", "ttc_amount": 2000 }
    ]
  }
}

Untitled

Marketplace ventilation

Foodcourt ventilation

Webhooks Management

Online payment: Ecommerce API

Overview

At a glance

Endpoints

Before you start

Webhooks

Generate a payment link

Parameters

Request

Response

Cancel a link

Parameters

Request

Response

Capture transactions

Parameters

Request

Response

Get checkout information

Parameters

Request

Response

The Checkout object

Attributes

The Transaction object

Attributes

The Customer object

Attributes

The Feature object

Attributes

The Item object

Attributes

The Tax object

Attributes

The Vendor object

Attributes

The Store object

Attributes

The Address object

Attributes

The Marketplace object

Attributes

Related pages