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

Header	Type	Required	Description
Authorization	string	✅	Bearer token with your merchant API key
Content-Type	string	✅	`application/json`

Request Body Parameters

Parameter	Type	Required	Description
amount	number	✅	The amount to send to the recipient (minimum: 0.01)
currency	string	✅	3-letter ISO currency code (e.g., XOF, GHS, KES)
payment_method	string	✅	Payment method to use. Currently only supports: `mobile_money`
order_id	string		Your internal order/transaction reference ID (max 255 characters)
callback_url	string	✅	URL where payout status updates will be sent (webhook URL) - Required. If provided, overrides the default webhook URL in your dashboard.
metadata	object	✅	Recipient information (required for mobile_money)
metadata.network	string	✅	Mobile money network (e.g., mtn, orange, moov, airtel, mpesa)
metadata.phone_number	string	✅	Recipient phone number for mobile money
metadata.country_code	string	✅	2-letter ISO country code (e.g., BF, GH, KE, CI)
metadata.beneficiary	string	✅	Full name of the beneficiary

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": "Payout initiated successfully",
  "data": {
    "transaction_id": "TXN-PAYOUT-9876543210",
    "amount": 5000,
    "fee": 50,
    "charged_amount": 5050,
    "currency": "XOF",
    "order_id": "PAYOUT-12345",
    "status": "pending",
    "payment_method": "mobile_money",
    "created_at": "2025-12-16T14:20:00Z",
    "metadata": {
      "phone_number": "22670123456",
      "network": "orange",
      "country_code": "BF",
      "beneficiary": "John Doe"
    }
  }
}

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)

{
  "status": "error",
  "message": "Insufficient balance for payout",
  "data": {
    "required_amount": 5050,
    "available_balance": 2000,
    "currency": "XOF"
  }
}

Payout Status

Status	Description
pending	Payout has been initiated and is being processed
successful	Payout has been completed successfully and money has been sent to recipient
failed	Payout has failed. The amount will be refunded to your balance
cancelled	Payout has been cancelled

Webhook Notification

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

Callback URL Priority: If you provide a callback_url in your request, notifications will be sent to this URL. If no callback_url is provided, we will use the default webhook URL configured in your merchant dashboard settings.

{
  "transaction_id": "CO-PAYOUT-9876543210",
  "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"
  }
}

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

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