Payout API
Permettez à vos marchands d'effectuer des payouts instantanés vers Mobile Money et comptes bancaires.
Capacités principales
- Payouts individuels instantanés
- Payouts en masse (jusqu'à 1000)
- Suivi en temps réel
- Webhooks de notification
Providers supportés
- Wave, Orange Money, MTN, Moov
- Virements bancaires IBAN
- Support multi-devise
- Cryptage des données
Authentification
Toutes les requêtes doivent inclure un Bearer Token valide.
Authorization: Bearer YOUR_MERCHANT_API_KEYWallets
GET
/api/v1/merchant/wallets
Récupère la liste des wallets du marchand.
{
"success": true,
"data": {
"wallets": [
{
"id": "uuid",
"name": "Wallet Principal",
"type": "payout",
"currency": "XOF",
"balance": 5000000,
"available_balance": 4800000,
"pending_balance": 200000,
"status": "active",
"daily_limit": 10000000,
"daily_spent": 1500000,
"daily_remaining": 8500000,
"created_at": "2026-02-09T15:00:00Z"
}
]
}
}
POST
/api/v1/merchant/wallets
Crée un nouveau wallet.
Request:
{
"name": "Wallet Fournisseurs",
"type": "payout",
"currency": "XOF",
"daily_limit": 5000000,
"monthly_limit": 50000000
}
POST
/api/v1/merchant/wallets/{uuid}/recharge
Recharge un wallet depuis le solde marchand.
Request:
{
"amount": 1000000,
"source": "merchant_balance"
}💸 Payouts
POST
/api/v1/merchant/payouts
Initie un payout vers un bénéficiaire.
Request:
{
"wallet_id": "uuid",
"recipient": {
"name": "Jean Kouassi",
"phone": "+2250709876543",
"email": "jean@example.com"
},
"destination": {
"type": "mobile_money",
"provider": "wave",
"account": "+2250709876543"
},
"amount": 50000,
"currency": "XOF",
"description": "Salaire Janvier 2026",
"metadata": {
"employee_id": "EMP-001"
},
"idempotency_key": "unique-key-123"
}Response:
{
"success": true,
"message": "Payout initié avec succès",
"data": {
"payout": {
"id": "uuid",
"reference": "PYT-260209-XYZ789",
"status": "pending",
"amount": 50000,
"fees": 750,
"net_amount": 50000,
"created_at": "2026-02-09T15:00:00Z"
}
}
}
GET
/api/v1/merchant/payouts
Liste les payouts avec filtres optionnels.
Paramètres: status, from, to, limit
GET
/api/v1/merchant/payouts/{reference}
Récupère les détails d'un payout spécifique.
POST
/api/v1/merchant/payouts/{reference}/cancel
Annule un payout en attente.
Request:
{
"reason": "Erreur de montant"
}📦 Batch Payouts
POST
/api/v1/merchant/payouts/batch
Crée un batch payout pour traiter plusieurs payouts à la fois (max 1000).
Request:
{
"wallet_id": "uuid",
"name": "Salaires Janvier 2026",
"payouts": [
{
"recipient_name": "Jean Kouassi",
"recipient_phone": "+2250709876543",
"destination_type": "mobile_money",
"destination_provider": "wave",
"destination_account": "+2250709876543",
"amount": 50000,
"description": "Salaire"
},
{
"recipient_name": "Marie Traore",
"recipient_phone": "+2250701234567",
"destination_type": "mobile_money",
"destination_provider": "orange_money",
"destination_account": "+2250701234567",
"amount": 75000,
"description": "Salaire"
}
],
"metadata": {
"payroll_month": "2026-01"
}
}Response:
{
"success": true,
"data": {
"batch": {
"id": "uuid",
"reference": "BATCH-260209-ABC123",
"name": "Salaires Janvier 2026",
"status": "processing",
"total_payouts": 2,
"total_amount": 125000,
"total_fees": 1875
}
}
}
GET
/api/v1/merchant/payouts/batch/{uuid}
Récupère le statut et les statistiques d'un batch payout.
💡 Exemples d'Intégration
PHP - Payout Simple
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'Authorization' => 'Bearer ' . $apiKey,
'Content-Type' => 'application/json',
])->post('https://pay.genius.ci/api/v1/merchant/payouts', [
'wallet_id' => 'wallet-uuid-123',
'recipient' => [
'name' => 'Jean Kouassi',
'phone' => '+2250709876543',
],
'destination' => [
'type' => 'mobile_money',
'provider' => 'wave',
'account' => '+2250709876543',
],
'amount' => 50000,
'currency' => 'XOF',
'description' => 'Salaire',
]);
if ($response->successful()) {
$payout = $response->json('data.payout');
echo "Payout créé: " . $payout['reference'];
}JavaScript - Batch Payout
const createBatchPayout = async (walletId, payouts) => {
const response = await fetch(
'https://pay.genius.ci/api/v1/merchant/payouts/batch',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
wallet_id: walletId,
name: 'Salaires Janvier 2026',
payouts: payouts,
}),
}
);
const data = await response.json();
return data.data.batch;
};Python - Suivi de Payout
import requests
def get_payout_status(reference):
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json',
}
response = requests.get(
f'https://pay.genius.ci/api/v1/merchant/payouts/{reference}',
headers=headers
)
return response.json()['data']['payout']
# Utilisation
payout = get_payout_status('PYT-260209-XYZ789')
print(f"Statut: {payout['status']}")
print(f"Montant: {payout['amount']} {payout['currency']}")🔔 Webhooks
Les webhooks vous notifient des changements de statut des payouts.
Événements Disponibles
payout.created
Un payout a été créé
payout.completed
Un payout a été complété avec succès
payout.failed
Un payout a échoué
batch.completed
Un batch payout a été complété
Payload Webhook
{
"event": "payout.completed",
"timestamp": "2026-02-09T15:30:00Z",
"data": {
"payout": {
"id": "uuid",
"reference": "PYT-260209-XYZ789",
"status": "completed",
"amount": 50000,
"currency": "XOF",
"recipient": {
"name": "Jean Kouassi",
"phone": "+2250709876543"
},
"completed_at": "2026-02-09T15:30:00Z"
}
}
}⚠️ Gestion des Erreurs
400 - Bad Request
Les paramètres de la requête sont invalides.
401 - Unauthorized
Le Bearer Token est manquant ou invalide.
403 - Forbidden
Vous n'avez pas les permissions pour cette action.
422 - Unprocessable Entity
Validation échouée (ex: solde insuffisant, limite dépassée).
429 - Too Many Requests
Limite de requêtes dépassée. Attendez avant de réessayer.
500 - Server Error
Erreur serveur. Réessayez plus tard.