API AWDPay Transfers

L'API AWDPay Transfers vous permet de transférer des fonds entre comptes AWDPay sans passer par des opérateurs externes (Mobile Money). C'est un transfert interne instantané sur le registre AWDPay.

Configuration spéciale

Pour les transferts AWDPay, utilisez toujours :

• gatewayName : "awdpay"
• country : "AF" (Afrique - code interne AWDPay)

Cas d'usage

• 🛒 Marketplaces — Créditer les vendeurs instantanément après une vente
• 💰 Applications wallet — Financer les sous-comptes utilisateur
• 🎁 Programmes de fidélité — Transférer des récompenses entre membres
• 🔄 Transferts P2P — Permettre les transferts entre utilisateurs AWDPay
• 🏢 Inter-filiales — Mouvements de fonds entre entités du même groupe

Directions de transfert

Direction	API	Description
Utilisateur → Marchand	Collections (Dépôt)	L'utilisateur AWDPay paie le marchand
Marchand → Utilisateur	Disbursements (Retrait)	Le marchand envoie des fonds à un utilisateur AWDPay

---

Collection AWDPay (Utilisateur → Marchand)

Recevoir des paiements d'un compte AWDPay vers votre solde marchand.

Endpoint

POST /api/deposits/initiate

Exemple de requête

curl -X POST "https://app.awdpay.com/api/deposits/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "customerName": "Jean Dupont",
    "customerPhone": "+221770123456",
    "customerEmail": "jean@example.com",
    "country": "AF",
    "gatewayName": "awdpay",
    "callbackUrl": "https://merchant.example/webhooks/collections",
    "metadata": {
      "orderReference": "ORDER-1192",
      "userId": "usr_12345"
    }
  }'

Paramètres spécifiques

Paramètre	Valeur	Description
country	"AF"	Code pays spécial pour AWDPay interne
gatewayName	"awdpay"	Passerelle AWDPay interne
customerPhone	String	Numéro associé au compte AWDPay du payeur

Réponse

{
  "reference": "DEP1704067200000ABC123",
  "status": "pending",
  "fees": 0,
  "paymentType": "otp",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "message": "En attente de confirmation OTP"
}

---

Disbursement AWDPay (Marchand → Utilisateur)

Envoyer des fonds de votre solde marchand vers un compte AWDPay.

Endpoint

POST /api/withdraws/initiate

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": "Marie Ndiaye",
    "beneficiaryPhone": "+221771234567",
    "beneficiaryEmail": "marie@example.com",
    "country": "AF",
    "gatewayName": "awdpay",
    "callbackUrl": "https://merchant.example/webhooks/disbursements",
    "metadata": {
      "orderReference": "PAYOUT-8831",
      "reason": "Remboursement de commande"
    }
  }'

Paramètres spécifiques

Paramètre	Valeur	Description
country	"AF"	Code pays spécial pour AWDPay interne
gatewayName	"awdpay"	Passerelle AWDPay interne
beneficiaryPhone	String	Numéro associé au compte AWDPay du bénéficiaire

Réponse

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

---

Vérifier le statut

Collection

curl -X GET "https://app.awdpay.com/api/deposits/DEP1704067200000ABC123" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

Disbursement

curl -X GET "https://app.awdpay.com/api/withdraws/WTD1704067200000DEF456" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

---

Avantages des transferts AWDPay

Fonctionnalité	Transfert AWDPay	Mobile Money
Frais	0% ou réduits	Variables par opérateur
Vitesse	⚡ Instantané	5 sec - 2 min
Disponibilité	24/7	Dépend de l'opérateur
Confirmation	OTP (Collection) / Direct (Disbursement)	Variable
Limite	Selon votre plan	Limites opérateur

---

Règles spécifiques

Vérification du solde

AWDPay vérifie le solde des deux parties :

• Collection : Le compte AWDPay du payeur doit avoir des fonds suffisants
• Disbursement : Votre solde marchand doit être suffisant

{
  "error": "insufficient_balance",
  "message": "Le compte du payeur n'a pas de fonds suffisants"
}

Confirmation OTP (Collections)

Pour les collections, le payeur reçoit un OTP pour confirmer :

1. Vous initiez la collection
2. Le payeur reçoit un SMS avec le code OTP
3. Le payeur confirme le paiement dans l'application AWDPay
4. Le statut passe de pending → success

Transferts directs (Disbursements)

Les disbursements vers un compte AWDPay sont instantanés et ne nécessitent pas de confirmation du bénéficiaire.

---

Webhooks

Les événements utilisent les mêmes sujets que les autres méthodes :

Collection réussie

{
  "event": "deposit.success",
  "timestamp": "2025-01-15T10:30:45Z",
  "data": {
    "reference": "DEP1704067200000ABC123",
    "status": "success",
    "amount": 5000.00,
    "currency": "XOF",
    "gatewayName": "awdpay",
    "country": "AF",
    "customerPhone": "+221770123456",
    "metadata": {
      "orderReference": "ORDER-1192"
    }
  }
}

Disbursement réussi

{
  "event": "withdrawal.success",
  "timestamp": "2025-01-15T10:31:00Z",
  "data": {
    "reference": "WTD1704067200000DEF456",
    "status": "success",
    "amount": 5000.00,
    "currency": "XOF",
    "gatewayName": "awdpay",
    "country": "AF",
    "beneficiaryPhone": "+221771234567",
    "metadata": {
      "orderReference": "PAYOUT-8831"
    }
  }
}

---

Rapprochement

Dans le tableau de bord AWDPay et les exports :

• Les transferts AWDPay sont identifiés par gatewayName: "awdpay"
• Le champ country: "AF" permet un filtrage facile
• Distinguez-les des mouvements Mobile Money pour vos rapports

---

Prochaines étapes

1. API Collections → Documentation complète des dépôts
2. API Disbursements → Documentation complète des retraits
3. Authentification → Obtenir votre token API
4. Gestion des erreurs → Gérer les cas d'échec