API - Retrait
Les conventions générales s'appliquent : en-têtes, enveloppe de réponse, pagination et codes d'erreur.
Demander un retrait
POST /api/public/v1/cash-outs/{wallet}/create
Le portefeuille source est passé dans l'URL. La destination provient de la configuration cash_out de ce portefeuille — elle ne se transmet pas dans le corps de la requête.
Paramètres
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
amount | entier | Non | Montant en ariary. Si omis, l'API retire le maximum possible, sorties en attente et frais déduits. |
description | string | Non | Mémo métier, 100 caractères maximum. |
Exemple
curl --request POST \
"https://efn.efaina.com/api/public/v1/cash-outs/a3bb189e-b1be-49d4-aec2-a9b02d7a5c20/create" \
--header "Authorization: Bearer VOTRE_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"amount": 250000,
"description": "Règlement fournisseur mensuel"
}'
Erreurs spécifiques
| Code | Cas |
|---|---|
422 sur amount | Solde disponible insuffisant, ou un retrait est déjà en cours sur ce portefeuille. |
422 sur detail_method | Le portefeuille n'a pas de configuration cash_out. Mettez-le à jour d'abord. |
422 sur detail_method.phone | Le numéro ne correspond à aucun opérateur mobile connu. |
403 | Le portefeuille appartient à un autre compte. |
Retraits en masse
POST /api/public/v1/cash-outs/mass/create
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
items | tableau | Oui | Liste des retraits à effectuer. |
items[].wallet_id | uuid | Oui | Portefeuille à débiter, appartenant à votre compte. |
items[].amount | entier | Non | Montant ; vide pour retirer le maximum. |
items[].description | string | Non | Mémo propre à cette ligne. |
curl --request POST \
"https://efn.efaina.com/api/public/v1/cash-outs/mass/create" \
--header "Authorization: Bearer VOTRE_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"items": [
{ "wallet_id": "8f7e39c2-0b3f-4a1c-9b2d-7f3e9b4c1d2a", "amount": 150000, "description": "Paie semaine 12" },
{ "wallet_id": "a3bb189e-b1be-49d4-aec2-a9b02d7a5c20" }
]
}'
La réponse est un 202 : le lot est mis en file et traité de façon asynchrone.
{
"statusHttp": "success",
"message": "…",
"response": {
"batch_id": "e4c2a1f0-9d3b-4c58-8a71-2f6b0d9e4c11",
"total": 2
}
}
Chaque ligne est traitée indépendamment : une ligne en échec n'annule pas les autres. Le suivi passe par les évènements cash-out.mass.completed et cash-out.mass.failed de votre webhook, qui portent le batch_id et la position de la ligne concernée.
Lister les retraits
GET /api/public/v1/cash-outs
Renvoie vos retraits sous forme paginée, avec les filtres communs. Champs filtrables notables : filter[wallet_id], filter[status.slug], between[amount], between[created_at].
{
"id": "09c18b51-f7f8-4b36-a49f-89f003eb1a3e",
"amount": 250000,
"date": "2024-06-15T09:20:03.000000Z",
"wallet": "a3bb189e-b1be-49d4-aec2-a9b02d7a5c20",
"status": "pending"
}