Référence API

Base URL

Toutes les requêtes doivent être adressées à :

https://api.alphapay.me/api/v1

Authentification

Toutes les routes marchand nécessitent votre clé API secrète, transmise dans le header Authorization au format Bearer :

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Utilisez une clé sk_test_... en environnement de test, sk_live_... en production. Retrouvez vos clés API dans votre tableau de bord, section Développeur.

Votre clé secrète donne accès complet à votre compte marchand (encaissement, retraits, solde). Ne l’exposez jamais côté client (navigateur, application mobile) — utilisez-la uniquement depuis votre backend.

Format des réponses

Toutes les réponses de l’API partagent la même enveloppe, qu’il s’agisse d’un succès ou d’une erreur.

{
  "success": true,
  "data": { },
  "code": 200
}

{
  "success": false,
  "error": {
    "message": "Solde disponible insuffisant.",
    "code": "insufficient_balance"
  },
  "code": 422
}

Le champ error prend deux formes selon le type d’erreur :

Erreur métier ({"message": "...", "code": "..."}) — un code d’erreur stable que vous pouvez tester dans votre code, ex. insufficient_balance, merchant_suspended.
Erreur de validation ({"champ": ["message"], "autre_champ": ["message"]}) — une entrée par champ invalide du corps de la requête.

Codes d’erreur HTTP

Code	Signification
`400`	Corps de requête invalide (champ manquant, format incorrect)
`401`	Clé API manquante, invalide ou expirée
`403`	Ressource n’appartenant pas à votre compte, ou compte suspendu
`404`	Ressource introuvable
`409`	Conflit d’état (ex. `Idempotency-Key` déjà utilisée avec un autre payload, transaction déjà dans un état terminal)
`410`	Ressource expirée (ex. lien de paiement ou session de checkout arrivé à expiration)
`422`	Requête valide mais impossible à exécuter en l’état (ex. solde insuffisant)
`429`	Trop de requêtes — respectez la limite de débit

Idempotence

Le header Idempotency-Key est optionnel : c’est vous qui décidez, requête par requête, si AlphaPay doit dédupliquer.

Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Sans le header — chaque appel est traité comme une intention nouvelle. Deux requêtes identiques créent deux opérations distinctes. Avec le header — une valeur unique que vous générez par intention logique d’opération (un UUID, par exemple) :

Rejeu	Résultat
Même clé, même corps	La réponse exacte du 1^er appel est renvoyée (même code HTTP, même contenu). Rien n’est recréé.
Même clé, corps différent	`409 Conflict` — la clé est déjà associée à une autre requête.
Même clé, 1^er appel encore en cours	`409 Conflict` — évite deux exécutions concurrentes.

Optionnel ne veut pas dire facultatif en pratique. Sur les endpoints qui déplacent de l’argent — POST /payments/softpay/initialize/, POST /payouts/initialize/, POST /settlements/, POST /wallet-transfers/, POST /payments/{id}/retry/ — un retry réseau sans clé crée un second débit réel. Envoyez-la systématiquement sur ces routes.

Générez une nouvelle Idempotency-Key à chaque nouvelle intention de paiement, mais réutilisez la même clé pour chaque retry réseau de cette même tentative. Un timeout ou une coupure réseau n’est jamais la preuve que la requête a échoué : elle a pu aboutir côté serveur.

Limite de débit

Les appels authentifiés (clé API ou dashboard) sont limités à 300 requêtes par minute par compte par défaut. Un dépassement renvoie 429 Too Many Requests. Espacez vos appels ou mettez en cache les réponses peu volatiles (ex. liste des pays/réseaux supportés).

Ressources

Paiements

Encaissez via checkout hébergé ou softpay

Liens de paiement

Créez des liens de paiement réutilisables

Retraits

Payez un bénéficiaire en mobile money

Wallet

Consultez vos soldes et les taux de change

Webhooks

Recevez vos événements en temps réel

Créer un compte

Inscription, KYC, première clé API

Vue d'ensemble

Encaisser

Transactions

Liens de paiement

Décaissements

Solde & taux de change

Webhooks

Référentiels

Base URL

Authentification

Format des réponses

Codes d’erreur HTTP

Idempotence

Limite de débit

Ressources

Paiements

Liens de paiement

Retraits

Wallet

Webhooks

Créer un compte

​Base URL

​Authentification

​Format des réponses

​Codes d’erreur HTTP

​Idempotence

​Limite de débit

​Ressources

Paiements

Liens de paiement

Retraits

Wallet

Webhooks

Créer un compte

Base URL

Authentification

Format des réponses

Codes d’erreur HTTP

Idempotence

Limite de débit

Ressources