Guides

Payouts

Payouts allow you to disburse funds from your Payonify account to recipients via mobile money. The Payouts API supports multiple destination types, with EcoCash mobile money currently available.

Approval Required

The Payouts API requires prior approval from the payment processor. Your merchant account must be approved for B2C (Business-to-Customer) services before you can use payouts. Contact sales for more information.

Payout Methods

Destination	Provider	Status
EcoCash B2C	Mobile Money (Econet)	Available
OneMoney B2C	Mobile Money (NetOne)	Coming Soon

How Payouts Work

sequenceDiagram participant Your Server participant Payonify participant Mobile Money Your Server->>Payonify: POST /v1/payouts/validate Payonify->>Mobile Money: Verify recipient Mobile Money-->>Payonify: Recipient details Payonify-->>Your Server: {valid: true, recipient: {...}} Your Server->>Payonify: POST /v1/payouts Payonify-->>Your Server: {status: "pending"} Note over Payonify,Mobile Money: Async processing Payonify->>Mobile Money: Send funds Mobile Money-->>Payonify: Transaction result Payonify->>Your Server: Webhook: payout.succeeded

Payout Flow

Validate the recipient's mobile money account (recommended)
Create the payout with amount, currency, and destination
Receive a webhook notification when the payout completes or fails

Step-by-Step Guide

Validate the Recipient

Before sending a payout, validate the recipient's account to ensure it exists and can receive funds:

Code
curl https://api.payonify.com/v1/payouts/validate \ -u "pk_test_abc123...:sk_test_xyz789..." \ -H "Content-Type: application/json" \ -d '{ "destination": { "mobile_money": { "ecocash": { "mobile_number": "771111111" } } } }'

Response:
```
Response
{
  "valid": true,
  "recipient": {
    "first_name": "John",
    "last_name": "Doe",
    "account_status": "active",
    "mobile_number": "771111111"
  }
}
```
The account_status will be active or inactive.

Create the Payout

Once validated, create the payout:

Code

curl https://api.payonify.com/v1/payouts \
-u "pk_test_abc123...:sk_test_xyz789..." \
-H "Content-Type: application/json" \
-d '{
  "amount": 5000,
  "currency": "usd",
  "description": "Monthly salary payment",
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  },
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}'

Response (201 Created):


Response
{
  "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
  "object": "payout",
  "amount": {
    "value": 5000,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1763144144,
  "status": "pending",
  "description": "Monthly salary payment",
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  },
  "destination_details": {
    "type": "mobile_money",
    "mobile_money": {
      "brand": "ecocash",
      "reference": null,
      "recipient_number": "771111111",
      "recipient_name": null,
      "channel_number": null,
      "network": "Econet"
    }
  },
  "failure_code": null,
  "failure_message": null
}

The payout is created with status: "pending" and will be processed asynchronously.

Handle the Webhook

When the payout completes, Payonify sends a webhook to your configured endpoint:


payout.succeeded webhook
{
  "id": "evt_abc123xyz",
  "type": "payout.succeeded",
  "object": "event",
  "created": 1763144160,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
      "object": "payout",
      "status": "paid",
      "amount": {
        "value": 5000,
        "currency": "usd"
      },
      "destination_details": {
        "type": "mobile_money",
        "mobile_money": {
          "brand": "ecocash",
          "reference": "CI270218.0450.T0691170",
          "recipient_number": "771111111",
          "recipient_name": "John Doe",
          "channel_number": "789643586",
          "network": "Econet"
        }
      }
    }
  }
}

See the Webhooks guide for details on verifying webhook signatures.

Validate First

Always validate recipients before creating payouts in production. This helps catch invalid numbers early and provides a better experience for your users.

Checking Payout Status

You can check the status of a payout at any time by retrieving it:

Code
curl https://api.payonify.com/v1/payouts/po_a7eryb3kdb6ljkzqe5vg3jbf \
  -u "pk_test_abc123...:sk_test_xyz789..."

Listing Payouts

List payouts with optional filters:

Code
curl "https://api.payonify.com/v1/payouts?status=paid&currency=usd&first=10" \
  -u "pk_test_abc123...:sk_test_xyz789..."

See the Filtering guide for all available filter options.

Reversing a payout

If a payout was sent in error, you can reverse a settled one by its ID with the Reversals API:

Code
curl https://api.payonify.com/v1/reversals \
  -u pk_live_...:sk_live_... \
  -H "Content-Type: application/json" \
  -d '{
    "payout": "po_a7eryb3kdb6ljkzqe5vg3jbf",
    "reason": "Sent in error"
  }'

The reversal is processed in the background - you get a processing response straight away, then a reversal.succeeded (or reversal.failed) webhook once it's done. A payout can be reversed once, and always for the full amount.

Webhook Events

Event	Description
`payout.succeeded`	Payout completed successfully, funds delivered to recipient
`payout.failed`	Payout failed to process

For details on setting up and verifying webhooks, see the Webhooks guide.

Test Numbers

Use these test numbers when testing payouts in test mode. Numbers use the 772 prefix.

Mobile Number	Behavior
`772111111`	Success - payout completed (recipient: John Doe)
`772111112`	Success - payout completed (recipient: Jane Smith)
`772111113`	Failed - insufficient balance
`772111114`	Failed - system timeout
`772111115`	Failed - recipient number does not exist
`772111116`	Failed - unregistered recipient

Last modified on September 10, 2026

Slide-In Relay