Introduction
VALIDIF API
One API to accept card payments, send payouts and receive events.
Base URL et environnement
Toutes les requêtes utilisent HTTPS et la base https://api.validif.com. Seul l'environnement Sandbox est disponible : aucune transaction réelle n'est traitée.
Authentification
Chaque requête serveur porte votre clé secrète Sandbox dans l'en-tête Authorization: Bearer vl_sec_sandbox_…. La clé secrète n'est affichée qu'une seule fois, à sa création, et n'est jamais stockée en clair. Générez-la depuis votre espace marchand.
Premier appel
Créez un paiement de 2 500,00 XOF (montants en unité mineure, entiers uniquement) :
POST /v1/payment_intents
curl https://api.validif.com/v1/payment_intents \
-H "Authorization: Bearer vl_sec_xxxxx" \
-H "Idempotency-Key: order_98231" \
-H "Content-Type: application/json" \
-d '{
"amount": 250000,
"currency": "XOF",
"capture_method": "automatic"
}'Idempotence
Les requêtes de création acceptent l'en-tête Idempotency-Key. Une même clé rejouée dans les 24 heures renvoie la réponse d'origine au lieu de créer une seconde ressource.
Erreurs normalisées
Les erreurs sont normalisées et n'exposent jamais les détails d'un fournisseur. Chaque réponse porte un request_id à citer en support.
422 Unprocessable Entity
{
"error": {
"code": "validation_error",
"message": "amount must be a positive integer",
"request_id": "req_8f21c0d4"
}
}| Champ | Type | Description |
|---|---|---|
| authentication_error | 401 | Clé API absente ou invalide. |
| authorization_error | 403 | Accès refusé à la ressource. |
| validation_error | 422 | Paramètre manquant ou invalide. |
| idempotency_conflict | 409 | Clé d'idempotence réutilisée avec un autre payload. |
| rate_limit | 429 | Trop de requêtes. |
| provider_timeout | 504 | Le fournisseur n'a pas répondu dans le délai. |