Transfers
The Transfers API powers Payonify Relay - our product for marketplace and platform businesses. You collect from customers with ordinary charges, then pay out to the recipients on your platform with Transfer objects, keeping your own commission on each one.
List transfers
Returns the transfers you've created, most recent first. Supports cursor pagination and
filtering by status and currency.
query Parameters
firstReturns the first n transfers. Use with after for forward pagination.
afterA cursor to fetch results after. Use with first.
lastReturns the last n transfers. Use with before for backward pagination.
beforeA cursor to fetch results before. Use with last.
statusFilter by transfer status.
currencyFilter by currency (ISO code, e.g. usd).
start_dateOnly return transfers created on or after this date (YYYY-MM-DD).
end_dateOnly return transfers created on or before this date (YYYY-MM-DD).
List transfers › Responses
A list of transfers
objectType of the returned object.
Array of transfer objects.
Pagination metadata
Create a transfer
Sends money from your available funds to a recipient, with your own commission set by
application_fee_amount. The transfer is processed in the background - you get a
response right away with a pending status, and a webhook once it completes as
succeeded or failed.
Transfer status
A transfer can have one of the following statuses:
pending: The transfer has been accepted and is being processed.succeeded: The money reached the recipient.failed: The transfer did not go through.
Create a transfer › Request Body
amountA positive integer representing the amount delivered to the recipient, in the smallest currency unit (e.g. 100 cents = $1.00). Must be at least the Payonify processing fee for the transfer.
currencyThe 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.
application_fee_amountYour marketplace commission on this transfer, in the smallest currency unit.
Credited in full to your Payonify account when the transfer succeeds. Defaults to 0.
descriptionCreate a transfer › Responses
Transfer created successfully
idUnique identifier for the transfer object. Transfer IDs have the prefix tr_.
objectA string representing the type of the object. Always "transfer".
The amount you asked to send.
What the recipient actually receives, after the transfer fee. Equal to
amount when your project covers the fee (the default), or less when the
recipient covers it. Set who covers the fee in your project settings.
application_fee_amountYour marketplace commission on this transfer, in the smallest currency unit.
descriptionAn arbitrary description you attached to the transfer.
statusThe status of the transfer.
Possible values:
pending: The transfer has been accepted and is being processed.succeeded: The transfer completed and funds were delivered to the recipient.failed: The transfer failed; the gross amount was returned to your relay balance.
The recipient's details. The mobile-money
reference and recipient_name fill in once the disbursement is completed.
livemodeHas the value true if the object exists in live mode or false if in test mode.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
failure_codeError code for a failed transfer. null unless the transfer failed.
failure_messageA human-readable message describing why the transfer failed. null unless the
transfer failed.
Validate a transfer recipient
Confirms a recipient's mobile number and returns the name it's registered to, so you
can catch a wrong number before you disburse. Use the same mobile_money destination
you'd send in a transfer.
Validate a transfer recipient › Request Body
The recipient's mobile-money details, with the provider as the field name.
Validate a transfer recipient › Responses
The recipient is valid
validRetrieve a transfer
Fetches a single transfer by its ID. Use it to check where a transfer got to - its status, and the failure reason if it didn't go through.
path Parameters
idUnique identifier for the transfer (e.g. tr_...).
Retrieve a transfer › Responses
Transfer details retrieved successfully
idUnique identifier for the transfer object. Transfer IDs have the prefix tr_.
objectA string representing the type of the object. Always "transfer".
The amount you asked to send.
What the recipient actually receives, after the transfer fee. Equal to
amount when your project covers the fee (the default), or less when the
recipient covers it. Set who covers the fee in your project settings.
application_fee_amountYour marketplace commission on this transfer, in the smallest currency unit.
descriptionAn arbitrary description you attached to the transfer.
statusThe status of the transfer.
Possible values:
pending: The transfer has been accepted and is being processed.succeeded: The transfer completed and funds were delivered to the recipient.failed: The transfer failed; the gross amount was returned to your relay balance.
The recipient's details. The mobile-money
reference and recipient_name fill in once the disbursement is completed.
livemodeHas the value true if the object exists in live mode or false if in test mode.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
failure_codeError code for a failed transfer. null unless the transfer failed.
failure_messageA human-readable message describing why the transfer failed. null unless the
transfer failed.
Retrieve your relay balance
Returns the funds you hold for each provider and currency - what's available to pay
out or refund, what's still pending in the maturation hold, and what's reserved for
transfers in flight. Money collected on a provider pays out on that same provider.
Worth checking before a transfer to make sure you're holding enough.
Retrieve your relay balance › Responses
Your relay funds, one entry per provider and currency
objectAlways "balance".
livemodeOne entry per provider and currency pool.