Paiement en magasin : Cloud API

Présentation

La Cloud API vous permet de piloter un terminal Yavin via HTTPS, depuis n'importe quel appareil ou serveur : lancer une transaction, imprimer ou partager un ticket, interrompre ou annuler un paiement. Choisissez-la lorsque le logiciel de caisse n'est pas sur le même réseau que le terminal, ou pour les logiciels de caisse web.

En bref

URL de base	Production : `https://api.yavin.com/api`. Sandbox : `https://api.sandbox.yavin.com/api`
Authentification	Clé d'API dans l'en-tête `Authorization: Bearer YOUR_API_KEY`
Convention de nommage	camelCase pour tous les payloads de requête, sauf l'objet `Item` qui est en snake_case
Version actuelle	`v5` pour `pos/payment`, `v4` pour tous les autres endpoints
Remise des résultats	Asynchrone : la réponse HTTP ne fait qu'accuser réception de la requête, le résultat de la transaction arrive sur votre webhook

Endpoints

Endpoint	Méthode	Version	Usage
`/v5/pos/payment`	POST	v5	Lancer une transaction de type debit, refund ou debit_and_enrol
`/v4/pos/print/`	POST	v4	Imprimer du contenu sur le terminal
`/v4/pos/share-receipt`	POST	v4	Partager un ticket par SMS, e-mail ou impression
`/v4/pos/abort/`	POST	v4	Interrompre le paiement en cours
`/v4/pos/reversal`	POST	v4	Annuler une transaction récente (de moins de 16 heures)

Versions

Version de l'API	Dernière mise à jour
`v5`	04/05/2026
`v4`	04/05/2026
`v1`	02/05/2022

Avant de commencer

Authentification et en-têtes

Chaque requête doit comporter la clé API de votre entreprise et déclarer son corps JSON. Vous trouverez votre clé API sur my.yavin.com, dans l'onglet API. Chaque entreprise (point de vente physique) possède sa propre clé API.

En-tête	Valeur	Obligatoire
`Authorization`	`Bearer YOUR_API_KEY`	oui
`Content-Type`	`application/json`	oui

Omettre Content-Type: application/json renvoie une erreur 400 Bad request, même si le payload est valide. Définissez les deux en-têtes dans chaque requête, y compris celles qui ne transportent qu'un serialNumber.

cURL

curl --request POST \
  --url https://api.yavin.com/api/v5/pos/payment \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "serialNumber": "782996JIS2",
    "transactionType": "debit",
    "vendor": {
      "softwareName": "MyPOS",
      "softwareVersion": "1.0"
    }
  }'

Fenêtre de notification

Un appel à la Cloud API demande au serveur Yavin d'envoyer une notification au terminal. Cette notification est valable pendant 5 secondes.

Si le terminal est hors ligne et ne la reçoit pas dans ce délai, l'action expire et n'est pas retransmise lorsque le terminal se reconnecte. Dans ce cas, aucun webhook n'est jamais envoyé pour le transactionId renvoyé.

Gérez toujours ce cas :

Implémentez un timeout côté client : 125 secondes en mode classique, 62 secondes en mode borne et pour les remboursements
Passé ce délai sans webhook, considérez le paiement comme échoué
Si vous le souhaitez, confirmez via la solution de repli par polling décrite ci-dessous
Réessayez avec un nouveau idempotentUuid

Réponses

Chaque endpoint renvoie un champ status : ok signifie que la requête a été acceptée (endpoints de paiement) ou qu'elle a atteint le terminal (endpoints v4), ko signifie qu'elle ne l'a pas été
Les erreurs sont renvoyées sous la forme d'un HTTP 400 avec status = ko et un message
Le résultat de la transaction est envoyé sur votre webhook sous la forme d'un objet Transaction, documenté à la fin de cette page avec les autres objets partagés

Envoi du webhook

Le résultat de la transaction est envoyé à votre webhook lorsque la transaction est terminée (y compris en cas d'échec). Configurez l'URL de votre webhook dans MyYavin : onglet Paramètres > API > Webhook (une URL par entreprise). Consultez Gestion des webhooks pour la structure du payload.

L'URL du webhook doit être en HTTPS et ne doit pas effectuer de redirection
Yavin attend un accusé de réception HTTP 200. En cas d'échec, le webhook est renvoyé après 1 minute, 10 minutes, 1 heure, puis 8 heures. Lorsque toutes les tentatives sont épuisées, le webhook est désactivé

Interrogation de secours. Si le webhook n'arrive pas dans le délai prévu (125 s en usage classique, 62 s en mode borne et pour les remboursements), interrogez GET https://api.yavin.com/api/v5/transaction/?transactionId={transactionId} sur l'Webservices API avec le transactionId renvoyé de façon synchrone, avant de réessayer avec un nouveau idempotentUuid.

Délais d'expiration

Un paiement dispose d'une fenêtre de 120 secondes entre la réception de la requête par le terminal et la lecture réussie de la carte, répartie en deux phases :

Jusqu'à 60 secondes pour les écrans facultatifs (pourboires, référence, vérification). Si cette phase expire, la transaction est interrompue.
Jusqu'à 60 secondes pour la lecture de la carte elle-même.

Attendez le webhook pendant 125 secondes pour une utilisation classique du terminal, et 62 secondes pour une utilisation en mode borne (écrans facultatifs désactivés) et pour les remboursements.

Idempotence

Envoyez un idempotentUuid à chaque requête de paiement, un par tentative de paiement. Voir Gestion de l'IdempotentUuid.

Devise

La devise est celle configurée sur le profil du marchand dans la base de données Yavin. Devises prises en charge actuellement : EUR, CHF, GBP.

Lancer une transaction de débit

POSThttps://api.yavin.com/api/v5/pos/payment

Lance un paiement par débit sur le terminal identifié par serialNumber.

Paramètres

amountIntegerrequis

Montant en centimes, doit être positif

serialNumberStringrequis

Numéro de série du terminal cible. Il figure au dos de l'appareil, à côté de l'étiquette S/N, ou dans Yavin Pay sous Menu > Paramètres > À propos

transactionTypeStringpar défaut debit

Utilisez debit. Les valeurs sont strictes : toute valeur inconnue, y compris credit, est traitée silencieusement comme un débit

idempotentUuidStringpar défaut autogenerated

Identifiant unique de la tentative de paiement, voir Gestion de IdempotentUuid. Générez un nouvel UUID pour chaque nouvelle tentative

cartIdString

Votre numéro de commande, affiché dans le backoffice MyYavin

customerCustomer

Informations client associées à la transaction

Afficher les paramètres de Customer

customer.firstNameString: Prénom
customer.lastNameString: Nom
customer.emailString: E-mail
customer.phoneString: Format international commençant par + (par ex. +33612345678)

enableGiftScreenBoolean

null (par défaut) : la configuration des pourboires du terminal s'applique. Une valeur non nulle la remplace pour cette transaction : true affiche l'écran des pourboires, false l'ignore

giftAmountIntegerpar défaut 0

Pourboire ou don en centimes, s'il est sélectionné côté logiciel de caisse

receiptTicketReceiptTicket

Contenu du ticket imprimé avec le ticket carte

Afficher les paramètres de ReceiptTicket

receiptTicket.dataStringrequis: Contenu à imprimer
receiptTicket.formatStringpar défaut text: Format du contenu

referenceString

Serveur ou personne qui traite la transaction

vendorVendor

Nom et version de votre logiciel

Afficher les paramètres de Vendor

vendor.softwareNameString: Nom du logiciel de caisse
vendor.softwareVersionString: Version du logiciel de caisse

acceptedPaymentAcceptedPaymentpar défaut {"acceptedMediumType":"all"}

Restreint les familles de cartes acceptées

Afficher les paramètres de AcceptedPayment

acceptedPayment.acceptedMediumTypeStringpar défaut all: all, lunch_vouchers_only, bank_cards_only

checkoutExternalIdString

Identifiant de caisse unique pour le marchand, obligatoire dès qu'un des champs de commande externe ci-dessous est envoyé. Utilisez une valeur différente pour chaque transaction

externalTableNumberString

Numéro de table. Utilisé uniquement avec checkoutExternalId

externalOrderNumberString

Numéro de commande lisible. Utilisé uniquement avec checkoutExternalId

externalOrderIdString

Identifiant technique unique de la commande dans votre logiciel de caisse. Utilisé uniquement avec checkoutExternalId

itemsArray of Item

Lignes détaillées du panier

Afficher les paramètres de Item

items.nameStringrequis: Nom de l'article
items.total_amountIntegerrequis: Montant total en centimes
items.total_amount_without_taxInteger: Total de l'article hors taxes
items.categoryString: Catégorie de l'article
items.eligible_titre_restaurantBoolean: Éligibilité aux titres-restaurant
items.free_noteString: Note en texte libre
items.quantityInteger: Quantité
items.unit_priceInteger: Prix unitaire en centimes
items.unit_price_without_taxInteger: Prix unitaire hors taxes en centimes
items.taxObject: { "amount": <int>, "rate": <int> }
items.itemsArray: Éléments imbriqués

Requête

{
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "checkout_123",
  "externalOrderId": "order_uuid_123",
  "externalOrderNumber": "A-1024",
  "externalTableNumber": "12",
  "items": [
    {
      "name": "Menu midi",
      "total_amount": 1590,
      "quantity": 1,
      "tax": { "amount": 265, "rate": 20 }
    }
  ]
}

curl -X POST 'https://api.yavin.com/api/v5/pos/payment' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "checkout_123",
  "externalOrderId": "order_uuid_123",
  "externalOrderNumber": "A-1024",
  "externalTableNumber": "12",
  "items": [
    {
      "name": "Menu midi",
      "total_amount": 1590,
      "quantity": 1,
      "tax": { "amount": 265, "rate": 20 }
    }
  ]
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/pos/payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "amount": 1000,
      "serialNumber": "782996JIS2",
      "transactionType": "debit",
      "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
      "vendor": {
        "softwareName": "MyPOS",
        "softwareVersion": "1.0"
      },
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      },
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@yavin.com"
      },
      "acceptedPayment": {
        "acceptedMediumType": "all"
      },
      "checkoutExternalId": "checkout_123",
      "externalOrderId": "order_uuid_123",
      "externalOrderNumber": "A-1024",
      "externalTableNumber": "12",
      "items": [
        {
          "name": "Menu midi",
          "total_amount": 1590,
          "quantity": 1,
          "tax": { "amount": 265, "rate": 20 }
        }
      ]
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "checkout_123",
  "externalOrderId": "order_uuid_123",
  "externalOrderNumber": "A-1024",
  "externalTableNumber": "12",
  "items": [
    {
      "name": "Menu midi",
      "total_amount": 1590,
      "quantity": 1,
      "tax": { "amount": 265, "rate": 20 }
    }
  ]
}

response = requests.post(
    "https://api.yavin.com/api/v5/pos/payment",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

JSON

{
  "status": "ok",
  "transactionId": "dIuiP6NovnZS"
}

Lancer une transaction et enregistrer la carte (debit_and_enrol)

POSThttps://api.yavin.com/api/v5/pos/payment

Lance un paiement et tokenise la carte dans le même flux. amount peut valoir 0 pour enregistrer une carte sans la débiter. Le token de la carte est envoyé avec le résultat de la transaction sur votre webhook.

Paramètres

amountIntegerrequis

Montant en centimes, 0 ou plus

serialNumberStringrequis

Numéro de série du terminal

transactionTypeStringrequis

Doit être debit_and_enrol

idempotentUuidStringpar défaut autogenerated

Clé d'idempotence

customerCustomer

Données client

Afficher les paramètres de Customer

customer.firstNameString: Prénom
customer.lastNameString: Nom
customer.emailString: E-mail
customer.phoneString: Format international commençant par + (par ex. +33612345678)

vendorVendor

Informations sur l'éditeur du logiciel

Afficher les paramètres de Vendor

vendor.softwareNameString: Nom du logiciel de caisse
vendor.softwareVersionString: Version du logiciel de caisse

referenceString

Référence du serveur ou de la personne

receiptTicketReceiptTicket

Contenu du ticket (facultatif)

Afficher les paramètres de ReceiptTicket

receiptTicket.dataStringrequis: Contenu à imprimer
receiptTicket.formatStringpar défaut text: Format du contenu

receiptTicketJsonString

Payload JSON supplémentaire sous forme de chaîne

acceptedPaymentAcceptedPaymentpar défaut {"acceptedMediumType":"all"}

Restreint les familles de cartes acceptées

Afficher les paramètres de AcceptedPayment

acceptedPayment.acceptedMediumTypeStringpar défaut all: all, lunch_vouchers_only, bank_cards_only

checkoutExternalId, externalOrderId, externalOrderNumber, externalTableNumberString

Références de commande externes

itemsArray of Item

Lignes de panier

Afficher les paramètres de Item

items.nameStringrequis: Nom de l'article
items.total_amountIntegerrequis: Montant total en centimes
items.total_amount_without_taxInteger: Total de l'article hors taxes
items.categoryString: Catégorie de l'article
items.eligible_titre_restaurantBoolean: Éligibilité aux titres-restaurant
items.free_noteString: Note en texte libre
items.quantityInteger: Quantité
items.unit_priceInteger: Prix unitaire en centimes
items.unit_price_without_taxInteger: Prix unitaire hors taxes en centimes
items.taxObject: { "amount": <int>, "rate": <int> }
items.itemsArray: Éléments imbriqués

Requête

{
  "amount": 0,
  "serialNumber": "782996JIS2",
  "transactionType": "debit_and_enrol",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  }
}

curl -X POST 'https://api.yavin.com/api/v5/pos/payment' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 0,
  "serialNumber": "782996JIS2",
  "transactionType": "debit_and_enrol",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  }
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/pos/payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "amount": 0,
      "serialNumber": "782996JIS2",
      "transactionType": "debit_and_enrol",
      "vendor": {
        "softwareName": "MyPOS",
        "softwareVersion": "1.0"
      }
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "amount": 0,
  "serialNumber": "782996JIS2",
  "transactionType": "debit_and_enrol",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  }
}

response = requests.post(
    "https://api.yavin.com/api/v5/pos/payment",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

Identique à l'endpoint de débit : status = ok avec un transactionId en cas d'acceptation, status = ko avec un message en cas d'échec.

Lancer une transaction de remboursement

POSThttps://api.yavin.com/api/v5/pos/payment

Recrédite les fonds sur la carte du client. Même endpoint, avec transactionType défini sur refund. Aucun écran facultatif n'est affiché : attendez le webhook pendant 62 secondes maximum.

Paramètres

transactionTypeStringrequispar défaut debit: Doit être défini sur refund. Toute autre valeur, telle que credit, lance un débit

Requête

{
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}

curl -X POST 'https://api.yavin.com/api/v5/pos/payment' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/pos/payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "amount": 1000,
      "serialNumber": "782996JIS2",
      "transactionType": "refund",
      "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
      "vendor": {
        "softwareName": "MyPOS",
        "softwareVersion": "1.0"
      },
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      }
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "amount": 1000,
  "serialNumber": "782996JIS2",
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}

response = requests.post(
    "https://api.yavin.com/api/v5/pos/payment",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

Identique à l'endpoint de débit : status = ok avec un transactionId en cas d'acceptation, status = ko avec un message en cas d'échec.

Imprimer un ticket

POSThttps://api.yavin.com/api/v4/pos/print/

Imprime un contenu libre sur le terminal (facture, ticket, bon de cuisine).

Paramètres

serialNumberStringrequis: Identifiant du terminal
dataStringrequis: Contenu à imprimer
formatStringpar défaut text: text ou escpos

Requête

{
  "serialNumber": "123456789",
  "format": "text",
  "data": "This is a ticket\nto print !"
}

curl -X POST 'https://api.yavin.com/api/v4/pos/print/' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "serialNumber": "123456789",
  "format": "text",
  "data": "This is a ticket\nto print !"
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v4/pos/print/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "serialNumber": "123456789",
      "format": "text",
      "data": "This is a ticket\nto print !"
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "serialNumber": "123456789",
  "format": "text",
  "data": "This is a ticket\nto print !"
}

response = requests.post(
    "https://api.yavin.com/api/v4/pos/print/",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

200 : status = ok (la requête a atteint le terminal) ou ko (elle ne l'a pas atteint). 400 : status = ko avec un message.

Partager un ticket

POSThttps://api.yavin.com/api/v4/pos/share-receipt

Partage un ticket par SMS, e-mail ou impression. Le terminal demande les informations du destinataire (numéro de téléphone ou e-mail).

Paramètres

serialNumberStringrequis

Identifiant du terminal

receiptTicketReceiptTicketrequis

Ticket à partager

Afficher les paramètres de ReceiptTicket

receiptTicket.dataStringrequis: Contenu à imprimer
receiptTicket.formatStringpar défaut text: Format du contenu

transactionIdStringrequis

Transaction liée au ticket

mediumStringrequis

L'une des valeurs yavin, sms, email, print, en minuscules (SMS est rejeté). Avec yavin, le ticket est enregistré et partagé selon les préférences de notification de l'utilisateur

Requête

{
  "serialNumber": "123456789",
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv43g7wxZ",
  "medium": "email"
}

curl -X POST 'https://api.yavin.com/api/v4/pos/share-receipt' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "serialNumber": "123456789",
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv43g7wxZ",
  "medium": "email"
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v4/pos/share-receipt", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "serialNumber": "123456789",
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      },
      "transactionId": "fsOv43g7wxZ",
      "medium": "email"
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "serialNumber": "123456789",
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv43g7wxZ",
  "medium": "email"
}

response = requests.post(
    "https://api.yavin.com/api/v4/pos/share-receipt",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

200 : status = ok (la requête a atteint le terminal) ou ko (elle ne l'a pas atteint). 400 : status = ko avec un message.

Interrompre une transaction

POSThttps://api.yavin.com/api/v4/pos/abort/

Interrompt le paiement en cours sur le terminal : tous les écrans de paiement sont fermés et le terminal revient à son écran principal.

Évitez d'interrompre une transaction pendant la phase de lecture de la carte : l'écran de la passerelle de paiement peut se fermer de manière inattendue et les informations de paiement risquent de ne pas être transmises correctement.

Paramètres

serialNumberStringrequis: Identifiant du terminal
idempotentUuidString: UUID de la tentative de paiement à interrompre

Requête

{
  "serialNumber": "123456789",
  "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
}

curl -X POST 'https://api.yavin.com/api/v4/pos/abort/' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "serialNumber": "123456789",
  "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v4/pos/abort/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "serialNumber": "123456789",
      "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "serialNumber": "123456789",
  "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
}

response = requests.post(
    "https://api.yavin.com/api/v4/pos/abort/",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

200 : status = ok (la requête a atteint le terminal) ou ko (elle ne l'a pas atteint). 400 : status = ko avec un message.

Annuler une transaction

POSThttps://api.yavin.com/api/v4/pos/reversal

Annule une transaction récente.

Conditions d'annulation. La transaction d'origine est un débit ok traité sur le même terminal que celui qui émet l'annulation, il y a moins de 16 heures (heure du terminal), et le montant de l'annulation est égal au montant total d'origine, pourboire inclus (amount + giftAmount).

Paramètres

amountIntegerrequis: Montant en centimes, doit être égal au montant total d'origine (amount • giftAmount)
initialTransactionIdStringrequis: Transaction à annuler

Requête

{
  "amount": 1000,
  "initialTransactionId": "dIuiP6NovnZS"
}

curl -X POST 'https://api.yavin.com/api/v4/pos/reversal' \
  -H 'Authorization: Bearer YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "initialTransactionId": "dIuiP6NovnZS"
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v4/pos/reversal", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.YAVIN_API_KEY}`,
    },
    body: JSON.stringify({
      "amount": 1000,
      "initialTransactionId": "dIuiP6NovnZS"
    }),
  });

  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",
    "Authorization": "Bearer " + os.environ["YAVIN_API_KEY"],
}

payload = {
  "amount": 1000,
  "initialTransactionId": "dIuiP6NovnZS"
}

response = requests.post(
    "https://api.yavin.com/api/v4/pos/reversal",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Réponse

200 : status = ok ou ko, avec initialTransactionId et reversalTransactionId. 400 : status = ko avec un message.

L'objet Transaction

Envoyé à votre webhook une fois la transaction terminée. Consultez Gestion des webhooks pour connaître l'enveloppe complète du webhook.

Attributs

statusString: ok, ko, pending
transactionIdString: Identifiant côté serveur
localIdString: Identifiant côté terminal
amountInteger: Montant en centimes, hors giftAmount. Le client est débité de la somme de amount et giftAmount (égale à total_amount dans le payload du webhook)
giftAmountInteger: Pourboire ou don en centimes
currencyCodeString: Code ISO 4217
transactionTypeString: par ex. debit
createdAtString: Date de création dans la base de données Yavin
appVersionString: Version de l'application Yavin Pay
serialNumberString: Identifiant du terminal
clientTicket / companyTicketString: Tickets client et marchand
panString: PAN de la carte masqué
ticketUrlString: URL du ticket client numérique
paymentApplicationString: AMEX, ANCV, CONECS_CONTACT, CONECS_CONTACTLESS, EMV_CONTACT, EMV_CONTACTLESS, EMV_MOTO, EMV_PAYMENT_LINK, RESTOFLASH, DISCOVER, CUP
schemeString: Réseau d'acceptation (par ex. VISA)
issuerString: Émetteur de la carte
referenceString: Serveur ou personne ayant effectué la transaction
checkoutExternalId, externalTableNumber, externalOrderNumber, externalOrderIdString: Références de commande externes

JSON

{
  "status": "ok",
  "transactionId": "dIuiP6NovnZS",
  "localId": "1042",
  "amount": 1000,
  "giftAmount": 0,
  "currencyCode": "EUR",
  "transactionType": "debit",
  "createdAt": "2026-08-14T10:22:31",
  "appVersion": "3.2.8",
  "serialNumber": "782996JIS2",
  "paymentApplication": "EMV_CONTACTLESS",
  "scheme": "CB",
  "issuer": "VISA",
  "pan": "424242******4242",
  "ticketUrl": "https://t.yavin.com/dIuiP6NovnZS",
  "reference": "Luke",
  "clientTicket": "...",
  "companyTicket": "...",
  "checkoutExternalId": "checkout_123",
  "externalTableNumber": "12",
  "externalOrderNumber": "A-1024",
  "externalOrderId": "order_uuid_123"
}

L'objet Customer

Facultatif sur l'endpoint de paiement. Informations client associées à la transaction. Elles ne sont pas utilisées par /share-receipt, où le terminal demande toujours les informations du destinataire.

Attributs

firstNameString: Prénom
lastNameString: Nom
emailString: E-mail
phoneString: Format international commençant par + (par ex. +33612345678)

JSON

{
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+33612345678",
    "email": "john@yavin.com"
  }
}

L'objet ReceiptTicket

Contenu imprimé avec le ticket carte sur l'endpoint de paiement, ou partagé par /share-receipt.

Attributs

dataStringrequis: Contenu à imprimer
formatStringpar défaut text: Format du contenu

JSON

{
  "receiptTicket": {
    "data": "Receipt ticket here to print if needed",
    "format": "text"
  }
}

L'objet Vendor

Identifie votre logiciel de caisse. Facultatif partout, mais fortement recommandé : il permet à notre équipe support de remonter d'un problème à une intégration et une version précises.

Attributs

softwareNameString: Nom du logiciel de caisse
softwareVersionString: Version du logiciel de caisse

JSON

{
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  }
}

L'objet AcceptedPayment

Limite les familles de cartes que le terminal accepte pour cette transaction. Utile, par exemple, pour une borne qui doit refuser les titres-restaurant.

Attributs

acceptedMediumTypeStringpar défaut all: all, lunch_vouchers_only, bank_cards_only

JSON

{
  "acceptedPayment": {
    "acceptedMediumType": "bank_cards_only"
  }
}

L'objet Item

Lignes de panier envoyées avec un paiement. Disponible uniquement sur v5 pos/payment. Les articles déterminent les règles d'éligibilité aux titres-restaurant : envoyez-les dès que le marchand accepte les titres-restaurant.

Les champs de Item sont en snake_case, contrairement au reste du payload.

Attributs

nameStringrequis: Nom de l'article
total_amountIntegerrequis: Montant total en centimes
total_amount_without_taxInteger: Total de l'article hors taxes
categoryString: Catégorie de l'article
eligible_titre_restaurantBoolean: Éligibilité aux titres-restaurant
free_noteString: Note en texte libre
quantityInteger: Quantité
unit_priceInteger: Prix unitaire en centimes
unit_price_without_taxInteger: Prix unitaire hors taxes en centimes
taxObject: { "amount": <int>, "rate": <int> }
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 }
    }
  ]
}

Gestion des webhooks

Gestion de l'IdempotentUuid

Paiement en magasin : Cloud API

Présentation

En bref

Endpoints

Versions

Avant de commencer

Authentification et en-têtes

Fenêtre de notification

Réponses

Envoi du webhook

Délais d'expiration

Idempotence

Devise

Lancer une transaction de débit

Paramètres

Requête

Réponse

Lancer une transaction et enregistrer la carte (debit_and_enrol)

Paramètres

Requête

Réponse

Lancer une transaction de remboursement

Paramètres

Requête

Réponse

Imprimer un ticket

Paramètres

Requête

Réponse

Partager un ticket

Paramètres

Requête

Réponse

Interrompre une transaction

Paramètres

Requête

Réponse

Annuler une transaction

Paramètres

Requête

Réponse

L'objet Transaction

Attributs

L'objet Customer

Attributs

L'objet ReceiptTicket

Attributs

L'objet Vendor

Attributs

L'objet AcceptedPayment

Attributs

L'objet Item

Attributs

Pages associées