8. Solde et retraits

Consultez votre solde puis retirez votre argent vers un compte Mobile Money ou, si un IBAN valide est enregistré dans votre profil, par virement bancaire.

Consulter son solde

GET/merchant/walletJeton de session

Solde disponible par devise, toutes applications confondues. N'additionnez jamais deux devises. Paramètre facultatif : environment=live|test.

Réponse 200

{
  "success": true,
  "data": {
    "balances": {
      "XAF": "980000.00"
    },
    "applications_without_activity": []
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
401	Jeton expiré.
503	Comptabilité momentanément indisponible (`LEDGER_MODULE_UNAVAILABLE`) : réessayer.

Vérifier le titulaire du numéro

POST/withdrawals/account-inquiryJeton de session

Avant un retrait, vérifiez le titulaire du numéro destinataire. Aucun montant n'est engagé. operator vaut orange ou mtn.

Corps de la requête

{
  "operator": "orange",
  "phone_number": "696246686"
}

Réponse 200

{
  "success": true,
  "data": {
    "operator": "orange",
    "phone_number": "696246686",
    "first_name": "PRENOM",
    "last_name": "NOM",
    "full_name": "PRENOM NOM"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
404	`ACCOUNT_NOT_FOUND` : numéro inconnu chez l'opérateur.
422	`operator` ou `phone_number` invalide.
502	`GIMAC_UNAVAILABLE` : vérification momentanément indisponible, réessayer.

Lancer le retrait

POST/withdrawalsJeton de session

Le montant est retenu immédiatement sur votre solde, puis envoyé au réseau. Pour un particulier, application_id est facultatif (votre application personnelle est utilisée).

Corps de la requête

{
  "amount": 15000,
  "destination_provider": "orange_money_cm",
  "destination_phone_number": "696246686",
  "currency": "XAF"
}

Réponse 201

{
  "success": true,
  "data": {
    "uuid": "...",
    "application_id": 1,
    "destination_provider": "orange_money",
    "destination_phone_number": "696246686",
    "amount": 15000,
    "currency": "XAF",
    "status": "pending",
    "failure_reason": null,
    "reference": "OM-9f3a1",
    "created_at": "2026-11-02T12:30:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
422	Solde insuffisant (`INSUFFICIENT_BALANCE`), réseau indisponible, données invalides.

Statut initial : pending (ou success / failed selon la réponse immédiate du réseau). Suivi : GET /withdrawals/{uuid} ; historique : GET /withdrawals.
Si le retrait échoue, le montant retenu est restitué à votre solde.

Retirer par virement bancaire

POST/withdrawalsJeton de session

Ajoutez destination_type: "bank". Le virement est envoyé à l'IBAN enregistré dans votre profil par le réseau GIMAC ; la banque est déduite de l'IBAN. Aucun fournisseur ni numéro de téléphone n'est envoyé dans la requête.

Corps de la requête

{
  "amount": 150000,
  "destination_type": "bank",
  "currency": "XAF"
}

Réponse 201

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-...",
    "application_id": 1,
    "destination_provider": "gimac",
    "destination_phone_number": null,
    "destination_bank": {
      "bank_name": "BICEC",
      "iban": "CM21 1000 5000 ...... 0117"
    },
    "amount": 150000,
    "currency": "XAF",
    "status": "pending",
    "failure_reason": null,
    "reference": "KP00000000000000001",
    "created_at": "2026-11-11T12:30:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
422	IBAN absent ou invalide, banque non participante au réseau GIMAC, devise différente de XAF, ou solde insuffisant.

Conditions : IBAN CEMAC valide (27 caractères et clé de contrôle correcte), banque participante active, devise XAF. Le montant est retenu dès le lancement ; un échec certain est restitué, tandis qu'un incident réseau peut nécessiter un contrôle.
Le retrait peut rester pending plus longtemps qu'un retrait Mobile Money. Le numéro complet d'IBAN est masqué dans destination_bank.iban. Pour modifier l'IBAN, contactez le support.