API AxiaPay

Authentification

Chaque requête porte votre clé secrète dans l'en-tête Authorization. Ne l'exposez jamais dans une application mobile ou un navigateur.

Authorization: Bearer axp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Base URL : https://axiapay.app/api/public/v1

Environnement de test : utilisez la même base sur https://axiapay.app avec une clé dédiée.

1. Encaissement — POST /collections

Débite le client via un push USSD/mobile money. Le montant est exprimé en unité entière de la devise du pays de l'opérateur. Les frais sont déduits : vous recevez net_amount.

curl -X POST https://axiapay.app/api/public/v1/collections \
  -H "Authorization: Bearer axp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "operator": "mtn_bj",
    "phone": "97000000",
    "customer_name": "Awa Diallo",
    "reference": "CMD-1042",
    "callback_url": "https://mon-site.com/axiapay/webhook"
  }'

201 Created
{
  "data": {
    "id": "0f6c1f2c-....",
    "type": "collection",
    "status": "pending",
    "amount": 5000,
    "fee": 275,
    "net_amount": 4725,
    "currency": "XOF",
    "country": "BJ",
    "operator": "mtn_bj",
    "phone": "97000000",
    "reference": "CMD-1042",
    "created_at": "2026-08-20T14:00:00.000Z"
  }
}

2. Décaissement — POST /disbursements

Envoie de l'argent vers un numéro mobile money. Votre portefeuille AxiaPay est débité de net_amount (montant + frais) au moment de la demande. Si l'opération échoue, le montant est automatiquement recrédité. Sans solde suffisant dans la devise concernée, la requête est refusée (insufficient_funds).

curl -X POST https://axiapay.app/api/public/v1/disbursements \
  -H "Authorization: Bearer axp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "operator": "orange_ci",
    "phone": "0700000000",
    "recipient_name": "Kofi Mensah",
    "reference": "PAYOUT-88"
  }'

3. Statut — GET /operations/{id}

Renvoie l'état à jour d'une opération (pending, success, failed). Le statut est rafraîchi auprès du prestataire à chaque appel.

curl https://axiapay.app/api/public/v1/operations/0f6c1f2c-.... \
  -H "Authorization: Bearer axp_live_xxx"

4. Portefeuille — GET /balance

Renvoie le solde disponible de votre portefeuille, par devise. Les encaissements réussis créditent le solde du montant net ; les décaissements le débitent.

curl https://axiapay.app/api/public/v1/balance -H "Authorization: Bearer axp_live_xxx"

{
  "data": {
    "balances": [
      { "currency": "XOF", "balance": 124500 }
    ]
  }
}

5. Catalogue — GET /operators

Liste les opérateurs actifs, leur pays et leur devise. Utilisez la valeur operator dans vos requêtes.

curl https://axiapay.app/api/public/v1/operators -H "Authorization: Bearer axp_live_xxx"

6. Webhooks

À chaque changement de statut, AxiaPay envoie un POST JSON à votre URL de notification.

POST https://mon-site.com/axiapay/webhook
X-AxiaPay-Event: collection.success
X-AxiaPay-Signature: 3f2b... (HMAC-SHA256 hex du corps brut)

{
  "event": "collection.success",
  "sent_at": "2026-08-20T14:01:12.000Z",
  "data": { "id": "0f6c1f2c-....", "status": "success", "amount": 5000, "reference": "CMD-1042" }
}

Vérifiez toujours la signature avec le secret whsec_… de votre clé, puis répondez 200. Événements : collection.success, collection.failed, disbursement.success, disbursement.failed.

// Node.js
import crypto from "node:crypto";

const expected = crypto
  .createHmac("sha256", process.env.AXIAPAY_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (expected !== req.headers["x-axiapay-signature"]) return res.status(401).end();

7. Erreurs

401 unauthorized      → clé API absente, invalide ou désactivée
422 invalid_request   → champ manquant ou format incorrect
400 operation_failed  → opérateur/pays indisponible ou refus du réseau mobile
404 not_found         → opération inconnue pour cette clé