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 Payonify before going live. Your merchant account must be approved by the payment processor for B2C (Business-to-Customer) services. Contact support to request access.

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&limit=10" \
  -u "pk_test_abc123...:sk_test_xyz789..."

See the Filtering guide for all available filter options.

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.

Last modified on March 14, 2026

Slide-In Webhooks

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

How Payouts Work

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.

Event

Description

payout.succeeded

Payout completed successfully, funds delivered to recipient

payout.failed

Payout failed to process