Introduction

L'API Yavin permet aux développeurs et aux intégrateurs d'intégrer des fonctionnalités de paiement à leurs propres parcours utilisateur : traiter des paiements sur un terminal, générer des liens de paiement en ligne, imprimer et partager des tickets, et accéder aux données de transaction.

Cas d'usage typiques : paiement sur terminal depuis un logiciel de caisse, paiement en borne, paiement en ligne Click & Collect, Order & Pay via QR code, Pay at Table via QR code.

Choisir votre intégration

Posez-vous d'abord une question : où le paiement a-t-il lieu ?

Configurer votre sandbox

Contactez notre équipe à l'adresse partnerships@yavin.com pour obtenir un environnement sandbox ainsi qu'un terminal de test si nécessaire.

Authentification

Yavin utilise un objet company pour représenter un point de vente physique. Chaque company possède sa propre clé d'API, disponible sur my.yavin.com dans l'onglet API.

Chaque requête HTTPS doit être authentifiée et doit contenir Content-Type: application/json.

Conventions

• Les montants sont toujours des entiers, exprimés en centimes, et doivent être positifs (1000 = 10,00 €). N'envoyez jamais de montant négatif : toutes les API ne le rejettent pas (sur l'Android Intent API, sa valeur absolue est débitée)
• Les codes de devise suivent la norme ISO 4217 (EUR, CHF, GBP). La devise réellement utilisée est celle configurée sur le profil du marchand
• Statuts : les résultats des transactions en magasin sont ok ou ko ; les paiements e-commerce ajoutent pending et authorised
• Idempotence : envoyez toujours un idempotentUuid dans les requêtes de paiement, un par tentative de paiement. Voir Gestion de l'IdempotentUuid
• Nommage : la convention (camelCase ou snake_case) varie selon l'API et est indiquée en haut de chaque page d'API

Flux de paiement en magasin

1. Le marchand sélectionne les articles ou le montant sur le logiciel de caisse
2. Le marchand appuie sur le bouton de paiement du logiciel de caisse
3. Le logiciel de caisse appelle la route de paiement avec le type debit et un idempotentUuid
4. Le client paie sur le terminal

Paiement réussi : la réponse est prise en compte sur le logiciel de caisse, y compris les pourboires (sous forme de trop-perçu, « trop perçu »), le cas échéant.

Paiement échoué : dans chacun des cas suivants, le paiement est abandonné, la réponse parvient au logiciel de caisse et vous pouvez lancer un nouveau paiement (avec un nouvel idempotentUuid) :

• Le client met plus de 60 secondes sur les écrans de pourboire ou d'avis
• Le client met plus de 60 secondes pour présenter sa carte
• La carte est refusée par la passerelle de paiement

Flux de paiement en ligne

1. Le client sélectionne des articles sur votre site web et clique sur payer ; votre serveur est notifié
2. Votre serveur appelle l'API Yavin pour générer un lien de paiement
3. Le serveur Yavin renvoie un lien de paiement unique
4. Votre serveur redirige le client vers le lien de paiement (page hébergée par Yavin)
5. Le client saisit ses informations de paiement dans le widget
6. Yavin appelle votre return_url_success ou return_url_cancelled (GET avec cartId et status dans les paramètres de requête) et votre webhook_url avec le résultat du paiement
7. Votre serveur traite le résultat et affiche les informations pertinentes au client

Consultez la page E-commerce API pour les modes de capture (immédiate ou différée), la durée de vie du lien de paiement, les statuts et le comportement en cas de paiements multiples.

Codes d'erreur HTTP

Formats des réponses d'erreur

La structure du corps de l'erreur dépend de la famille d'endpoints. Écrivez un gestionnaire par structure ; ne supposez pas un format unique pour toutes les API.