Payouts

Single Payouts

Send individual payouts to recipients

Single payouts allow you to send funds to one recipient at a time. This is ideal for one-off transactions, refunds, or when you need to process payouts individually.

When to Use Single Payouts

  • One-time payments to individual recipients
  • Refunds or customer disbursements
  • Small-scale operations
  • Testing and development

Creating a Single Payout

To create a single payout, you’ll need:

  1. merchantId: Your merchant identifier
  2. merchantReference: Your internal reference for tracking and idempotency
  3. destinationValue: Object with:
    • minorAmount: Amount in minor units (integer, e.g., 10000 = 100.00 NGN). See Amount Format below.
    • currency: Must be a supported payout currency (NGN, XOF, XAF, GHS, KES, ZAR, AED, EGP, SAR, USDT, USDC)
  4. paymentMethodId: "banktransfer", "mobilemoney", or "crypto"
  5. paymentLocation: 3-letter ISO country code (e.g., NGA, KEN, EGY)
  6. Recipient Details:
    • For bank accounts: type: "bank_account", accountNumber, bankCode, accountHolderName, country, optional phoneNumber
    • For mobile wallets: type: "mobile_money", phoneNumber, country, operator, optional name
    • For crypto wallets: type: "crypto_wallet", address, network (ERC20 or TRC20), optional memo
  7. sender (optional): Sender details with KYC fields (required for some destinations)
  8. attributes (optional): Additional payout attributes as key-value pairs

Amount Format

Amounts are specified in minor units (the smallest currency unit, like cents). The minorAmount field is an integer.

Examples:

  • 10000 minorAmount = 100.00 NGN (Nigerian Naira)
  • 5000 minorAmount = 50.00 KES (Kenyan Shillings)
  • 10000 minorAmount = 100.00 EGP (Egyptian Pounds)
  • 1000000 minorAmount = 1.000000 USDT

Important: Fiat currencies use 2 decimal places (multiply by 100). USDT/USDC use 6 decimal places (multiply by 1,000,000).

Request Examples

Bank Account Payout

1{
2  "merchantId": "your-merchant-id",
3  "merchantReference": "PAYOUT-2024-001",
4  "destinationValue": {
5    "minorAmount": 1000000,
6    "currency": "NGN"
7  },
8  "paymentMethodId": "banktransfer",
9  "paymentLocation": "NGA",
10  "recipient": {
11    "type": "bank_account",
12    "accountNumber": "0123456789",
13    "bankCode": "044",
14    "accountHolderName": "John Doe",
15    "country": "NGA"
16  },
17  "attributes": {}
18}

Note: minorAmount: 1000000 = 10,000.00 NGN (multiply by 100 to convert from major to minor units).

Mobile Wallet Payout

1{
2  "merchantId": "your-merchant-id",
3  "merchantReference": "PAYOUT-2024-002",
4  "destinationValue": {
5    "minorAmount": 500000,
6    "currency": "KES"
7  },
8  "paymentMethodId": "mobilemoney",
9  "paymentLocation": "KEN",
10  "recipient": {
11    "type": "mobile_money",
12    "phoneNumber": "254712345678",
13    "country": "KEN",
14    "operator": "mpesa",
15    "name": "Jane Smith"
16  },
17  "attributes": {}
18}

Note: minorAmount: 500000 = 5,000.00 KES.

Crypto Wallet Payout

1{
2  "merchantId": "your-merchant-id",
3  "merchantReference": "PAYOUT-2024-003",
4  "destinationValue": {
5    "minorAmount": 1250000,
6    "currency": "USDT"
7  },
8  "paymentMethodId": "crypto",
9  "paymentLocation": "USA",
10  "recipient": {
11    "type": "crypto_wallet",
12    "address": "0x1111222233334444555566667777888899990000",
13    "network": "ERC20"
14  },
15  "attributes": {}
16}

Note: minorAmount: 1250000 = 1.250000 USDT.

Response Structure

Successful Response

A successful payout response (HTTP 201) includes:

1{
2  "status": "PENDING",
3  "transactionId": "payout_9f8b7c6d5e4a3b2c1d0e",
4  "message": "Payout transaction initiated successfully",
5  "merchantReference": "PAYOUT-2024-001",
6  "paymentMethodId": "banktransfer",
7  "processorReference": "PROC-123456"
8}

Response fields:

  • status: Current status (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED)
  • transactionId: Unique transaction identifier
  • message: Status message
  • merchantReference: Your provided merchant reference (if supplied)
  • sessionId: Session ID (if applicable)
  • identifiers: Additional identifiers related to the transaction
  • paymentAttributes: Payment-specific attributes and metadata
  • paymentMethodId: Payment method identifier
  • processorName: Payment processor name
  • processorReference: Payment processor reference
  • financialTransactionReference: Financial transaction reference from the processor
  • currentAttemptId: Current attempt identifier
  • batchPayoutId: Batch payout identifier, if part of a bulk payout

Payout Statuses

  • PENDING: Payout has been created and is awaiting processing
  • PROCESSING: Payout is currently being processed
  • COMPLETED: Payout has been successfully completed
  • FAILED: Payout has failed (check message, identifiers, and paymentAttributes for details)
  • CANCELLED: Payout was cancelled

Error Handling

The API returns standard HTTP status codes:

  • 201: Payout transaction initiated successfully
  • 400: Bad Request - Invalid payout parameters or insufficient balance
  • 401: Unauthorized - Invalid or missing authentication
  • 422: Request validation failed
  • 500: Internal server error

Error Response Structure

Error responses (HTTP 400, 401, 422) include an error object with code and message fields:

1{
2  "error": {
3    "code": "INSUFFICIENT_BALANCE",
4    "message": "Insufficient balance in payout source account"
5  }
6}

Example error responses:

Insufficient Balance (400):

1{
2  "error": {
3    "code": "INSUFFICIENT_BALANCE",
4    "message": "Insufficient balance in payout source account"
5  }
6}

Invalid Parameters (400):

1{
2  "error": {
3    "code": "INVALID_REQUEST",
4    "message": "Invalid recipient details provided"
5  }
6}

Unauthorized (401):

1{
2  "error": {
3    "code": "UNAUTHORIZED",
4    "message": "Invalid or expired access token"
5  }
6}

Common error codes:

  • INSUFFICIENT_BALANCE: Not enough funds in the payout currency
  • INVALID_REQUEST: Invalid request parameters (e.g., invalid currency, missing required fields)
  • INVALID_RECIPIENT: Invalid recipient details (e.g., invalid account number, phone number)
  • UNAUTHORIZED: Invalid or expired access token
  • RATE_LIMIT_EXCEEDED: Too many requests (see Rate Limiting)

Example Use Cases

  • Refund Processing: Send refunds to customers who returned products
  • Vendor Payments: Pay individual suppliers or service providers
  • Customer Rewards: Distribute loyalty rewards or cashback
  • One-off Disbursements: Send individual payments as needed

Idempotency

The merchantReference field enables idempotency. If you send a payout request with a merchantReference that was used in a previous successful request, the API will return the original payout instead of creating a duplicate. This prevents accidental duplicate payouts if a request is retried.

Best practice: Use unique, meaningful references for each payout (e.g., PAYOUT-2024-001, REFUND-ORDER-12345).

Best Practices

  • Always verify recipient details before initiating payouts
  • Use unique, meaningful references for idempotency and easy tracking
  • Monitor payout status through the history endpoints or webhooks
  • Ensure sufficient balance before initiating payouts
  • Handle failed payouts by checking status, message, and any returned identifiers or paymentAttributes
  • Store payout IDs and references for reconciliation and tracking
  • Implement retry logic with exponential backoff for transient failures

For detailed API documentation, see the Payouts API Reference.