API

Gestion des webhooks

Voir en Markdown

Présentation

Yavin envoie un webhook standardisé après qu'une transaction a passé la phase d'acceptation, avec une structure homogène pour les transactions proxi (en magasin) et ecommerce. Utilisez-le pour être notifié des résultats des transactions sans interrogation régulière.

Ce webhook standardisé peut casser des intégrations qui reposaient sur l'ancienne structure ou sur des clés mises à jour ou supprimées. Examinez la structure ci-dessous pour vérifier la compatibilité avec vos gestionnaires de webhook existants, et contactez le support si vous avez besoin d'aide pour vous adapter.

Envoi

  • Le webhook est envoyé aux URL configurées de l'entreprise associée à la transaction. Les URL se configurent dans MyYavin : onglet Paramètres > API > Webhook (les encaissements ecommerce peuvent aussi transmettre un webhook_url par lien)
  • Il est envoyé uniquement lors de l'acceptation de la transaction, pour les transactions proxi comme ecommerce
  • La structure est conçue pour rester stable et cohérente à l'avenir

Les règles d'envoi (contraintes sur les URL, nouvelles tentatives à 1 minute, 10 minutes, 1 heure, 8 heures, puis désactivation) sont décrites dans les pages des API qui émettent le webhook : Cloud API et Webservices API.

Structure du payload

Tous les champs sont facultatifs, sauf indication contraire. Les montants sont des entiers en centimes.

trs_idString
Identifiant de la transaction sur le serveur Yavin
local_idString
Identifiant côté terminal
statusString
ok, ko, pending
typeString
DEBIT, CREDIT, REVERSAL, REFUND
asked_amountInteger
Montant demandé, en centimes
gift_amountInteger
Pourboire ou don, en centimes
total_amountInteger
Montant total, en centimes
currency_codeString
Code ISO 4217
created_atString
Horodatage de création
device_datetimeString
Horodatage sur l'appareil
device_timestampInteger
Horodatage Unix sur l'appareil
server_timestampInteger
Horodatage Unix sur le serveur
serial_numberString
Identifiant du terminal
mediumString
CARD, VAD_MOTO, PAYMENT_LINK, eDebit, WIRE, CASH, ANCV, myyavin, RESTOFLASH
schemeString
AMEX, CONECS, CB, ANCV, MASTERCARD, VISA, MAESTRO
payment_applicationString
AMEX, ANCV, CASH, CONECS_CONTACT, CONECS_CONTACTLESS, DISCOVER, EMV_CONTACT, EMV_CONTACTLESS, EMV_MOTO, EMV_PAYMENT_LINK, RESTOFLASH, OTHER, VAD_NEPTING_REFUND, WIRE
panString
PAN de la carte masqué
card_tokenString
Token unique de la carte du client
referenceString
Serveur ou personne ayant effectué la transaction
client_ticketString
Ticket client
company_ticketString
Ticket marchand
receipt_ticketObject
Contenu du ticket (data, format)
app_versionString
Version de l'application Yavin Pay
company_idInteger
Identifiant interne Yavin de l'entreprise
company_external_idInteger
ID externe de l'entreprise

Liste brute des champs

Python
created_at: str
device_datetime: str
device_timestamp: int
asked_amount: int
gift_amount: int
total_amount: int
status: Literal['ok', 'ko', 'pending']
trs_id: str
serial_number: str
currency_code: str
client_ticket: str
company_ticket: str
receipt_ticket: Dict
type: Literal["DEBIT", "CREDIT", "REVERSAL", "REFUND"]
reference: str
medium: Literal["CARD", "VAD_MOTO", "PAYMENT_LINK", "eDebit", "WIRE", "CASH", "ANCV", "myyavin", "RESTOFLASH"]
scheme: Literal["AMEX", "CONECS", "CB", "ANCV", "MASTERCARD", "VISA", "MAESTRO"]
payment_application: Literal["AMEX", "ANCV", "CASH", "CONECS_CONTACT", "CONECS_CONTACTLESS", "DISCOVER", "EMV_CONTACT", "EMV_CONTACTLESS", "EMV_MOTO", "EMV_PAYMENT_LINK", "RESTOFLASH", "OTHER", "VAD_NEPTING_REFUND", "WIRE"]
app_version: str
pan: str
company_id: int
company_external_id: int
card_token: str
local_id: str
server_timestamp: int

Sécuriser votre endpoint webhook

Les requêtes webhook ne sont pas signées actuellement. Tant qu'aucun mécanisme de signature n'est disponible, protégez votre endpoint :

  • Utilisez une URL difficile à deviner contenant un jeton secret (par ex. https://mydomain.com/webhooks/yavin/{random_token}) et rejetez les requêtes sur tout autre chemin
  • Ne vous fiez jamais au webhook seul pour les décisions liées à l'argent : à réception, revérifiez côté serveur via /get_cart_information/ (ecommerce) ou GET /v5/transaction/?transactionId= (proxi) avant de marquer une commande comme payée
  • Dédoublonnez : les nouvelles tentatives peuvent livrer le même événement plusieurs fois. Utilisez trs_id (proxi) ou checkout_external_id + action (ecommerce) comme clé d'idempotence

Paiement en magasin : Cloud API

Paiement en ligne : E-commerce API

Webservices API