Initiate Payout

Initiate a payout to a third party (contractor, supplier, etc).

Use Cases:

Pay contractors/freelancers for services

Pay suppliers for goods

Marketplace disbursements to sellers

Refunds or reimbursements to third parties

Recipient details for bank transfer:

recipient_name (required) - Full name of recipient

bank_account_number (required) - Bank account number

bank_name (required) - Name of the bank

account_holder_name (required) - Account holder name

bank_routing_number (optional) - Routing/sort code

recipient_email (optional) - Recipient email

recipient_phone (optional) - Recipient phone

Recipient details for mobile money:

recipient_name (required) - Full name of recipient

mobile_number (required) - Mobile number

network_provider (required) - Network: mtn_momo, mpesa, orange_money, vodafone_cash

recipient_email (optional) - Recipient email

recipient_phone (optional) - Recipient phone

Creates entries in BOTH ledgers:

merchant_transactions: Customer-facing ledger (merchants can track business payments)

merchant_wallet_transactions: Internal audit trail

Fee: 1.5% of payout amount (configurable per currency/type in future)

curl --location --request POST '/api/v1/merchants/payouts' \ --header 'x-api-key: <api-key>' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 800, "currency_code": "NGN", "notes": "Q4 contractor payment", "payout_reason": "Invoice #12345 - Web development services", "payout_type": "bank_transfer", "recipient_details": { "account_holder_name": "John Doe", "bank_account_number": "1234567890", "bank_name": "Example Bank", "recipient_email": "john@example.com", "recipient_name": "John Doe" } }'

Request

Responses