Webservices API

Présentation

La Webservices API est destinée aux intégrations serveur à serveur via HTTPS : récupérez les données de transactions, remboursez des transactions et recevez les événements de transaction via des webhooks. Choisissez-la pour vos workflows de reporting, de rapprochement et de remboursement, indépendamment de la manière dont les paiements ont été effectués.

En bref

URL de base	Production : `https://api.yavin.com/api/v5`. Sandbox : `https://api.sandbox.yavin.com/api/v5`
Authentification	Clé d'API dans l'en-tête `Yavin-Secret`
Convention de nommage	Dépend de l'endpoint : Récupérer les transactions utilise le camelCase (`startDate`, `serialNumbers`) avec deux exceptions en snake_case (`only_pending`, `exclude_e_commerce`) ; Remboursement utilise le snake_case (`user_email`). Reportez-vous au tableau des paramètres de chaque endpoint
Version actuelle	`v5`
Remise des résultats	Synchrone pour les endpoints de récupération ; les remboursements sont synchrones, avec un webhook lors de l'acceptation ou du rejet définitif

Endpoints

Endpoint	Méthode	Usage
`/pos/transactions/`	POST	Récupérer un lot de transactions
`/transaction/`	GET	Récupérer une transaction unique
`/transaction/{id}/refund/`	POST	Rembourser une transaction

Avant de commencer

Authentification et en-têtes

Chaque requête doit contenir la clé API de votre entreprise dans l'en-tête Yavin-Secret et déclarer Content-Type: application/json. Vous trouverez votre clé API sur my.yavin.com, dans l'onglet API.

En-tête	Valeur	Obligatoire
`Yavin-Secret`	`YOUR_API_KEY`	oui
`Content-Type`	`application/json`	oui

Fuseaux horaires

Sur l'endpoint de récupération, startTime et endTime doivent être fournis sans indicateur de fuseau horaire (pas de Z final) et sont interprétés dans le timezone que vous indiquez. Renseignez toujours le paramètre timezone pour obtenir des données correctes.

Erreurs transitoires

Les réponses 502 occasionnelles sur les appels lourds sont des erreurs de passerelle transitoires, et non des erreurs applicatives : réessayez avec un backoff exponentiel. Pour les imports d'historique, découpez les requêtes jour par jour plutôt que de récupérer de grandes plages.

Envoi du webhook

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é

Pour le payload standardisé du webhook de transaction, consultez Gestion des webhooks.

Récupérer un lot de transactions

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

Récupère les transactions d'un compte Yavin. Utilisez limit et offset pour la pagination, ainsi que les filtres (dates, terminaux, schemes) pour ne récupérer que ce dont vous avez besoin. Si aucun filtre de date n'est défini, les 30 derniers jours sont récupérés.

Les transactions sont renvoyées dans l'ordre chronologique inverse (les plus récentes en premier). Si vous paginez alors que de nouvelles transactions arrivent, fixez endDate et endTime à un point dans le passé afin que les pages restent cohérentes (sans doublons ni omissions).

Paramètres

startDateString: Date la plus ancienne à inclure, yyyy-MM-dd, incluse. Si aucun filtre de date n'est défini, les 30 derniers jours sont récupérés
endDateString: Date la plus récente à inclure, yyyy-MM-dd, incluse (la journée entière sauf si endTime est défini)
startTimeStringpar défaut 00:00:00: Heure de début le startDate, HH:mm:ss, sans indicateur de fuseau horaire, interprétée dans timezone
endTimeStringpar défaut 23:59:59: Heure de fin le endDate, HH:mm:ss, sans indicateur de fuseau horaire, interprétée dans timezone
timezoneString: ID du fuseau horaire de l'appelant (par ex. Europe/Paris). Fortement recommandé
limitIntegerpar défaut 20: Nombre maximal de transactions renvoyées, jusqu'à 200
offsetIntegerpar défaut 0: Décalage de pagination
serialNumbersArray: Identifiants de terminaux sur lesquels filtrer (visibles dans Yavin Services)
referencesArray: Références sur lesquelles filtrer
schemesArray: Schemes sur lesquels filtrer
currencyCodeString: Code ISO 4217
only_pendingBooleanpar défaut false: true : uniquement les transactions en attente
exclude_e_commerceBooleanpar défaut false: true : exclure les transactions ecommerce

Requête

url = 'https://api.yavin.com/api/v5/pos/transactions/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}
params = {
  "serialNumbers": ["123456789"],
  "timezone": "Europe/Paris",
  "startDate": "2022-01-01",
  "endDate": "2022-02-01",
  "startTime": "00:00:00",
  "endTime": "23:59:59",
  "limit": 100
}

curl -X POST 'https://api.yavin.com/api/v5/pos/transactions/' \
  -H 'Yavin-Secret: YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "serialNumbers": [
    "123456789"
  ],
  "timezone": "Europe/Paris",
  "startDate": "2022-01-01",
  "endDate": "2022-02-01",
  "startTime": "00:00:00",
  "endTime": "23:59:59",
  "limit": 100
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/pos/transactions/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({
      "serialNumbers": [
        "123456789"
      ],
      "timezone": "Europe/Paris",
      "startDate": "2022-01-01",
      "endDate": "2022-02-01",
      "startTime": "00:00:00",
      "endTime": "23:59:59",
      "limit": 100
    }),
  });

  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 = {
  "serialNumbers": [
    "123456789"
  ],
  "timezone": "Europe/Paris",
  "startDate": "2022-01-01",
  "endDate": "2022-02-01",
  "startTime": "00:00:00",
  "endTime": "23:59:59",
  "limit": 100
}

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

Réponse

JSON

{
  "total": 356,
  "limit": 100,
  "offset": 0,
  "count": 100,
  "transactions": [
    {
      "amount": 100,
      "createdAt": "2022-05-10T14:09:06",
      "customer": { "email": "", "phone": "0612345687" },
      "giftAmount": 0,
      "issuer": "BNP",
      "scheme": "CB",
      "status": "ok",
      "transactionId": "IEqoLmjuRqfq",
      "type": "debit",
      "serialNumber": "123456789"
    }
  ]
}

Récupérer une transaction

GEThttps://api.yavin.com/api/v5/transaction/

Récupère les détails d'une transaction unique. La transaction doit appartenir à l'entreprise associée à la clé API ; sinon, une erreur est renvoyée.

Paramètres

transactionIdStringrequis: Identifiant unique de la transaction, transmis dans la query string

Requête

curl -X GET 'https://api.yavin.com/api/v5/transaction/?transactionId=<transactionId>' \
  -H 'Yavin-Secret: YAVIN_API_KEY'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/transaction/?transactionId=<transactionId>", {
    method: "GET",
    headers: {
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
  });

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

import os
import requests

headers = {
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

response = requests.get(
    "https://api.yavin.com/api/v5/transaction/?transactionId=<transactionId>",
    headers=headers,
)
response.raise_for_status()
data = response.json()

Réponse

JSON

{
  "transactionDetails": {
    "askedAmount": 1000,
    "giftAmount": 0,
    "totalAmount": 1000,
    "serverDatetime": "2022-05-10T14:09:06",
    "deviceDatetime": "2022-05-10T14:09:06",
    "issuer": "BNP",
    "scheme": "CB",
    "status": "ok",
    "transactionId": "mk8wHcHUeQol",
    "type": "debit",
    "serialNumber": "123456789",
    "clientTicket": "ticket_client_123",
    "companyTicket": "ticket_merchant_123",
    "receiptTicket": { "data": "receipt_data", "format": "text" },
    "reference": "server_reference_123"
  }
}

Rembourser une transaction

POSThttps://api.yavin.com/api/v5/transaction/{original_transaction_id}/refund/

Initie le remboursement d'une transaction précédemment traitée.

Conditions de remboursement.

Le point de vente doit avoir l'option « remboursements par API » activée
La transaction d'origine a été traitée par le même établissement et n'a pas encore de remboursement associé (les remboursements multiples sur une même transaction ne sont pas possibles)
Le montant du remboursement est supérieur à 0 et inférieur ou égal au montant de la transaction d'origine
Les transactions AMEX, CUP, Espèces, ANCV, Conecs, Edenred et Swile ne sont pas remboursables

Comme un seul remboursement par transaction est possible, un remboursement partiel rend définitivement non remboursable via l'API le montant restant : remboursez le montant total souhaité en un seul appel.

Si user_email n'est pas connu dans la base de données Yavin ou n'a pas accès à MyYavin BO, un e-mail d'approbation est envoyé à tous les utilisateurs administrateurs du backoffice marchand, et le remboursement reste en waiting jusqu'à son approbation.

Paramètres

amountIntegerrequis

Montant du remboursement en centimes, doit être positif

user_emailStringrequis

E-mail de l'utilisateur à l'origine du remboursement

vendorVendorrequis

Informations sur l'éditeur du logiciel

Afficher les paramètres de Vendor

vendor.software_nameStringrequis: Nom du logiciel de caisse
vendor.software_versionStringrequis: Version du logiciel de caisse

prioritise_tipBooleanpar défaut false

En cas de remboursement partiel : false (par défaut), le montant de la transaction est remboursé en premier ; true, le pourboire est remboursé en premier

Requête

{
  "amount": 1000,
  "user_email": "user@example.com",
  "vendor": {
    "software_name": "MyPOS",
    "software_version": "1.0"
  }
}

curl -X POST 'https://api.yavin.com/api/v5/transaction/{original_transaction_id}/refund/' \
  -H 'Yavin-Secret: YAVIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "user_email": "user@example.com",
  "vendor": {
    "software_name": "MyPOS",
    "software_version": "1.0"
  }
}'

(async () => {
  const response = await fetch("https://api.yavin.com/api/v5/transaction/{original_transaction_id}/refund/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Yavin-Secret": process.env.YAVIN_API_KEY,
    },
    body: JSON.stringify({
      "amount": 1000,
      "user_email": "user@example.com",
      "vendor": {
        "software_name": "MyPOS",
        "software_version": "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",
    "Yavin-Secret": os.environ["YAVIN_API_KEY"],
}

payload = {
  "amount": 1000,
  "user_email": "user@example.com",
  "vendor": {
    "software_name": "MyPOS",
    "software_version": "1.0"
  }
}

response = requests.post(
    "https://api.yavin.com/api/v5/transaction/{original_transaction_id}/refund/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
data = response.json()

Réponse

Tous les cas de figure en un coup d'œil :

Code HTTP	`status`	Signification	Champs supplémentaires
201	`refunded`	Le remboursement a été traité	`message` = `ok`, `transaction_id` (transaction de remboursement)
202	`pending`	Reçu, des vérifications supplémentaires sont nécessaires avant le traitement	`message` = `ok`, `transaction_id`
202	`waiting`	Reçu, approbation manuelle requise dans le backoffice	`message` = `ok`, `transaction_id`, `approval_url` (URL du backoffice pour examiner le remboursement)
400		Requête mal formée : objet JSON indexé par champ, par exemple `"amount": ["cannot be greater than the transaction's total amount"]`
400		Remboursement impossible : champ `error`, par exemple `This transaction has already been refunded`
422	`not_possible`	Refusé par l'émetteur	`message` = `The refund was refused by the issuer`

Un webhook est envoyé uniquement lorsque le remboursement a été accepté ou rejeté, car l'état en attente est déjà connu grâce à la réponse synchrone. Son corps correspond à l'objet RefundWebhook documenté ci-dessous.

Configuration

Transaction e-commerce : le webhook_url fourni lors de la création du lien est rappelé
Transaction Proxi : demandez à l'équipe Support Yavin de configurer une URL de webhook pour chaque société intégrée

L'objet Transaction

Renvoyé dans la liste par l'endpoint de récupération par lot.

Attributs

amountInteger

Montant en centimes

giftAmountInteger

Pourboire ou don en centimes

createdAtString

Date de création, ISO 8601

currencyCodeString

Code ISO 4217

statusString

Statut de la transaction

transactionIdString

Identifiant unique

typeString

Type de transaction (par exemple debit)

serialNumberString

Identifiant du terminal

schemeString

Réseau d'acceptation (par exemple CB)

issuerString

Émetteur de la carte

referenceString

Serveur ou personne ayant effectué la transaction

cartIdString

Référence de commande provenant du logiciel de caisse

customerCustomer

Informations sur le client, lorsqu'elles sont disponibles

Afficher les paramètres de Customer

customer.first_nameString: Prénom
customer.last_nameString: Nom
customer.emailString: E-mail
customer.phoneString: Format international commençant par + (par ex. +33612345678)
customer.birth_dateString: Date de naissance

JSON

{
  "amount": 100,
  "giftAmount": 0,
  "createdAt": "2022-05-10T14:09:06",
  "currencyCode": "EUR",
  "status": "ok",
  "transactionId": "IEqoLmjuRqfq",
  "type": "debit",
  "serialNumber": "123456789",
  "scheme": "CB",
  "issuer": "BNP",
  "reference": "Luke",
  "cartId": "ORDER-2026-000123",
  "customer": { "email": "", "phone": "0612345687" }
}

L'objet TransactionDetails

Renvoyé par l'endpoint de récupération unitaire, sous transactionDetails. Plus riche que l'objet Transaction : il contient les tickets et les deux horodatages.

Attributs

askedAmountInteger: Montant demandé, en centimes
giftAmountInteger: Pourboire ou don, en centimes
totalAmountInteger: Montant total, en centimes
serverDatetimeString: Horodatage de création sur le serveur, ISO 8601
deviceDatetimeString: Horodatage de création sur l'appareil, ISO 8601
issuerString: Émetteur de la carte (par exemple BNP)
schemeString: Réseau d'acceptation (par exemple CB, VISA)
statusString: Statut de la transaction (par exemple ok)
transactionIdString: Identifiant unique
typeString: debit, credit, ...
serialNumberString: Numéro de série du terminal
clientTicket / companyTicketString: Tickets client et marchand
receiptTicketObject: Contenu du ticket : data et format
referenceString: Référence liée à la transaction (par exemple, le serveur)

JSON

{
  "askedAmount": 1000,
  "giftAmount": 0,
  "totalAmount": 1000,
  "serverDatetime": "2022-05-10T14:09:06",
  "deviceDatetime": "2022-05-10T14:09:06",
  "issuer": "BNP",
  "scheme": "CB",
  "status": "ok",
  "transactionId": "mk8wHcHUeQol",
  "type": "debit",
  "serialNumber": "123456789",
  "clientTicket": "ticket_client_123",
  "companyTicket": "ticket_merchant_123",
  "receiptTicket": { "data": "receipt_data", "format": "text" },
  "reference": "server_reference_123"
}

L'objet RefundWebhook

Envoyé à votre webhook lorsqu'un remboursement a été accepté ou refusé. Contient à la fois la transaction d'origine et la transaction de remboursement, ce qui vous permet de effectuer le rapprochement sans second appel.

Attributs

original_transactionObject: Détails de la transaction d'origine : transaction_id, asked_amount, gift_amount, total_amount (en centimes), pan (masqué), date (ISO 8601)
refund_transactionObject: Mêmes champs pour la transaction de remboursement
statusString: success ou rejected
request_user_emailString: E-mail de l'utilisateur à l'origine du remboursement
sourceString: api ou myyavin

JSON

{
  "original_transaction": {
    "transaction_id": "txn_1234567890",
    "asked_amount": 5000,
    "gift_amount": 500,
    "total_amount": 5500,
    "pan": "411111******1111",
    "date": "2025-01-10T14:32:45Z"
  },
  "refund_transaction": {
    "transaction_id": "txn_refund_0987654321",
    "asked_amount": 5000,
    "gift_amount": 500,
    "total_amount": 5500,
    "pan": "411111******1111",
    "date": "2025-01-11T09:12:03Z"
  },
  "status": "success",
  "request_user_email": "user@example.com",
  "source": "api"
}

L'objet Customer

Informations client associées à une transaction, lorsqu'elles sont disponibles.

Attributs

first_nameString: Prénom
last_nameString: Nom
emailString: E-mail
phoneString: Format international commençant par + (par ex. +33612345678)
birth_dateString: Date de naissance

JSON

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

L'objet Vendor

Identifie votre logiciel dans une requête de remboursement. Obligatoire, et au format snake_case sur cet endpoint.

Attributs

software_nameStringrequis: Nom du logiciel de caisse
software_versionStringrequis: Version du logiciel de caisse

JSON

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

Gestion des webhooks

Webservices API

Présentation

En bref

Endpoints

Avant de commencer

Authentification et en-têtes

Fuseaux horaires

Erreurs transitoires

Envoi du webhook

Récupérer un lot de transactions

Paramètres

Requête

Réponse

Récupérer une transaction

Paramètres

Requête

Réponse

Rembourser une transaction

Paramètres

Requête

Réponse

L'objet Transaction

Attributs

L'objet TransactionDetails

Attributs

L'objet RefundWebhook

Attributs

L'objet Customer

Attributs

L'objet Vendor

Attributs

Pages associées