Payouts

A Payout object represents a disbursement of funds to a recipient. Payouts allow you to send money to mobile money wallets and other supported destinations. Currently, EcoCash mobile money is available, with more coming soon.

Approval required: the Payouts API needs prior approval — your account must be approved for B2C services. Contact sales for more.

Validate a payout recipient

POST

https://api.payonify.com

/v1/payouts/validate

Validates a recipient's mobile money account before initiating a payout. This is a synchronous operation that queries the mobile money provider directly to verify the recipient's account status and retrieve their details.

It is recommended to validate recipients before creating payouts to avoid failed transactions.

Request Body Example


Code
{
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}

Validate a payout recipient › Request Body

Parameters for validating a payout recipient before initiating a payout. This is a synchronous operation that queries the mobile money provider to verify the recipient's account.

PayoutValidateRequest

PayoutDestination · required

The destination for the payout funds. The destination is structured to support multiple destination types. Currently, EcoCash mobile money is the available destination, with more options (e.g., OneMoney, bank transfer) coming soon.

Validate a payout recipient › Responses

Recipient validated successfully

The result of a payout recipient validation. Contains whether the recipient is valid and their account details if found.

PayoutValidateResponse

valid

boolean

Whether the recipient account is valid and can receive payouts.

object

Details about the validated recipient. Only present when valid is true.

List all payouts

GET

https://api.payonify.com

/v1/payouts

Returns a paginated list of payouts. The payouts are returned sorted by creation date, with the most recently created payouts appearing first.

Using pagination

By default, this endpoint returns 10 payouts per page. You can adjust this with the limit parameter and navigate through pages using the after cursor returned in the paging object.

Code
GET /v1/payouts?limit=5&after=cursor_xyz789

List all payouts › query Parameters

limit

integer · min: 1 · max: 100

Number of records to return per page. Use with cursor-based pagination.

Default: 10

first

integer · min: 1 · max: 100

Number of records to return for forward pagination. Use with after cursor.

after

string

Cursor for forward pagination. Returns records after this cursor.

last

integer · min: 1 · max: 100

Number of records to return for backward pagination. Use with before cursor.

before

string

Cursor for backward pagination. Returns records before this cursor.

status

string · enum

Filter payouts by status.

Enum values:

pending

paid

failed

currency

string · enum

Filter payouts by currency ISO code.

Enum values:

usd

zwg

start_date

string · date

Filter payouts created on or after this date. Use ISO 8601 format (YYYY-MM-DD).

end_date

string · date

Filter payouts created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all payouts › Responses

A list of payouts

PayoutList

object

string

Type of the returned object.

Payout[]

Array of payout objects.

object

Pagination metadata

GET/v1/payouts

curl https://api.payonify.com/v1/payouts \
  --header 'Authorization: Basic <credentials>'

Example Responses

{
  "object": "list",
  "data": [
    {
      "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
      "object": "payout",
      "amount": {
        "value": 5000,
        "currency": "usd"
      },
      "livemode": false,
      "created": 1746702317,
      "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": "772111111",
          "recipient_name": "John Doe",
          "channel_number": "789643586",
          "network": "Econet"
        }
      },
      "failure_code": null,
      "failure_message": null
    }
  ],
  "paging": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": null,
    "end_cursor": null,
    "page_size": 10
  }
}

json

application/json

Create a payout

POST

https://api.payonify.com

/v1/payouts

Creates a new payout to send funds to a recipient. The payout is processed asynchronously — the response returns immediately with a pending status while processing happens in the background.

You will receive a webhook notification (payout.succeeded or payout.failed) when the payout is completed.

Request Body Example


Code
{
  "amount": 5000,
  "currency": "usd",
  "description": "Monthly salary payment",
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  },
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}

Payout Status

A payout can have one of the following statuses:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Create a payout › Request Body

Parameters for creating a new payout. The payout will be processed asynchronously after creation.

PayoutCreateRequest

amount

integer · min: 100 · required

A positive integer representing the payout amount in the smallest currency unit (e.g. 100 cents = $1.00).

The minimum amount is 100 (e.g., $1.00).

currency

string · enum · required

A three-letter ISO currency code. Currently, only usd and zwg are supported.

Enum values:

usd

zwg

PayoutDestination · required

description

string · maxLength: 150

An optional description for the payout. This can be used for internal reference or record-keeping.

Maximum 150 characters.

object · maxProps: 5

A set of key-value pairs for storing additional information about the payout.

You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.

Create a payout › Responses

Payout created successfully

A payout represents a disbursement of funds to a recipient. Payouts are processed asynchronously — the initial response will have a `pending` status, and the final result will be delivered via webhook.

Payout

id

string

Unique identifier for the payout object. Payout IDs have the prefix po_.

object

string

A string representing the type of the object. Always "payout" for payout objects.

object

Contains the monetary value and currency information for the payout.

livemode

boolean

Has the value true if the object exists in live mode or false if in test mode.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

status

string · enum

The status of the payout.

Possible values:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Enum values:

pending

paid

failed

description

string

Description of the payout, if one was provided at creation time.

object

A set of key-value pairs attached to the payout.

object

Contains information about the payout destination. The structure depends on the destination type used.

failure_code

string

Error code for a failed payout. This field will be null if the payout has not failed.

failure_message

string

A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.

POST/v1/payouts

curl https://api.payonify.com/v1/payouts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <credentials>' \
  --data '{
  "amount": 5000,
  "currency": "usd",
  "description": "Monthly salary payment",
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  }
}'

Example Request Body

{
  "amount": 5000,
  "currency": "usd",
  "description": "Monthly salary payment",
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  }
}

json

application/json

Example Responses

{
  "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
  "object": "payout",
  "amount": {
    "value": 5000,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "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": "772111111",
      "recipient_name": "John Doe",
      "channel_number": "789643586",
      "network": "Econet"
    }
  },
  "failure_code": null,
  "failure_message": null
}

json

application/json

Retrieve a payout

GET

https://api.payonify.com

/v1/payouts/{id}

Retrieves the details of an existing payout. You can use this endpoint to check the status of a payout.

Payout details

The payout object contains detailed information about the payout, including:

The amount sent
The current status of the payout
Destination details (recipient info, references)
Failure information if applicable

Retrieve a payout › path Parameters

id

string · required

Unique identifier for the payout

Retrieve a payout › Responses

Payout details retrieved successfully

Payout

id

string

Unique identifier for the payout object. Payout IDs have the prefix po_.

object

string

A string representing the type of the object. Always "payout" for payout objects.

object

Contains the monetary value and currency information for the payout.

livemode

boolean

Has the value true if the object exists in live mode or false if in test mode.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

status

string · enum

The status of the payout.

Possible values:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Enum values:

pending

paid

failed

description

string

Description of the payout, if one was provided at creation time.

object

A set of key-value pairs attached to the payout.

object

Contains information about the payout destination. The structure depends on the destination type used.

failure_code

string

Error code for a failed payout. This field will be null if the payout has not failed.

failure_message

string

A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.

GET/v1/payouts/{id}

curl https://api.payonify.com/v1/payouts/:id \
  --header 'Authorization: Basic <credentials>'

Example Responses

{
  "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
  "object": "payout",
  "amount": {
    "value": 5000,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "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": "772111111",
      "recipient_name": "John Doe",
      "channel_number": "789643586",
      "network": "Econet"
    }
  },
  "failure_code": null,
  "failure_message": null
}

json

application/json

Checkout Sessions

Validate a payout recipient

POST

https://api.payonify.com

/v1/payouts/validate

It is recommended to validate recipients before creating payouts to avoid failed transactions.

Request Body Example


Code
{
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}

Validate a payout recipient › Request Body

Parameters for validating a payout recipient before initiating a payout. This is a synchronous operation that queries the mobile money provider to verify the recipient's account.

PayoutValidateRequest

PayoutDestination · required

Validate a payout recipient › Responses

Recipient validated successfully

The result of a payout recipient validation. Contains whether the recipient is valid and their account details if found.

PayoutValidateResponse

valid

boolean

Whether the recipient account is valid and can receive payouts.

object

Details about the validated recipient. Only present when valid is true.

List all payouts

GET

https://api.payonify.com

/v1/payouts

Returns a paginated list of payouts. The payouts are returned sorted by creation date, with the most recently created payouts appearing first.

Using pagination

By default, this endpoint returns 10 payouts per page. You can adjust this with the limit parameter and navigate through pages using the after cursor returned in the paging object.

Code
GET /v1/payouts?limit=5&after=cursor_xyz789

List all payouts › query Parameters

limit

integer · min: 1 · max: 100

Number of records to return per page. Use with cursor-based pagination.

Default: 10

first

integer · min: 1 · max: 100

Number of records to return for forward pagination. Use with after cursor.

after

string

Cursor for forward pagination. Returns records after this cursor.

last

integer · min: 1 · max: 100

Number of records to return for backward pagination. Use with before cursor.

before

string

Cursor for backward pagination. Returns records before this cursor.

status

string · enum

Filter payouts by status.

Enum values:

pending

paid

failed

currency

string · enum

Filter payouts by currency ISO code.

Enum values:

usd

zwg

start_date

string · date

Filter payouts created on or after this date. Use ISO 8601 format (YYYY-MM-DD).

end_date

string · date

Filter payouts created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all payouts › Responses

A list of payouts

PayoutList

object

string

Type of the returned object.

Payout[]

Array of payout objects.

object

Pagination metadata

Create a payout

POST

https://api.payonify.com

/v1/payouts

Creates a new payout to send funds to a recipient. The payout is processed asynchronously — the response returns immediately with a pending status while processing happens in the background.

You will receive a webhook notification (payout.succeeded or payout.failed) when the payout is completed.

Request Body Example


Code
{
  "amount": 5000,
  "currency": "usd",
  "description": "Monthly salary payment",
  "metadata": {
    "employee_id": "12345",
    "payment_type": "salary"
  },
  "destination": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}

Payout Status

A payout can have one of the following statuses:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Create a payout › Request Body

Parameters for creating a new payout. The payout will be processed asynchronously after creation.

PayoutCreateRequest

amount

integer · min: 100 · required

A positive integer representing the payout amount in the smallest currency unit (e.g. 100 cents = $1.00).

The minimum amount is 100 (e.g., $1.00).

currency

string · enum · required

A three-letter ISO currency code. Currently, only usd and zwg are supported.

Enum values:

usd

zwg

PayoutDestination · required

description

string · maxLength: 150

An optional description for the payout. This can be used for internal reference or record-keeping.

Maximum 150 characters.

object · maxProps: 5

A set of key-value pairs for storing additional information about the payout.

You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.

Create a payout › Responses

Payout created successfully

Payout

id

string

Unique identifier for the payout object. Payout IDs have the prefix po_.

object

string

A string representing the type of the object. Always "payout" for payout objects.

object

Contains the monetary value and currency information for the payout.

livemode

boolean

Has the value true if the object exists in live mode or false if in test mode.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

status

string · enum

The status of the payout.

Possible values:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Enum values:

pending

paid

failed

description

string

Description of the payout, if one was provided at creation time.

object

A set of key-value pairs attached to the payout.

object

Contains information about the payout destination. The structure depends on the destination type used.

failure_code

string

Error code for a failed payout. This field will be null if the payout has not failed.

failure_message

string

A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.

Retrieve a payout

GET

https://api.payonify.com

/v1/payouts/{id}

Retrieves the details of an existing payout. You can use this endpoint to check the status of a payout.

Payout details

The payout object contains detailed information about the payout, including:

The amount sent
The current status of the payout
Destination details (recipient info, references)
Failure information if applicable

Retrieve a payout › path Parameters

id

string · required

Unique identifier for the payout

Retrieve a payout › Responses

Payout details retrieved successfully

Payout

id

string

Unique identifier for the payout object. Payout IDs have the prefix po_.

object

string

A string representing the type of the object. Always "payout" for payout objects.

object

Contains the monetary value and currency information for the payout.

livemode

boolean

Has the value true if the object exists in live mode or false if in test mode.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

status

string · enum

The status of the payout.

Possible values:

pending: The payout has been created and is being processed.
paid: The payout completed successfully and funds have been delivered.
failed: The payout failed to process.

Enum values:

pending

paid

failed

description

string

Description of the payout, if one was provided at creation time.

object

A set of key-value pairs attached to the payout.

object

Contains information about the payout destination. The structure depends on the destination type used.

failure_code

string

Error code for a failed payout. This field will be null if the payout has not failed.

failure_message

string

A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.