Créer un Retrait

Initier un disbursement vers le portefeuille mobile d'un bénéficiaire.

Endpoint

POST /api/withdraws/initiate

Paramètres de requête

Paramètre	Type	Requis	Description
amount	Double	✅	Montant à transférer (min : 0.01)
currency	String	✅	Code devise ISO 4217 (3 caractères, ex. XOF, EUR)
beneficiaryName	String	✅	Nom complet du bénéficiaire
beneficiaryPhone	String	✅	Numéro de téléphone au format international (ex. +221770000000)
beneficiaryEmail	String	❌	Email du bénéficiaire
country	String	✅	Code pays ISO 3166-1 alpha-2 (ex. SN, CI)
gatewayName	String	❌	Passerelle spécifique (sinon sélection automatique)
callbackUrl	String	❌	URL webhook pour notifications (max 500 caractères)
returnUrl	String	❌	URL de redirection après traitement
metadata	Map<String, String>	❌	Données personnalisées (ex. orderReference, userId)

Exemple de requête

curl -X POST "https://app.awdpay.com/api/withdraws/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "beneficiaryName": "Amadou Diallo",
    "beneficiaryPhone": "+221770123456",
    "beneficiaryEmail": "amadou@example.com",
    "country": "SN",
    "gatewayName": "wave-senegal",
    "callbackUrl": "https://merchant.example/webhooks/withdrawals",
    "metadata": {
      "orderReference": "PAYOUT-8831",
      "userId": "usr_12345"
    }
  }'

Réponse succès

{
  "reference": "WTD1704067200000ABC123",
  "status": "pending",
  "fees": 50.0,
  "paymentType": "direct",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "message": "Retrait initié avec succès"
}

Champs de réponse

Champ	Type	Description
reference	String	Référence unique du retrait (format : WTD{timestamp}{random})
status	String	Statut initial (pending, processing)
fees	Double	Montant des frais facturés
paymentType	String	Type de traitement (direct, redirect, redirect_post, ussd)
createdAt	DateTime	Date/heure de création
expiresAt	DateTime	Date/heure d'expiration
message	String	Message descriptif
url	String	URL de confirmation (si paymentType = redirect)

Codes d'erreur

Code HTTP	Code erreur	Description
400	invalid_request	Paramètres manquants ou invalides
401	unauthorized	Token invalide ou expiré
404	merchant_not_found	Compte marchand non trouvé
422	insufficient_balance	Solde marchand insuffisant
422	limit_exceeded	Limite de transaction dépassée
500	server_error	Erreur interne

---

Prochaine étape

➡️ Vérifier le statut — Suivre le statut de votre retrait