Paiement en ligne : E-commerce API

Présentation

L'API Ecommerce vous permet de générer un lien de paiement, de capturer un paiement (en totalité ou en partie), d'annuler un lien et de consulter l'état actuel d'un checkout.

Vous créez un lien pour une commande
Vous redirigez votre client vers le checkout sécurisé de Yavin pour qu'il paie par carte bancaire (y compris American Express, avec 3-D Secure et la sélection de la marque en cas de co-badge gérés pour vous) ou par titre-restaurant (Conecs, Swile, Edenred)
Vous êtes informé du résultat par webhook

Choisissez-la pour tout paiement en ligne : e-commerce, Click & Collect, Order & Pay ou Pay at Table via QR code.

En bref

URL de base	Production : `https://api.yavin.com/api/v5/ecommerce`. Sandbox : `https://api.sandbox.yavin.com/api/v5/ecommerce`
Authentification	Clé d'API dans l'en-tête `Yavin-Secret`
Convention de nommage	L'entrée accepte à la fois le camelCase et le snake_case (`checkoutExternalId` et `checkout_external_id` fonctionnent tous deux). Les réponses utilisent le snake_case, sauf les paramètres de requête ajoutés à vos URL de retour, qui restent en camelCase (`cartId`, `status`) pour des raisons de rétrocompatibilité
Version actuelle	`v5`. Les nouvelles intégrations doivent utiliser `checkout_external_id` (`cart_id`, déprécié, n'est qu'un alias conservé pour la rétrocompatibilité) et envoyer `order_number`
Remise des résultats	Asynchrone : webhook à chaque événement du checkout, ainsi qu'une redirection du client vers vos URL de retour

Endpoints

Endpoint	Méthode	Usage
`/generate_link/`	POST	Créer un checkout et obtenir un lien de paiement
`/cancel_link/`	POST	Annuler un checkout
`/capture_transactions/`	POST	Capturer des transactions autorisées (capture différée)
`/get_cart_information/`	POST	Consulter l'état actuel d'un checkout

Avant de commencer

Checkout

Un checkout représente une demande de paiement unique, initiée par /generate_link/. Il peut contenir une ou plusieurs transactions : un client peut payer une partie avec un titre-restaurant et compléter le reste par carte. Le payload du checkout renvoyé par la plupart des endpoints et par le webhook est documenté dans la section The Checkout object, à la fin de cette page.

Statuts du checkout

Il n'existe pas de statut « failed » : le client peut toujours réessayer sur la page de paiement.

Statut	Signification
`pending`	En attente de paiement
`ok`	Entièrement payé et capturé
`authorised`	Payé, mais une ou plusieurs transactions doivent encore être capturées
`ko`	Le checkout a été annulé

Montants

Toujours des entiers en centimes, toujours positifs. amount minimum du checkout : 100 (1,00 €).

Sandbox

Sur l'environnement sandbox (api.sandbox.yavin.com), la page de paiement n'utilise aucune carte de test : le paiement est validé dès que le client clique sur Payer.

Durée de vie du lien de paiement

Les liens inutilisés (sans paiement associé) restent actifs au maximum 72 heures, puis le checkout et le lien sont annulés
Les checkouts partiellement payés sont systématiquement annulés par le script quotidien, afin que les fonds soient restitués au client (point particulièrement important pour les titres-restaurant, dont les plafonds de dépense sont stricts)
Si un paiement reste nécessaire après l'annulation d'un lien, générez un nouveau lien via /generate_link/

Capture différée

Lorsque is_instant_capture = false, chaque jour vers 04:00 UTC, un script :

Capture toutes les transactions des checkouts entièrement payés avec le statut authorised, une fois leur capture_min_delay écoulé
Annule toutes les transactions des checkouts partiellement payés (statut pending), ce qui restitue les fonds aux clients

Conseils pour les checkouts avec paiements multiples

Un pourboire est ajouté en plus de la commande et la commande est payée en premier :

À chaque paiement, la part correspondant à la commande est couverte en premier, et le pourboire n'est prélevé que sur la marge restante de cette transaction
Le pourboire est donc porté par la transaction qui dispose encore de capacité une fois la commande couverte (généralement le dernier complément), et pas nécessairement par le premier moyen de paiement
Chaque transaction indique son propre gift_amount ; le gift_amount au niveau du checkout correspond au total

Exemple. Un checkout de 26 € avec un pourboire de 1 € (27 € au total) est payé 25 € par titre-restaurant, puis 2 € par carte. Le titre-restaurant est plafonné à 25 € et les consacre entièrement à la commande ; il ne porte donc aucun pourboire (gift_amount: 0). La transaction par carte couvre le dernier euro de la commande ainsi que le pourboire de 1 € (gift_amount: 100).

Une transaction par titre-restaurant ne peut porter un pourboire que si la commande et le pourboire tiennent ensemble sous son plafond légal de 25 €. Si la commande seule atteint le plafond, le pourboire est reporté sur le moyen de paiement suivant.

Webhooks

Si un webhook_url est fourni lors de la génération du lien, il est appelé via POST à chaque action effectuée sur le checkout. Le corps de la requête est un objet Checkout avec un champ action supplémentaire.

Action	Signification
`payment_received`	Un paiement a été effectué, pour tout ou partie du montant demandé
`capture`	Toutes les transactions sont capturées, le statut du checkout est désormais `ok`. Avec la capture instantanée, vous recevez `capture` ; sur un checkout multi-paiements, la dernière transaction indique `capture` plutôt que `payment_received`
`cancel`	Le checkout a été annulé

Yavin attend un accusé de réception HTTP 200. Dans le cas contraire, le webhook est renvoyé avec un délai d'attente croissant, jusqu'à 5 nouvelles tentatives, puis Yavin abandonne. Renvoyez rapidement le code 200 et traitez la notification de façon asynchrone : les réponses lentes sont considérées comme des échecs et déclenchent de nouvelles tentatives.

Générer un lien de paiement

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

Crée un checkout et renvoie le lien de paiement vers lequel vous redirigez votre client.

Les URL de retour doivent être en HTTPS. Les schémas personnalisés tels que appid:// sont rejetés :

ils ne prouvent pas l'appartenance du destinataire
ils peuvent être interceptés par une autre application
ils ne répondent pas aux exigences de sécurité des acteurs bancaires et des PSP

Pour un retour automatique dans une application mobile, utilisez les Universal Links (iOS) ou les App Links (Android) : tous deux reposent sur des URL HTTPS, garantissent le contrôle du domaine et ouvrent l'application de façon sécurisée, avec un repli vers le web.

Paramètres

checkout_external_idStringrequis

Identifiant unique côté marchand qui lie la demande de paiement à votre commande. Remplace cart_id, désormais obsolète

order_numberStringrequis

Numéro de commande lisible, unique par jour ou par service

amountIntegerrequis

Montant à encaisser, en centimes. Minimum 100 (1,00 €)

return_url_successStringrequis

URL HTTPS vers laquelle rediriger en cas de paiement réussi

return_url_cancelledStringrequis

URL HTTPS vers laquelle rediriger si le paiement est annulé

gift_amountInteger

Pourboire encaissé sur votre plateforme (et non via notre fonctionnalité de pourboire intégrée), exclu de amount, afin que nous indiquions dans le backoffice la bonne répartition entre chiffre d'affaires et pourboires

is_instant_captureBooleanpar défaut true

true : fonds encaissés immédiatement. false : les transactions sont préautorisées puis capturées via /capture_transactions/ ou le script quotidien

capture_min_delayIntegerpar défaut 0

Nombre minimal d'heures à attendre après le paiement intégral avant que le script quotidien ne procède à la capture. Pertinent uniquement avec is_instant_capture = false. Valeurs acceptées : 0 à 72 (les valeurs supérieures sont ramenées à 72)

order_sourceStringpar défaut ecommerce

L'une des valeurs suivantes : pay_at_table, click_and_collect, delivery, ecommerce

amount_without_taxInteger

Montant hors taxes (hors gift_amount)

tax_amountInteger

Montant de la taxe (hors gift_amount)

webhook_urlString

URL HTTPS pour les notifications webhook

messageString

Message complémentaire affiché sur la page de paiement

datetimeString

Date et heure de création du checkout

currencyString

Code ISO 4217 (par ex. EUR)

vendorVendor

Informations sur le vendeur

Afficher les paramètres de Vendor

vendor.software_nameString: Nom du logiciel
vendor.software_versionString: Version du logiciel

customerCustomer

Informations sur le client, obligatoires pour share_by_email / share_by_sms

Afficher les paramètres de Customer

customer.first_nameStringrequis: Prénom
customer.last_nameStringrequis: Nom
customer.emailString: E-mail (obligatoire pour share_by_email)
customer.telephoneString: Format international commençant par + (obligatoire pour share_by_sms)
customer.addressString: Adresse
customer.cityString: Ville
customer.postcodeString: Code postal

itemsArray of Item

Lignes du panier, obligatoires pour les règles d'éligibilité aux titres-restaurant

Afficher les paramètres de Item

items.nameStringrequis

Nom de l'article

items.total_amountIntegerrequis

Montant total de l'article, en centimes

items.total_amount_without_taxInteger

Montant hors taxes

items.categoryString

Catégorie de l'article

items.eligible_titre_restaurantBoolean

Éligibilité aux titres-restaurant

items.free_noteString

Note libre

items.quantityInteger

Quantité

items.unit_priceInteger

Prix unitaire en centimes

items.unit_price_without_taxInteger

Prix unitaire hors taxes

items.taxTax

Détail des taxes pour cet article

Afficher les paramètres de Tax

items.tax.amountIntegerrequis: Montant de la taxe en centimes
items.tax.rateIntegerrequis: Taux de taxe sous forme d'entier décimal (par ex. 20 pour 20 %)

items.itemsArray

Éléments imbriqués

referenceString

Référence complémentaire

client_referenceString

Référence client

featuresFeature

Options de fonctionnalités (pourboires, titres-restaurant, partage de lien)

Afficher les paramètres de Feature

features.tipsBooleanpar défaut true: Indique si les pourboires sont activés sur la page de paiement
features.customer_contactsBooleanpar défaut true: Indique si les clients entreprise sont activés
features.meal_vouchersBooleanpar défaut true: Indique si les titres-restaurant sont activés
features.share_by_emailBooleanpar défaut false: Envoie le lien de paiement par e-mail ; nécessite un Customer avec une adresse e-mail. Un seul des deux (e-mail ou SMS) par requête
features.share_by_smsBooleanpar défaut false: Envoie le lien de paiement par SMS ; nécessite un Customer avec un numéro de téléphone. Un seul des deux (e-mail ou SMS) par requête

external_order_idString

Votre identifiant de commande, renvoyé tel quel dans le payload du checkout

external_order_numberString

Numéro de commande lisible, renvoyé tel quel. Utilisé uniquement avec checkout_external_id

external_table_numberString

Numéro de table (par ex. Pay at Table). Utilisé uniquement avec checkout_external_id

marketplaceMarketplace

Répartit le paiement entre plusieurs bénéficiaires ; la somme des montants de ventilation doit être égale à amount

Afficher les paramètres de Marketplace

marketplace.ventilationsArrayrequis: Liste d'objets, chacun avec public_account_id (String) et ttc_amount (Integer, en centimes). La somme des valeurs ttc_amount doit être égale à amount de l'encaissement

Requête

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

Réponse

En cas de succès, la réponse contient payment_link (redirigez votre client vers cette URL), ainsi que share_link lorsqu'un partage par e-mail/SMS a été demandé (par ex. { "status": "success", "message": null }).

En cas d'erreur de validation, la réponse contient errors, un objet JSON indexé par champ, par ex. "checkout_external_id": ["This checkout_external_id already exists"] :

This checkout_external_id already exists : un checkout existe déjà avec cet identifiant pour votre société
This field is required. : un champ obligatoire (par ex. amount, order_number) est manquant
Only https links are supported : une URL de retour ou l'URL du webhook n'est pas en HTTPS

Délai d'attente. Définissez un délai d'attente côté client d'au moins 30 secondes, afin qu'une réponse lente ne vous conduise pas à générer un lien en double.

Redirection du client. Lorsque le checkout est entièrement payé ou annulé, le client est redirigé via GET vers votre return_url_success ou return_url_cancelled, avec cartId et status dans les paramètres de requête (conservés en camelCase pour la rétrocompatibilité ; cartId contient votre checkout_external_id) :

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

Il n'existe pas de redirection en cas d'échec de paiement : les clients peuvent toujours réessayer. En cas d'annulation, return_url_cancelled est appelé.

Ne confirmez jamais une commande sur la seule redirection du navigateur. L'URL de retour est un GET côté client : il peut ne pas avoir lieu (navigateur fermé avant la redirection) ou être falsifié (les paramètres sont visibles par le client). Confirmez toujours à partir d'une source côté serveur : la notification webhook_url ou un appel à /get_cart_information/.

Annuler un lien

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

Annule un checkout. Possible uniquement si le checkout est encore annulable : non payé en totalité, pas déjà annulé et ne contenant aucune transaction non annulable.

Paramètres

checkout_external_idStringrequis: Checkout à annuler

Requête

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

Réponse

En cas de succès, une confirmation message ainsi que webhook_data, un objet Checkout avec ses transactions. En cas d'échec, un error parmi :

Cart has already been paid in full : le statut du checkout est ok
Cart has already been cancelled : le statut du checkout est ko
Cart contains a non-cancellable transaction : une ou plusieurs transactions ne peuvent pas être annulées

Les chaînes message et error sont renvoyées telles quelles par l'API et utilisent encore le mot « cart » (héritage de cart_id, désormais obsolète).

Capturer des transactions

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

Capture les transactions d'un checkout, en totalité ou en partie. Disponible uniquement pour les liens générés avec is_instant_capture = false.

La capture partielle n'est prise en charge que si toutes les transactions du checkout l'autorisent. Certains émetteurs de titres-restaurant ne prennent pas en charge la capture partielle : dans ce cas, le montant autorisé est capturé en totalité.

Paramètres

checkout_external_idStringrequis: Checkout à capturer
amount_to_captureInteger: Montant à capturer en centimes, dans la limite du amount demandé initialement (hors gift_amount). 0 annule le lien, mais préférez /cancel_link/ pour cela

Requête

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

Réponse

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

Obtenir les informations d'un checkout

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

Lit l'état actuel d'un checkout. Utilisez-le pour réconcilier, ou pour confirmer un paiement lorsque vous avez besoin d'une certitude au-delà du webhook.

Le chemin de l'endpoint est get_cart_information, un identifiant fixe conservé pour la rétrocompatibilité. L'objet qu'il renvoie est le payload du checkout.

Paramètres

checkout_external_idStringrequis: Checkout à lire

Requête

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

Réponse

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

L'objet Checkout

L'objet central de cette API. Il est envoyé à votre webhook à chaque événement, et renvoyé par /cancel_link/ (sous la forme webhook_data), /capture_transactions/ et /get_cart_information/ (sous la forme data).

Attributs

actionString

L'action qui a déclenché ce webhook. Webhook uniquement

reasonString

Contexte supplémentaire (par ex. motif d'annulation). Généralement vide lorsque l'action a été déclenchée par un appel à un endpoint

checkout_external_idString

Le checkout_external_id que vous avez fourni dans la requête d'origine

cart_idString

Alias obsolète de checkout_external_id

external_order_idString

Votre identifiant de commande, renvoyé tel quel

external_order_numberString

Numéro de commande lisible, renvoyé tel quel

external_table_numberString

Numéro de table, renvoyé tel quel

payment_linkString

Le lien de paiement de ce checkout

requested_amountInteger

Total demandé : amount plus gift_amount le cas échéant, en centimes

asked_amountInteger

Le amount d'origine (hors gift_amount). Diffère de requested_amount en cas de capture partielle ou d'utilisation d'un gift_amount

paid_amountInteger

Total payé par le client, en centimes

service_feeInteger

Frais de service, en centimes

gift_amountInteger

Total des pourboires laissés par le client, en centimes

statusString

pending, ok, authorised, ko

transactionsArray of Transaction

Les paiements rattachés à ce checkout

Afficher les paramètres de Transaction

transactions.transaction_idString: Identifiant unique de cette transaction
transactions.total_amountInteger: Montant payé en centimes
transactions.gift_amountInteger: Pourboire porté par cette transaction, en centimes
transactions.currency_codeString: Code ISO 4217
transactions.date_of_paymentString: YYYY-MM-DD HH:MM:SS, GMT
transactions.gatewayString: Passerelle utilisée pour cette transaction
transactions.issuerString: Nom de l'émetteur de la carte
transactions.panString: Premiers et derniers chiffres de la carte, reliés par des astérisques
transactions.statusString: Statut de la transaction

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

L'objet Transaction

Un paiement rattaché à un checkout. Un checkout peut en porter plusieurs, par exemple un titre-restaurant plus un complément par carte.

Attributs

transaction_idString: Identifiant unique de cette transaction
total_amountInteger: Montant payé en centimes
gift_amountInteger: Pourboire porté par cette transaction, en centimes
currency_codeString: Code ISO 4217
date_of_paymentString: YYYY-MM-DD HH:MM:SS, GMT
gatewayString: Passerelle utilisée pour cette transaction
issuerString: Nom de l'émetteur de la carte
panString: Premiers et derniers chiffres de la carte, reliés par des astérisques
statusString: Statut de la transaction

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

L'objet Customer

Informations du client rattachées au checkout. Obligatoires lorsque vous demandez à Yavin d'envoyer le lien de paiement par e-mail ou par SMS via l'objet Feature.

Attributs

first_nameStringrequis: Prénom
last_nameStringrequis: Nom
emailString: E-mail (obligatoire pour share_by_email)
telephoneString: Format international commençant par + (obligatoire pour share_by_sms)
addressString: Adresse
cityString: Ville
postcodeString: Code postal

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

L'objet Feature

Active ou désactive les options proposées par la page de paiement, et détermine si Yavin envoie le lien au client à votre place.

Attributs

tipsBooleanpar défaut true: Indique si les pourboires sont activés sur la page de paiement
customer_contactsBooleanpar défaut true: Indique si les clients entreprise sont activés
meal_vouchersBooleanpar défaut true: Indique si les titres-restaurant sont activés
share_by_emailBooleanpar défaut false: Envoie le lien de paiement par e-mail ; nécessite un Customer avec une adresse e-mail. Un seul des deux (e-mail ou SMS) par requête
share_by_smsBooleanpar défaut false: Envoie le lien de paiement par SMS ; nécessite un Customer avec un numéro de téléphone. Un seul des deux (e-mail ou SMS) par requête

JSON

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

L'objet Item

Lignes du panier rattachées au checkout. Les articles déterminent les règles d'éligibilité aux titres-restaurant ; envoyez-les donc dès que le marchand accepte les titres-restaurant.

Attributs

nameStringrequis

Nom de l'article

total_amountIntegerrequis

Montant total de l'article, en centimes

total_amount_without_taxInteger

Montant hors taxes

categoryString

Catégorie de l'article

eligible_titre_restaurantBoolean

Éligibilité aux titres-restaurant

free_noteString

Note libre

quantityInteger

Quantité

unit_priceInteger

Prix unitaire en centimes

unit_price_without_taxInteger

Prix unitaire hors taxes

taxTax

Détail des taxes pour cet article

Afficher les paramètres de Tax

tax.amountIntegerrequis: Montant de la taxe en centimes
tax.rateIntegerrequis: Taux de taxe sous forme d'entier décimal (par ex. 20 pour 20 %)

itemsArray

Éléments imbriqués

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

L'objet Tax

Détail des taxes associé à un Item.

Attributs

amountIntegerrequis: Montant de la taxe en centimes
rateIntegerrequis: Taux de taxe sous forme d'entier décimal (par ex. 20 pour 20 %)

JSON

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

L'objet Vendor

Identifie le marchand et le logiciel derrière l'encaissement.

Attributs

software_nameString: Nom du logiciel
software_versionString: Version du logiciel

JSON

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

L'objet Store

Le magasin physique derrière l'encaissement, imbriqué dans l'objet Vendor.

Attributs

store_idStringrequis

Identifiant du magasin

addressAddress

Adresse du magasin

Afficher les paramètres de Address

address.addressStringrequis: Adresse (numéro et rue)
address.cityStringrequis: Ville
address.postcodeStringrequis: Code postal

JSON

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

L'objet Address

Adresse postale, imbriquée dans l'objet Store.

Attributs

addressStringrequis: Adresse (numéro et rue)
cityStringrequis: Ville
postcodeStringrequis: Code postal

JSON

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

L'objet Marketplace

Répartit un paiement entre plusieurs bénéficiaires. Consultez Ventilation Marketplace et Ventilation Foodcourt pour l'onboarding et la partie comptable.

Attributs

ventilationsArrayrequis: Liste d'objets, chacun avec public_account_id (String) et ttc_amount (Integer, en centimes). La somme des valeurs ttc_amount doit être égale à amount de l'encaissement

JSON

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

Untitled

Ventilation Marketplace

Ventilation Foodcourt

Gestion des webhooks

Paiement en ligne : E-commerce API

Présentation

En bref

Endpoints

Avant de commencer

Checkout

Statuts du checkout

Montants

Sandbox

Durée de vie du lien de paiement

Capture différée

Conseils pour les checkouts avec paiements multiples

Webhooks

Générer un lien de paiement

Paramètres

Requête

Réponse

Annuler un lien

Paramètres

Requête

Réponse

Capturer des transactions

Paramètres

Requête

Réponse

Obtenir les informations d'un checkout

Paramètres

Requête

Réponse

L'objet Checkout

Attributs

L'objet Transaction

Attributs

L'objet Customer

Attributs

L'objet Feature

Attributs

L'objet Item

Attributs

L'objet Tax

Attributs

L'objet Vendor

Attributs

L'objet Store

Attributs

L'objet Address

Attributs

L'objet Marketplace

Attributs

Pages associées