Payouts Overview

The Payouts API enables you to send money directly to beneficiaries through various payment methods including bank transfers, mobile money, and digital wallets. This is ideal for disbursements, refunds, rewards, and incentive payments.

Overview

Payouts allow you to:

• Send money globally - Transfer funds to beneficiaries in multiple countries and currencies
• Multiple payment rails - Bank transfers, mobile money, digital wallets, and more
• Real-time tracking - Monitor payout status from creation to completion
• Beneficiary management - Save and reuse beneficiary information for recurring payments

Quick Start

1. Create Beneficiaries - Save beneficiary information for reuse
2. Create a Payout - Initiate a money transfer
3. Track Status - Monitor payout progress

Available Endpoints

Payout Lifecycle

Payouts progress through the following statuses:

created → queued → processing → settling → completed
                       ↓            ↓
                    failed      action_required

Status Definitions

Fees and Charges

Payout fees vary by provider and are calculated based on:

• Fixed fees - A flat amount per transaction
• Percentage fees - A percentage of the payout amount
• Combined fees - Both fixed and percentage components

Fee information is included in the payout response after creation.

Currency Support

Each payout provider supports specific currencies. The supported currencies are returned in the provider details. Common supported currencies include:

• USD, EUR, GBP (Major currencies)
• INR, NGN, KES, GHS (Regional currencies)
• And many more based on provider coverage

Best Practices

Before Creating Payouts

1. Verify provider availability - Check that a suitable provider exists for the destination country/currency
2. Validate beneficiary info - Ensure all required identifiers are provided
3. Check wallet balance - Confirm sufficient funds including fees

During Processing

1. Use unique reference IDs - Prevent duplicate payouts with idempotent references
2. Handle async processing - Implement polling or webhooks for status updates
3. Store payout IDs - Save returned IDs for tracking and reconciliation

Error Handling

1. Check failure reasons - Failed payouts include detailed error information
2. Implement retries - Some failures are temporary and can be retried
3. Monitor completion rates - Track success metrics for each provider/corridor

Security Considerations

• Always use HTTPS for all API communications
• Validate beneficiary data before creating payouts
• Implement fraud checks for unusual payout patterns
• Use webhooks securely with signature verification

Next Steps

• Create a Beneficiary - Save beneficiary information
• Create Your First Payout - Send money to a beneficiary