Authentification

API Keys

Toutes les requêtes vers l'API externe nécessitent une clé API valide dans l'en-tête HTTP X-API-KEY.

En-têtes requis

Exemple

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Environnements

L'API externe dispose de deux environnements indépendants : Live et Test. Chaque environnement a ses propres clés API, son propre client secret et ses propres données (totalement isolées l'une de l'autre).

Clés API Live

Les clés API Live traitent des paiements réels via le processeur. N'utilisez des clés Live que lorsque votre intégration est entièrement validée.

Clés API Test

Les clés API Test permettent de tester toute l'intégration sans mouvement d'argent réel. Les paiements sont simulés, les webhooks sont générés automatiquement et les données sont stockées de manière totalement isolée.

Flux d'intégration recommandé : Commencez toujours avec une clé API Test. Développez et validez toute votre intégration. Lorsque tout fonctionne correctement, créez une clé API Live et modifiez les URLs (ajoutez ou retirez /test/).

Restriction par IP

Les clés API peuvent avoir des restrictions IP configurées depuis le tableau de bord. Si votre IP n'est pas dans la liste autorisée, vous recevrez une erreur 403 Forbidden.

Recommandation : Configurez des restrictions IP en production pour plus de sécurité. En environnement Test, vous pouvez laisser les IP sans restriction pour faciliter le développement.

Restriction par webcode

Chaque clé API est liée à un webcode spécifique (identifiant de votre entreprise dans Avirato Payments). Vous ne pouvez opérer qu'avec le webcode associé à votre clé.

Le champ webcode est obligatoire dans toutes les requêtes et doit correspondre au webcode de votre clé API.

Scopes

Les clés API ont un scope qui détermine les endpoints accessibles :

Une clé Live ne peut pas accéder aux routes Test, et inversement.

Idempotence

Les endpoints d'écriture (création de session, modifications, paiement POS) prennent en charge l'en-tête Idempotency-Key. Si vous envoyez la même Idempotency-Key avec les mêmes paramètres :

1. La première requête est traitée normalement
2. Les requêtes suivantes avec la même clé renvoient la même réponse sans réexécuter l'opération

L'idempotence fonctionne de manière identique dans les deux environnements (Live et Test). Les enregistrements d'idempotence de chaque environnement sont isolés l'un de l'autre.

Conflits d'idempotence (409)

Si vous réutilisez une Idempotency-Key de manière incorrecte, l'API répond avec 409 Conflict pour éviter des comportements incohérents :

Recommandation : utilisez Idempotency-Key systématiquement en production pour éviter les encaissements en double, mais associez une clé unique par tentative logique (par exemple, dérivée de orderId + retry). Si vous devez modifier le body, utilisez une nouvelle clé.

# Premier appel : crée le paiement
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Deuxième appel avec la même clé et le même body : renvoie la même réponse sans créer un autre paiement
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Troisième appel avec la même clé mais un body différent : 409 Conflict
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 99999, "currency": "EUR" }, ... }'

Client Secret

Chaque environnement a son propre client secret. Le client secret sert à déchiffrer les données chiffrées reçues dans la redirection post-paiement (paramètre data dans la urlOk).

• Client secret Live : généré lors de la création de la première clé API Live.
• Client secret Test : généré lors de la création de la première clé API Test.

Le client secret n'est affiché qu'une seule fois au moment de la création de la première clé de l'environnement. Si vous le perdez, vous pouvez le faire tourner depuis le tableau de bord (section Intégrations > API Keys > Roter le secret).

Important : Les client secrets Live et Test sont différents. Assurez-vous d'utiliser le bon secret pour déchiffrer les données de redirection dans chaque environnement.

Gestion des clés API

Les clés API se gèrent depuis le tableau de bord Avirato Payments (section Intégrations > API Keys) :