Merchant Payout (Send Money)

Send money to customers via mobile money.

KYC Required: Your business account must have an approved KYC status to perform payout transactions in live mode.

Endpoint

POST /api/v1/merchant/payout

Headers

Request Body Parameters

Amount rounding: For transactions in certain countries (BF, BJ, CI, CM, GN, ML, TG), the amount may be automatically rounded to the nearest multiple of 5 to meet local processing requirements. The response always reflects the actual processed amount.

Example Request

curl -X POST "https://dashboard.mbiyo.africa/api/v1/merchant/payout" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "mobile_money",
    "order_id": "PAYOUT-12345",
    "callback_url": "https://yourdomain.com/webhook/payout-status",
    "metadata": {
      "network": "orange",
      "phone_number": "+22670123456",
      "country_code": "BF",
      "beneficiary": "John Doe"
    }
  }'

Success Response (200 OK)

{
  "status": "success",
  "message": "Transaction initiated successfully",
  "data": {
    "transaction_id": "CO-66F3A1B2C4D5E1727258400A1B2",
    "amount": 5000,
    "fee": 50,
    "currency": "XOF",
    "order_id": "PAYOUT-12345",
    "type": "cashout",
    "status": "pending",
    "charged_amount": 5050,
    "created_at": "2025-12-16T14:20:00Z"
  }
}

Amounts: for a payout, charged_amount = amount + fee: this is what is debited from your balance when the payout is created. The recipient receives amount.

Error Response — KYC Not Approved (403 Forbidden)

{
  "status": "error",
  "message": "KYC approval required for live payouts",
  "data": null
}

Error Response — Insufficient Balance (400 Bad Request)

Your balance in the payout currency must cover amount + fee.

{
  "status": "error",
  "message": "Insufficient balance for payout",
  "data": null
}

Other Error Responses

Always check the top-level status field, not only the HTTP code.

Payout Status

Webhook Notification

When the payout status changes, we will send a POST request to your callback_url with the following payload:

Callback URL: callback_url is required for payouts, and notifications for this payout are sent to it.

{
  "transaction_id": "CO-66F3A1B2C4D5E1727258400A1B2",
  "amount": 5000,
  "fee": 50,
  "currency": "XOF",
  "order_id": "PAYOUT-12345",
  "status": "successful",
  "charged_amount": 5050,
  "type": "cashout",
  "created_at": "2025-12-16T14:20:00Z",
  "updated_at": "2025-12-16T14:25:00Z",
  "metadata": {
    "country_code": "BF",
    "phone_number": "22670123456",
    "network": "orange",
    "beneficiary": "John Doe"
  }
}

metadata echoes the payout details and may contain additional fields; ignore the ones you do not use.

Important: Always verify the payout status by calling the transaction status endpoint to confirm the final state before marking it as completed in your system.

Fee Structure

Payout fees are automatically deducted from your merchant wallet balance. The total charged amount includes:

• Payout amount (sent to recipient)
• Service fee (varies by country and network)

Note: Ensure your wallet has sufficient balance to cover both the payout amount and the service fee before initiating a payout.

Best Practices

1. Verify KYC Status: Ensure your business account KYC is approved before implementing payout functionality.
2. Check Balance: Always verify your wallet balance before initiating payouts.
3. Use Webhooks: Implement webhook handlers to receive real-time payout status updates.
4. Validate Recipients: Verify recipient phone numbers and network information before initiating payouts.
5. Handle Failures: Implement proper error handling for failed payouts.
6. Keep Records: Store transaction_id and order_id for reconciliation purposes.

Supported Networks by Country

Transaction Limits

Each country and currency has minimum and maximum transaction amount limits enforced at the network level. Transactions exceeding these limits will be rejected with a 400 error.