Retraits
Un retrait envoie une partie de votre solde vers un numéro MonCash ou NatCash. Chaque retrait est vérifié puis envoyé à la main par notre équipe : il n’y a pas de transfert automatique.
POST/v1/withdrawalspermission withdrawals:write, Idempotency-Key obligatoire
curl https://moncashapi.fedtopup.com/api/v1/withdrawals \
-H "Authorization: Bearer $MONCASHAPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: retrait-2026-09-30-001" \
-d '{
"amount": 10000,
"wallet": "moncash",
"phone": "37123456",
"name": "Jean Pierre"
}'const reponse = await fetch("https://moncashapi.fedtopup.com/api/v1/withdrawals", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MONCASHAPI_SECRET_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "retrait-2026-09-30-001", // obligatoire
},
body: JSON.stringify({ amount: 10000, wallet: "moncash", phone: "37123456", name: "Jean Pierre" }),
});
const retrait = await reponse.json();
// retrait.status === "requested" : la demande attend notre équipeimport { randomUUID } from "node:crypto";
// Gardez la clé d'idempotence avec votre demande : en cas de coupure, renvoyez la MÊME.
const cle = randomUUID();
const reponse = await fetch("https://moncashapi.fedtopup.com/api/v1/withdrawals", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MONCASHAPI_SECRET_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": cle,
},
body: JSON.stringify({ amount: 10000, wallet: "moncash", phone: "37123456", name: "Jean Pierre" }),
});
const retrait = await reponse.json();
if (!reponse.ok) throw new Error(retrait.error.code);<?php
$ch = curl_init("https://moncashapi.fedtopup.com/api/v1/withdrawals");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("MONCASHAPI_SECRET_KEY"),
"Content-Type: application/json",
"Idempotency-Key: retrait-2026-09-30-001",
],
CURLOPT_POSTFIELDS => json_encode([
"amount" => 10000,
"wallet" => "moncash",
"phone" => "37123456",
"name" => "Jean Pierre",
]),
]);
$retrait = json_decode(curl_exec($ch), true);
curl_close($ch);import os
import requests
reponse = requests.post(
"https://moncashapi.fedtopup.com/api/v1/withdrawals",
headers={
"Authorization": f"Bearer {os.environ['MONCASHAPI_SECRET_KEY']}",
"Idempotency-Key": "retrait-2026-09-30-001",
},
json={"amount": 10000, "wallet": "moncash", "phone": "37123456", "name": "Jean Pierre"},
timeout=20,
)
retrait = reponse.json()Paramètres
| Champ | Type | Description |
|---|---|---|
amount | entier, requis | Montant à envoyer, en gourdes entières (minimum 1 500 GDS vers MonCash, 5 000 GDS vers NatCash ; maximum 50 000 GDS). |
wallet | texte, requis | moncash ou natcash. |
phone | texte, requis | Numéro de réception : 8 chiffres, avec ou sans +509. |
name | texte, requis | Nom du bénéficiaire (2 à 80 caractères), tel qu’il figure sur le compte. |
metadata | objet | Vos propres données (4 Ko au plus). |
Frais
Les frais de retrait sont de 5 %. Ils s’ajoutent au montant envoyé : le total est débité de votre solde.
- Montant
- 10 000 GDS
- Frais de retrait
- 500 GDS
- Total débité
- 10 500 GDS
À la demande, le total est réservé : il quitte balance.available pour balance.reserved. Si la demande est refusée ou annulée, il redevient disponible, en entier.
L’objet retrait
{
"id": "wd_8b1e4c7a90d2f3a5c6e7",
"object": "withdrawal",
"status": "requested",
"amount": 10000,
"fee": 500,
"total": 10500,
"currency": "HTG",
"wallet": "moncash",
"phone": "+50937123456",
"name": "Jean Pierre",
"reason": null,
"transfer_reference": null,
"project_id": "prj_5d2a9c4e1b7f4a0c8e3d6f1a2b4c5d6e",
"created_at": "2026-09-30T14:40:12.003Z",
"updated_at": "2026-09-30T14:40:12.003Z",
"completed_at": null
}Les statuts
| Champ | Type | Description |
|---|---|---|
requested | en attente | Demande reçue, pas encore prise en charge. Encore annulable depuis le tableau de bord. |
under_review | en attente | Un membre de notre équipe examine la demande. |
approved | en cours | Demande approuvée, transfert à effectuer. |
processing | en cours | Le transfert est en train d’être effectué. |
completed | terminé | Transfert envoyé. transfer_reference porte la référence du transfert. |
rejected | refusé | Demande refusée ; reason donne le motif. La réservation est libérée. |
cancelled | annulé | Demande annulée par vous avant sa prise en charge. |
failed | échec | Le transfert n’a pas abouti ; reason donne le motif. La réservation est libérée. |
Webhooks envoyés : withdrawal.requested, withdrawal.processing, withdrawal.completed, withdrawal.rejected, withdrawal.cancelled, withdrawal.failed.
Lire et lister
GET/v1/withdrawalspermission withdrawals:read
GET/v1/withdrawals/:idpermission withdrawals:read
Filtres : status, limit, cursor.
Erreurs fréquentes
| Champ | Type | Description |
|---|---|---|
402 INSUFFICIENT_BALANCE | — | Le solde disponible ne couvre pas le montant et ses frais. |
400 AMOUNT_TOO_LOW / AMOUNT_TOO_HIGH | — | Montant hors des bornes du portefeuille choisi. |
400 INVALID_PHONE / INVALID_NAME / INVALID_WALLET | — | Numéro, nom ou portefeuille invalide. |
409 TOO_MANY_OPEN_WITHDRAWALS | — | Trop de retraits en cours : attendez qu’ils soient traités. |
400 IDEMPOTENCY_KEY_REQUIRED | — | L’en-tête Idempotency-Key est obligatoire pour créer un retrait. |
503 WITHDRAWALS_PAUSED | — | Les retraits sont temporairement suspendus ; votre solde n’est pas touché. |