Merchant Payout (Send Money)

Send money to customers via mobile money

Post https://dashboard.mbiyo.africa/api/v1/merchant/payout

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

Headers

Authorization* string

Pass your merchant API key as a bearer token in the request header to authorize this call

Content-Type* string

application/json

Request Body Parameters

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 (optional, max 255 characters)

callback_url* string

URL where payout status updates will be sent (webhook URL) - Required

Note: If provided, this URL will be used instead of the default webhook URL configured in your dashboard settings.

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)

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"
    }
  }'

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"
    },
  }
}

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.


{
  "event": "payout.status.updated",
  "transaction_id": "TXN-PAYOUT-9876543210",
  "order_id": "PAYOUT-12345",
  "status": "successful",
  "amount": 5000,
  "fee": 50,
  "currency": "XOF",
  "payment_method": "mobile_money",
  "recipient": {
    "phone_number": "22670123456",
    "network": "orange"
  },
  "updated_at": "2025-12-16T14:25:00Z"
}

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.