Initiate money transfers to beneficiaries via bank transfers, mobile money, and other payment methods

Create Payout API

Create a new payout to transfer money to a beneficiary. The payout amount is immediately deducted from your wallet, and the funds are sent through the appropriate payment provider.

Endpoint

POST /api/v1/payouts

Authentication: API Key + Secret required

Request Headers

X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here
Content-Type: application/json
Idempotency-Key: pay_xyz789_1705689660

Header	Required	Description
`X-API-Key`	Yes	Your API key
`X-API-Secret`	Yes	Your API secret
`Content-Type`	Yes	Must be `application/json`
`Idempotency-Key`	Yes	Unique key (8-256 chars) to prevent duplicate payouts. Learn more →

Critical: The Idempotency-Key header is required for all payout creation requests. This prevents duplicate payouts from network retries or application crashes. Keys are valid for 24 hours.

Request Body

Required Fields

{
  "reference_id": "PAY_2024_001",
  "wallet_id": 1234,
  "amount": 100.00,
  "currency": "USD",
  "beneficiary_email": "john.doe@example.com",
  "beneficiary_first_name": "John",
  "beneficiary_last_name": "Doe"
}

Complete Request Schema

{
  "reference_id": "PAY_2024_001",
  "wallet_id": 1234,
  "amount": 100.00,
  "currency": "USD",
  "beneficiary_id": "ben_abc123xyz",
  "beneficiary_email": "john.doe@example.com",
  "beneficiary_first_name": "John",
  "beneficiary_last_name": "Doe",
  "beneficiary_country": "US",
  "beneficiary_phone": "+1234567890",
  "beneficiary_identifiers": {
    "account_number": "123456789",
    "routing_number": "987654321"
  },
  "description": "Q1 2024 Bonus Payment",
  "metadata": {
    "employee_id": "EMP001",
    "department": "Engineering"
  },
  "notify_beneficiary": true
}

Field Descriptions

Field	Type	Required	Description
`reference_id`	string	Yes	Unique client reference for idempotency
`wallet_id`	number	Yes	Source wallet ID for the payout
`amount`	number	Yes	Payout amount (must be > 0)
`currency`	string	Yes	Currency code (ISO 4217)
`beneficiary_id`	string	No	ID of saved beneficiary (alternative to inline info)
`beneficiary_email`	string	Yes*	Beneficiary email (*required if no beneficiary_id)
`beneficiary_first_name`	string	Yes*	First name (*required if no beneficiary_id)
`beneficiary_last_name`	string	Yes*	Last name (*required if no beneficiary_id)
`beneficiary_country`	string	No	Country code (ISO 3166-1 alpha-2)
`beneficiary_phone`	string	No	Phone number with country code
`beneficiary_identifiers`	object	No	Payment identifiers (bank account, mobile number, etc.)
`description`	string	No	Internal description for the payout
`metadata`	object	No	Custom key-value pairs for your reference
`notify_beneficiary`	boolean	No	Send email notification to beneficiary (default: false)

Validation Rules

reference_id: Must be unique across all your payouts (idempotency key)
amount: Must be positive and within provider min/max limits
currency: Must be supported by an available payout provider
wallet_id: Must belong to your client and have sufficient balance (including fees)
beneficiary_email: Must be valid email format when provided

Response

Success Response

Status Code: 201 Created

{
  "id": "pyt_xyz789abc",
  "reference_id": "PAY_2024_001",
  "status": "created",
  "amount": 100.00,
  "currency": "USD",
  "fees": 1.50,
  "total_amount": 101.50,
  "beneficiary": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "phone": "+1234567890"
  },
  "description": "Q1 2024 Bonus Payment",
  "created_at": "2024-01-15T10:30:00Z",
  "queued_at": null,
  "submitted_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancelled_at": null
}

Response Fields

Field	Type	Description
`id`	string	Unique payout identifier (use for tracking)
`reference_id`	string	Your client reference
`status`	string	Current payout status
`amount`	number	Payout amount to beneficiary
`currency`	string	Currency code
`fees`	number	Fees charged for this payout
`total_amount`	number	Total deducted from wallet (amount + fees)
`beneficiary`	object	Beneficiary information
`failure_code`	string	Error code if failed (nullable)
`failure_reason`	string	Error description if failed (nullable)
`description`	string	Payout description (nullable)
`created_at`	string	Creation timestamp (ISO 8601)
`queued_at`	string	When queued for processing (nullable)
`submitted_at`	string	When submitted to provider (nullable)
`completed_at`	string	When completed successfully (nullable)
`failed_at`	string	When failed (nullable)
`cancelled_at`	string	When cancelled (nullable)

Payout Statuses

Status	Description	Wallet Impact
`created`	Payout created and queued	Deducted
`queued`	In queue for processing	Deducted
`processing`	Being processed by provider	Deducted
`settling`	Funds settling to beneficiary	Deducted
`action_required`	Needs additional action	Deducted
`completed`	Successfully delivered	Deducted
`failed`	Processing failed	Refunded
`cancelled`	Cancelled by client	Refunded
`expired`	Expired before completion	Refunded

Error Responses

400 Bad Request - Validation Error

{
  "error": "ValidationException",
  "message": "reference_id is required"
}

400 Bad Request - Invalid Amount

{
  "error": "ValidationException",
  "message": "amount must be greater than 0"
}

400 Bad Request - Insufficient Funds

{
  "error": "InternalServerError",
  "message": "insufficient wallet balance"
}

400 Bad Request - Duplicate Reference

{
  "error": "InternalServerError",
  "message": "duplicate reference_id"
}

401 Unauthorized

{
  "error": "UnauthorizedAccess",
  "message": "Authentication required"
}

500 Internal Server Error

{
  "error": "InternalServerError",
  "message": "Failed to create payout"
}

Examples

Basic Payout with Inline Beneficiary

# IMPORTANT: Always include Idempotency-Key header
curl -X POST "{{host}}/api/v1/payouts" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay_2024_001_$(date +%s)" \
  -d '{
    "reference_id": "PAY_2024_001",
    "wallet_id": 1234,
    "amount": 100.00,
    "currency": "USD",
    "beneficiary_email": "john.doe@example.com",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_country": "US",
    "beneficiary_identifiers": {
      "account_number": "123456789",
      "routing_number": "987654321"
    },
    "description": "Bonus Payment",
    "notify_beneficiary": true
  }'

Payout with Saved Beneficiary

curl -X POST "{{host}}/api/v1/payouts" \
  -H "X-API-Key: sk_live_abc123def456" \
      -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "PAY_2024_002",
    "wallet_id": 1234,
    "amount": 50.00,
    "currency": "USD",
    "beneficiary_id": "ben_abc123xyz",
    "description": "Recurring payment"
  }'

Mobile Money Payout

curl -X POST "{{host}}/api/v1/payouts" \
  -H "X-API-Key: sk_live_abc123def456" \
      -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "MM_2024_001",
    "wallet_id": 5678,
    "amount": 1000.00,
    "currency": "KES",
    "beneficiary_email": "jane@example.com",
    "beneficiary_first_name": "Jane",
    "beneficiary_last_name": "Wanjiku",
    "beneficiary_country": "KE",
    "beneficiary_phone": "+254712345678",
    "beneficiary_identifiers": {
      "mobile_number": "+254712345678",
      "provider": "mpesa"
    },
    "notify_beneficiary": true
  }'

Error Handling Example

Idempotency

The reference_id field serves as an idempotency key. If you submit a payout with a reference_id that already exists:

The request will fail with a duplicate reference error
The original payout is not modified

This prevents accidental duplicate payouts due to network retries or application errors.

Best Practice

Generate unique reference IDs using a combination of:

Timestamp or sequential counter
Random component
Business context (e.g., invoice number)

Wallet Deduction

The payout amount plus fees are deducted immediately when the payout is created:

Validation - Check wallet balance covers amount + fees
Deduction - Immediately deduct total amount from wallet
Processing - Payout enters processing queue
Outcome - If failed/cancelled, amount is refunded to wallet

Important: Ensure your wallet has sufficient balance for both the payout amount and any applicable fees before creating a payout.

Best Practices

Before Creating Payouts

Check provider availability - Verify a provider supports the target currency/country
Calculate total cost - Account for payout amount + fees
Validate wallet balance - Ensure sufficient funds before submission
Verify beneficiary details - Validate bank/mobile details are correct

During Processing

Store payout IDs - Save the returned id for tracking
Monitor status - Poll the Get Payout API for updates
Handle failures gracefully - Check failure_code and failure_reason for details

Production Recommendations

Use webhooks - Set up webhooks for real-time status updates (when available)
Implement reconciliation - Regularly compare your records with API data
Set up alerts - Monitor for unusual failure rates
Test thoroughly - Use sandbox environment before production

List Payouts - View all your payouts
Get Payout - Check payout status and details
Cancel Payout - Cancel a pending payout

Create Payout API

On this page