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.
Validate a payout recipient
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
Request Body
destinationobject · requiredThe 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.
Responses
Recipient validated successfully
validbooleanWhether the recipient account is valid and can receive payouts.
recipientobjectDetails about the validated recipient. Only present when
validistrue.
List all 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
query Parameters
limitinteger · min: 1 · max: 100Number of records to return per page. Use with cursor-based pagination.
Default: 10firstinteger · min: 1 · max: 100Number of records to return for forward pagination. Use with
aftercursor.afterstringCursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100Number of records to return for backward pagination. Use with
beforecursor.beforestringCursor for backward pagination. Returns records before this cursor.
statusstring · enumFilter payouts by status.
Enum values:pendingpaidfailedcurrencystring · enumFilter payouts by currency ISO code.
Enum values:usdzwgstart_datestring · dateFilter payouts created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · dateFilter payouts created on or before this date. Use ISO 8601 format (YYYY-MM-DD).
Responses
A list of payouts
objectstringType of the returned object.
dataobject[]Array of payout objects.
pagingobjectPagination metadata
Create a payout
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
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.
Request Body
amountinteger · min: 100 · requiredA 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 · requiredA three-letter ISO currency code. Currently, only
usdandzwgare supported.Enum values:usdzwgdestinationobject · requiredThe 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: 150An optional description for the payout. This can be used for internal reference or record-keeping.
Maximum 150 characters.
metadataobject · maxProps: 5A 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.
Responses
Payout created successfully
idstringUnique identifier for the payout object. Payout IDs have the prefix
po_.objectstringA string representing the type of the object. Always
"payout"for payout objects.amountobjectContains the monetary value and currency information for the payout.
livemodebooleanHas the value
trueif the object exists in live mode orfalseif in test mode.createdintegerTime at which the object was created. Measured in seconds since the Unix epoch.
statusstring · enumThe 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:pendingpaidfaileddescriptionstringDescription of the payout, if one was provided at creation time.
metadataobjectA set of key-value pairs attached to the payout.
destination_detailsobjectContains information about the payout destination. The structure depends on the destination type used.
failure_codestringError code for a failed payout. This field will be
nullif the payout has not failed.failure_messagestringA human-readable message providing more details about why the payout failed. This field will be
nullif the payout has not failed.
Retrieve a payout
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
path Parameters
idstring · requiredUnique identifier for the payout
Responses
Payout details retrieved successfully
idstringUnique identifier for the payout object. Payout IDs have the prefix
po_.objectstringA string representing the type of the object. Always
"payout"for payout objects.amountobjectContains the monetary value and currency information for the payout.
livemodebooleanHas the value
trueif the object exists in live mode orfalseif in test mode.createdintegerTime at which the object was created. Measured in seconds since the Unix epoch.
statusstring · enumThe 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:pendingpaidfaileddescriptionstringDescription of the payout, if one was provided at creation time.
metadataobjectA set of key-value pairs attached to the payout.
destination_detailsobjectContains information about the payout destination. The structure depends on the destination type used.
failure_codestringError code for a failed payout. This field will be
nullif the payout has not failed.failure_messagestringA human-readable message providing more details about why the payout failed. This field will be
nullif the payout has not failed.