Payouts

Endpoint:https://api.payonify.com

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

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.

Payout Endpoints

POST /v1/payouts/validateValidate a recipient POST /v1/payoutsCreate a payout GET /v1/payouts/:idRetrieve a payout GET /v1/payoutsList all payouts

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

destinationobject · 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

validboolean
Whether the recipient account is valid and can receive payouts.
recipientobject
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

limitinteger · min: 1 · max: 100
Number of records to return per page. Use with cursor-based pagination.
Default: 10
firstinteger · min: 1 · max: 100
Number of records to return for forward pagination. Use with after cursor.
afterstring
Cursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100
Number of records to return for backward pagination. Use with before cursor.
beforestring
Cursor for backward pagination. Returns records before this cursor.
statusstring · enum
Filter payouts by status.
Enum values:
pending
paid
failed
currencystring · enum
Filter payouts by currency ISO code.
Enum values:
usd
zwg
start_datestring · date
Filter payouts created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · date
Filter payouts created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all payouts › Responses

A list of payouts

objectstring
Type of the returned object.
dataobject[]
Array of payout objects.
pagingobject
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

amountinteger · 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).
currencystring · enum · required
A three-letter ISO currency code. Currently, only usd and zwg are supported.
Enum values:
usd
zwg
destinationobject · 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.

descriptionstring · maxLength: 150
An optional description for the payout. This can be used for internal reference or record-keeping.

Maximum 150 characters.
metadataobject · 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

idstring
Unique identifier for the payout object. Payout IDs have the prefix po_.
objectstring
A string representing the type of the object. Always "payout" for payout objects.
amountobject
Contains the monetary value and currency information for the payout.
livemodeboolean
Has the value true if the object exists in live mode or false if in test mode.
createdinteger
Time at which the object was created. Measured in seconds since the Unix epoch.
statusstring · 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
descriptionstring
Description of the payout, if one was provided at creation time.
metadataobject
A set of key-value pairs attached to the payout.
destination_detailsobject
Contains information about the payout destination. The structure depends on the destination type used.
failure_codestring
Error code for a failed payout. This field will be null if the payout has not failed.
failure_messagestring
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

idstring · required
Unique identifier for the payout

Retrieve a payout › Responses

Payout details retrieved successfully

idstring
Unique identifier for the payout object. Payout IDs have the prefix po_.
objectstring
A string representing the type of the object. Always "payout" for payout objects.
amountobject
Contains the monetary value and currency information for the payout.
livemodeboolean
Has the value true if the object exists in live mode or false if in test mode.
createdinteger
Time at which the object was created. Measured in seconds since the Unix epoch.
statusstring · 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
descriptionstring
Description of the payout, if one was provided at creation time.
metadataobject
A set of key-value pairs attached to the payout.
destination_detailsobject
Contains information about the payout destination. The structure depends on the destination type used.
failure_codestring
Error code for a failed payout. This field will be null if the payout has not failed.
failure_messagestring
A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.

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

destinationobject · 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

validboolean
Whether the recipient account is valid and can receive payouts.
recipientobject
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

limitinteger · min: 1 · max: 100
Number of records to return per page. Use with cursor-based pagination.
Default: 10
firstinteger · min: 1 · max: 100
Number of records to return for forward pagination. Use with after cursor.
afterstring
Cursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100
Number of records to return for backward pagination. Use with before cursor.
beforestring
Cursor for backward pagination. Returns records before this cursor.
statusstring · enum
Filter payouts by status.
Enum values:
pending
paid
failed
currencystring · enum
Filter payouts by currency ISO code.
Enum values:
usd
zwg
start_datestring · date
Filter payouts created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · date
Filter payouts created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all payouts › Responses

A list of payouts

objectstring
Type of the returned object.
dataobject[]
Array of payout objects.
pagingobject
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

amountinteger · 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).
currencystring · enum · required
A three-letter ISO currency code. Currently, only usd and zwg are supported.
Enum values:
usd
zwg
destinationobject · 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.

descriptionstring · maxLength: 150
An optional description for the payout. This can be used for internal reference or record-keeping.

Maximum 150 characters.
metadataobject · 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

idstring
Unique identifier for the payout object. Payout IDs have the prefix po_.
objectstring
A string representing the type of the object. Always "payout" for payout objects.
amountobject
Contains the monetary value and currency information for the payout.
livemodeboolean
Has the value true if the object exists in live mode or false if in test mode.
createdinteger
Time at which the object was created. Measured in seconds since the Unix epoch.
statusstring · 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
descriptionstring
Description of the payout, if one was provided at creation time.
metadataobject
A set of key-value pairs attached to the payout.
destination_detailsobject
Contains information about the payout destination. The structure depends on the destination type used.
failure_codestring
Error code for a failed payout. This field will be null if the payout has not failed.
failure_messagestring
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

idstring · required
Unique identifier for the payout

Retrieve a payout › Responses

Payout details retrieved successfully

idstring
Unique identifier for the payout object. Payout IDs have the prefix po_.
objectstring
A string representing the type of the object. Always "payout" for payout objects.
amountobject
Contains the monetary value and currency information for the payout.
livemodeboolean
Has the value true if the object exists in live mode or false if in test mode.
createdinteger
Time at which the object was created. Measured in seconds since the Unix epoch.
statusstring · 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
descriptionstring
Description of the payout, if one was provided at creation time.
metadataobject
A set of key-value pairs attached to the payout.
destination_detailsobject
Contains information about the payout destination. The structure depends on the destination type used.
failure_codestring
Error code for a failed payout. This field will be null if the payout has not failed.
failure_messagestring
A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.