Reference
API Reference
Une API REST prévisible : JSON en entrée et en sortie, montants en unités mineures, créations idempotentes et erreurs normalisées.
Base URL
Base unique
https://api.validif.com/v1
Une seule base d'API sert les deux environnements. L'environnement est déterminé par la clé secrète envoyée : sk_sandbox_… pour les tests, sk_live_… pour le traitement réel. Les données des deux environnements sont totalement isolées.
Exemple
curl -X POST https://api.validif.com/v1/payments \
-H "Authorization: Bearer sk_sandbox_..." \
-H "Idempotency-Key: order-1042" \
-H "Content-Type: application/json" \
-d '{"amount":250000,"currency":"XOF","description":"Commande 1042"}'Les clés sk_live_… sont délivrées après validation de votre société. Voir Request Production Access.
Conventions
| Champ | Type | Description |
|---|---|---|
| amount | integer | Toujours en unités mineures (250000 = 2 500,00). |
| currency | string | Code ISO 4217 en majuscules. |
| id | string | Identifiant opaque préfixé par type d'objet. |
| status | string | État issu d'une machine à états stricte. |
| created_at | string | Horodatage ISO 8601 en UTC. |
Idempotence
Envoyez un en-tête Idempotency-Key unique par opération métier sur chaque création. Rejouer le même appel avec la même clé renvoie l'objet initial ; réutiliser la clé avec un autre payload renvoie idempotency_conflict (409).
Pagination
Les endpoints de liste renvoient les objets les plus récents d'abord et acceptent limit. Les résultats sont toujours limités à votre propre société.
Endpoints
| Champ | Type | Description |
|---|---|---|
| GET /v1/ping | Status | Vérifier la disponibilité de l'API (sans authentification). |
| GET /v1/me | Account | Société, environnement et scopes de la clé utilisée. |
| POST /v1/payments | Payments | Créer un paiement (retourne une checkout_url). |
| GET /v1/payments | Payments | Lister les paiements de l'environnement courant. |
| GET /v1/payments/:id | Payments | Lire un paiement. |
| GET /v1/payments/:id/events | Payments | Historique des événements d'un paiement. |
| POST /v1/payments/:id/authorize | Payments | Autoriser le paiement. |
| POST /v1/payments/:id/capture | Payments | Capturer un paiement autorisé. |
| POST /v1/payments/:id/cancel | Payments | Annuler un paiement non capturé. |
| POST /v1/payments/:id/fail | Payments | Marquer un paiement en échec. |
| POST /v1/payouts | Payouts | Créer un payout vers une destination éligible. |
| GET /v1/payouts | Payouts | Lister les payouts. |
| GET /v1/payouts/:id | Payouts | Lire un payout. |
Détail des paramètres et des transitions : Payments, Payouts, Webhooks et Errors.