API externe - Guide d'intégration

Qu'est-ce que l'API externe

L'API externe d'Avirato Payments permet aux intégrateurs externes (ERP, plateformes e-commerce, systèmes de gestion, etc.) de traiter les paiements en ligne et les paiements POS de manière sécurisée, sans avoir à connaître l'infrastructure interne du système.

Avec une seule intégration, vous pouvez :

Créer des sessions de paiement en ligne et rediriger le client vers une page de paiement sécurisée
Traiter des paiements POS en envoyant un encaissement directement à un terminal physique
Modifier des paiements : remboursements totaux et partiels, captures de préautorisation, annulations et extensions de préautorisation
Consulter des paiements : obtenir le détail d'une session, lister les sessions avec filtres et pagination, lister les modifications

Environnements : Live et Test

L'API externe propose deux environnements totalement indépendants :

Live	Test
Objectif	Traiter des paiements réels	Intégrer et tester sans argent réel
URL de base	`https://aviratopayments.com/external/v1/`	`https://aviratopayments.com/external/v1/test/`
API Keys	Clés d'environnement Live	Clés d'environnement Test
Paiements en ligne	Processeur réel	Simulation avec cartes fictives
Paiements POS	Terminal physique réel	Simulation immédiate (magic amounts)
Webhooks	Envoyés par le processeur réel	Générés automatiquement par le backend
Argent réel	Oui	Non

Recommandation : Intégrez d'abord dans l'environnement Test pour vérifier que votre système fonctionne correctement. Une fois validé, passez en Live en utilisant simplement votre clé API de production et en supprimant /test/ des URLs.

URL de base

Live: https://aviratopayments.com/external/v1/
Test: https://aviratopayments.com/external/v1/test/

Tous les endpoints de cette documentation affichent l'URL complète de l'environnement Live. Pour utiliser l'environnement Test, insérez /test/ après /v1/. Par exemple :

Live : POST https://aviratopayments.com/external/v1/payment/session
Test : POST https://aviratopayments.com/external/v1/test/payment/session

Authentification rapide

Toutes les requêtes nécessitent une clé API dans l'en-tête X-API-KEY :

X-API-KEY: votre_cle_api_ici

Les clés API se gèrent depuis le tableau de bord Avirato Payments (section Intégrations > API Keys). Chaque clé est liée à un webcode (identifiant d'entreprise) et à un environnement (Live ou Test).

De plus, toutes les requêtes POST acceptent optionnellement l'en-tête Idempotency-Key pour éviter les opérations en double. Nous recommandons de l'utiliser systématiquement en production. Réutiliser la même clé avec un body différent ou un autre endpoint renvoie 409 Conflict (voir Authentification et Gestion des erreurs).

Pour plus de détails : Authentification

Structure des réponses

Réponse réussie

Toutes les réponses réussies suivent cette structure :

{
  "success": true,
  "data": { ... }
}

Le contenu de data varie selon l'endpoint. Le champ success est toujours true pour les réponses 2xx.

Réponse en erreur

{
  "success": false,
  "error": {
    "message": "Description de l'erreur en anglais",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123..."
  }
}

Le traceId est unique par requête. Incluez-le toujours lorsque vous contactez le support technique. Voir Gestion des erreurs pour le catalogue complet.

Concepts clés avant de commencer

Session vs paiement (pour les paiements en ligne)

Il est essentiel de comprendre cette distinction :

Session (sessionId) : l'intention d'encaissement que votre système crée. Elle contient le montant, les URLs de retour, etc.
Paiement (paymentReference) : la transaction réelle autorisée par le processeur. Elle n'existe que lorsque le client finalise le paiement avec succès.

Règle pratique : utilisez sessionId pour consulter l'état. Utilisez paymentReference pour modifier (rembourser, capturer, annuler, prolonger).

Voir Paiements en ligne - Session vs paiement pour l'explication complète.

Opérations asynchrones

Les modifications (refund, capture, cancel, extend) sont asynchrones. L'API accepte la requête immédiatement (HTTP 202) mais l'opération est traitée en arrière-plan. L'état initial est pending (remboursements) ou received (capture, cancel, extend) et évolue vers success ou failed lorsque le processeur confirme.

Les paiements POS sont synchrones : la requête attend la réponse du terminal.

En environnement Test : les modifications se résolvent presque immédiatement (le backend simule la réponse du processeur). Vous recevrez le webhook de confirmation en quelques secondes.

Flux d'intégration typique

1. Paiement en ligne

Votre système                   Avirato Payments                  Client
    |                                    |                              |
    |-- POST /payment/session ---------->|                              |
    |<-- 201 { sessionId, paymentUrl } --|                              |
    |                                    |                              |
    |-- Redirige le client -------------->+---------------------------->|
    |                                    |     (page de paiement sécurisée)|
    |                                    |<-- Finalise le paiement -------|
    |                                    |                              |
    |                                    |-- Redirige vers urlOk -------->|
    |                                    |   (données chiffrées)         |
    |                                    |                              |
    |-- GET /payment/session/{id} ------>|                              |
    |<-- { status: completed,            |                              |
    |      paymentReference: "..." } ----|                              |
    |                                    |                              |
    |   (Vous pouvez maintenant faire    |                              |
    |    refund, capture, etc. avec      |                              |
    |    paymentRef)                     |                              |

2. Paiement POS

Votre système                   Avirato Payments         Terminal TPE
    |                                    |                      |
    |-- POST /pos/payment ------------->|                      |
    |                                    |-- Envoie l'encaissement ->|
    |                                    |    (le client paie     |
    |                                    |     sur le terminal)  |
    |                                    |<-- Résultat ----------|
    |<-- 200 { status: success,          |                      |
    |          paymentReference } --------|                      |

Note : Ces flux fonctionnent de manière identique en environnement Test, en remplaçant /external/v1/ par /external/v1/test/. La seule différence est qu'en Test le paiement en ligne se finalise avec des cartes fictives et le paiement POS est simulé avec des magic amounts (sans terminal réel).

Différences clés entre Test et Live

Aspect	Live	Test
Paiement en ligne	Le client paie avec une carte réelle sur le formulaire de paiement	Le client utilise des cartes fictives sur un formulaire simulé
Paiement POS	Le terminal physique traite l'encaissement	Le résultat est simulé immédiatement selon le montant
Webhooks	Envoyés par le processeur réel lors de la confirmation	Générés automatiquement par le backend à la fin de la simulation
Modifications	Traitées par le processeur réel (peut prendre secondes/minutes)	Simulées instantanément par le backend
Références	Préfixe `-EXT-`, `-PXT-`, `-POSX-`, `-RFX-`, `-CTX-`, etc.	Préfixe `-EXTT-`, `-PXTT-`, `-POSXT-`, `-RFXT-`, `-CTXT-`, etc.
Argent	Transactions réelles	Aucun mouvement d'argent
Données	Totalement isolées	Totalement isolées (pas de mélange avec le live)

Index des endpoints

Paiements en ligne

Méthode	Endpoint	Description	HTTP Status
POST	`/payment/session`	Créer une session de paiement	201
GET	`/payment/session/{sessionId}`	Obtenir le détail d'une session	200
GET	`/payment/sessions`	Lister les sessions	200

Modifications (paiements en ligne et POS)

Méthode	Endpoint	Description	HTTP Status
POST	`/payment/refund`	Rembourser un paiement	202
POST	`/payment/capture`	Capturer une préautorisation	202
POST	`/payment/cancel`	Annuler une préautorisation	202
POST	`/payment/extend`	Prolonger une préautorisation	202
GET	`/payment/session/{sessionId}/modifications`	Lister les modifications d'une session	200
GET	`/pos/payment/{posPaymentId}/modifications`	Lister les modifications d'un paiement POS	200
GET	`/modifications`	Lister toutes les modifications	200

Paiements POS

Méthode	Endpoint	Description	HTTP Status
GET	`/pos/terminals`	Lister les terminaux actifs	200
POST	`/pos/payment`	Créer un paiement POS	200
GET	`/pos/payments`	Lister les paiements POS	200

Rappel : Pour utiliser un endpoint en environnement Test, ajoutez /test/ après /v1/. Exemple : POST /external/v1/test/payment/session.

Documentation développeurs