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

---

## Endpoints

### Generate a payment link

`POST https://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

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checkout_external_id` | String | yes |  | Merchant-unique ID linking the payment request to your order. Replaces the deprecated cart_id |
| `order_number` | String | yes |  | Human-readable order number, unique per day or per service |
| `amount` | Integer | yes |  | Amount to collect, in cents. Minimum 100 (1,00 €) |
| `return_url_success` | String | yes |  | HTTPS URL to redirect to on successful payment |
| `return_url_cancelled` | String | yes |  | HTTPS URL to redirect to if the payment is cancelled |
| `gift_amount` | Integer | no |  | 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_capture` | Boolean | no | true | true: funds collected instantly. false: transactions are pre-authorised and captured via /capture_transactions/ or the daily script |
| `capture_min_delay` | Integer | no | 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_source` | String | no | ecommerce | One of pay_at_table, click_and_collect, delivery, ecommerce |
| `amount_without_tax` | Integer | no |  | Amount excluding tax (excluding gift_amount) |
| `tax_amount` | Integer | no |  | Tax amount (excluding gift_amount) |
| `webhook_url` | String | no |  | HTTPS URL for webhook notifications |
| `message` | String | no |  | Additional message shown on the payment page |
| `datetime` | String | no |  | Datetime of the checkout creation |
| `currency` | String | no |  | ISO 4217 code (eg EUR) |
| `vendor` | Vendor | no |  | Vendor details |
| `customer` | Customer | no |  | Customer details, required for share_by_email / share_by_sms |
| `items` | Array of Item | no |  | Basket lines, required for meal-voucher eligibility rules |
| `reference` | String | no |  | Additional reference |
| `client_reference` | String | no |  | Client reference |
| `features` | Feature | no |  | Feature toggles (tips, meal vouchers, link sharing) |
| `external_order_id` | String | no |  | Your order ID, echoed back in the checkout payload |
| `external_order_number` | String | no |  | Human-readable order number, echoed back. Only used with checkout_external_id |
| `external_table_number` | String | no |  | Table number (eg Pay at Table). Only used with checkout_external_id |
| `marketplace` | Marketplace | no |  | Split the payment across beneficiaries; ventilation amounts must sum to amount |

#### Request

_Python (docs)_
```python
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_
```bash
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"
}'
```

_Node_
```javascript
(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);
})();
```

_Python_
```python
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

`POST https://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

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checkout_external_id` | String | yes |  | Checkout to cancel |

#### Request

_JSON_
```json
{ "checkout_external_id": "order_001" }
```

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

_Node_
```javascript
(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);
})();
```

_Python_
```python
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

`POST https://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

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checkout_external_id` | String | yes |  | Checkout to capture |
| `amount_to_capture` | Integer | no |  | 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

_JSON_
```json
{
  "checkout_external_id": "order_001",
  "amount_to_capture": 2500
}
```

_cURL_
```bash
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
}'
```

_Node_
```javascript
(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);
})();
```

_Python_
```python
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_
```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

`POST https://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

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checkout_external_id` | String | yes |  | Checkout to read |

#### Request

_JSON_
```json
{ "checkout_external_id": "order_001" }
```

_cURL_
```bash
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" }'
```

_Node_
```javascript
(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);
})();
```

_Python_
```python
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_
```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"
      }
    ]
  }
}
```

## Other

### 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).

```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"
    }
  ]
}
```

#### Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| action | String | The action that triggered this webhook. Webhook only |
| reason | String | Additional context (eg cancellation reason). Usually empty when the action was triggered by an endpoint call |
| checkout_external_id | String | The checkout_external_id you provided in the original request |
| cart_id | String | Deprecated alias of checkout_external_id |
| external_order_id | String | Your order ID, echoed back |
| external_order_number | String | Human-readable order number, echoed back |
| external_table_number | String | Table number, echoed back |
| payment_link | String | The payment link of this checkout |
| requested_amount | Integer | Total requested: amount plus gift_amount if used, in cents |
| asked_amount | Integer | The original amount (excluding gift_amount). Differs from requested_amount when a partial capture was done or a gift_amount was used |
| paid_amount | Integer | Total paid by the customer, in cents |
| service_fee | Integer | Service fee, in cents |
| gift_amount | Integer | Total tip left by the customer, in cents |
| status | String | pending, ok, authorised, ko |
| transactions | Array of Transaction | The payments attached to this checkout |

---

### The Transaction object

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

```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"
}
```

#### Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| transaction_id | String | Unique ID of this transaction |
| total_amount | Integer | Amount paid in cents |
| gift_amount | Integer | Tip carried by this transaction, in cents |
| currency_code | String | ISO 4217 code |
| date_of_payment | String | YYYY-MM-DD HH:MM:SS, GMT |
| gateway | String | Gateway used for this transaction |
| issuer | String | Card issuer name |
| pan | String | First and last digits of the card, joined by asterisks |
| status | String | Transaction status |

---

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

```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"
  }
}
```

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| first_name | String | yes | First name |
| last_name | String | yes | Last name |
| email | String | no | Email (required for share_by_email) |
| telephone | String | no | International format starting with + (required for share_by_sms) |
| address | String | no | Address |
| city | String | no | City |
| postcode | String | no | Postcode |

---

### The Feature object

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

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

#### Attributes

| Attribute | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| tips | Boolean | no | true | Whether tips are active on the payment page |
| customer_contacts | Boolean | no | true | Whether company clients are active |
| meal_vouchers | Boolean | no | true | Whether meal vouchers are active |
| share_by_email | Boolean | no | false | Send the payment link by email; requires a Customer with an email. Only one of email/SMS per request |
| share_by_sms | Boolean | no | false | Send the payment link by SMS; requires a Customer with a telephone. Only one of email/SMS per request |

---

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

```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 }
    }
  ]
}
```

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| name | String | yes | Item name |
| total_amount | Integer | yes | Total amount for the item, in cents |
| total_amount_without_tax | Integer | no | Amount without tax |
| category | String | no | Item category |
| eligible_titre_restaurant | Boolean | no | Meal-voucher eligibility |
| free_note | String | no | Free-form note |
| quantity | Integer | no | Quantity |
| unit_price | Integer | no | Unit price in cents |
| unit_price_without_tax | Integer | no | Unit price without tax |
| tax | Tax | no | Tax breakdown for this item |
| items | Array | no | Nested items |

---

### The Tax object

Tax breakdown attached to an Item.

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

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| amount | Integer | yes | Tax amount in cents |
| rate | Integer | yes | Tax rate as a decimal integer (eg 20 for 20%) |

---

### The Vendor object

Identifies the merchant and the software behind the checkout.

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

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| software_name | String | no | Software name |
| software_version | String | no | Software version |

---

### The Store object

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

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

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| store_id | String | yes | Store identifier |
| address | Address | no | Store address |

---

### The Address object

Postal address, nested in the Store object.

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

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| address | String | yes | Street address |
| city | String | yes | City |
| postcode | String | yes | Postcode |

---

### The Marketplace object

Splits a payment across several beneficiaries. See [Marketplace ventilation](https://app.notion.com/p/3bc9a8f4fd9a81e38611f1801e7b4a1f) and [Foodcourt ventilation](https://app.notion.com/p/3bc9a8f4fd9a818eab8bd10c906fd69d) for the onboarding and the accounting side.

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

#### Attributes

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| ventilations | Array | yes | 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 |

---

### Related pages

[Untitled](https://app.notion.com/p/3bc9a8f4fd9a81f393d1ec78c8b679d1)

[Marketplace ventilation](https://app.notion.com/p/3bc9a8f4fd9a81e38611f1801e7b4a1f)

[Foodcourt ventilation](https://app.notion.com/p/3bc9a8f4fd9a818eab8bd10c906fd69d)

[Webhooks Management](https://app.notion.com/p/3bc9a8f4fd9a81b582ace5b88b72adf0)