A Refund object represents a reversal of funds from a previously created charge. When you create a refund, Payonify attempts to return the funds to the customer's original payment method.
List all refunds
Returns a paginated list of refunds. The refunds are returned sorted by creation date, with the most recently created refunds appearing first.
Using pagination
By default, this endpoint returns 10 refunds 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 refunds by status.
Enum values:pendingprocessingsucceededfailedcancelledcurrencystring · enumFilter refunds by currency ISO code.
Enum values:usdzwgstart_datestring · dateFilter refunds created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · dateFilter refunds created on or before this date. Use ISO 8601 format (YYYY-MM-DD).
Responses
A list of refunds
objectstringType of the returned object.
dataobject[]Array of refund objects.
pagingobjectPagination metadata
Create a new refund
Creates a new refund for a specified charge. A refund reverses a previous payment and returns the funds to the customer.
Request Body Example
Code
Refund status
A refund can have one of the following statuses:
pending: The refund has been created but not yet processed.processing: The refund is in the process of being completed.succeeded: The refund completed successfully.failed: The refund was attempted but failed.cancelled: The refund was cancelled.
Request Body
chargestring · requiredThe identifier of the charge to refund. This is the ID of the original charge that you want to refund.
reasonstringReason for the refund. This helps with record-keeping and can be useful for tracking why refunds were issued.
This field is optional but recommended for better tracking and reporting.
metadataobject · maxProps: 5A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the refund in a structured way.
You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.
Responses
Refund created successfully
idstringUnique identifier for the refund object. This ID is used to reference the refund in other API calls.
objectstringA string representing the type of the object. Always
"refund"for refund objects.amountobjectContains the monetary value and currency information for the refund.
createdintegerTime at which the object was created. Measured in seconds since the Unix epoch.
This timestamp can be used to track when the refund was initially created.
chargestringID of the charge that was refunded. This links the refund to the original charge transaction.
reasonstringReason for the refund. This is the explanation provided when creating the refund.
statusstring · enumStatus of the refund. This field indicates where the refund is in the processing lifecycle.
Possible values:
pending: The refund has been created but not yet processed.processing: The refund is in the process of being completed.succeeded: The refund completed successfully.failed: The refund was attempted but failed.cancelled: The refund was cancelled.
Enum values:pendingprocessingsucceededfailedcancelledmetadataobjectA set of key-value pairs that can be attached to an object. This is useful for storing additional information about the refund in a structured way.
Metadata is not displayed to the customer and can be used for your internal systems to track refunds, correlate with other systems, etc.
failure_codestringError code for a failed refund. This field will be populated only if the refund failed. The code can be used to programmatically handle specific error cases.
If the refund was processed successfully, this field will be
null.failure_reasonstringA human-readable message providing more details about why the refund failed. This message can be displayed to the user or used for debugging.
If the refund was processed successfully, this field will be
null.refund_detailsobjectContains information about the refund details. This object provides detailed information about how the refund was processed.
The structure of this object depends on the payment method used for the original transaction. It will contain either a
mobile_moneyorcardobject depending on the original payment type.
Retrieve a refund
Retrieves the details of an existing refund. You can use this endpoint to check the status of a refund.
Refund details
The refund object contains detailed information about the refund, including:
- The amount refunded
- The ID of the original charge
- The current status of the refund
- Payment method details
- Refund reference information from the payment provider
path Parameters
idstring · requiredUnique identifier for the refund
Responses
Refund details retrieved successfully
idstringUnique identifier for the refund object. This ID is used to reference the refund in other API calls.
objectstringA string representing the type of the object. Always
"refund"for refund objects.amountobjectContains the monetary value and currency information for the refund.
createdintegerTime at which the object was created. Measured in seconds since the Unix epoch.
This timestamp can be used to track when the refund was initially created.
chargestringID of the charge that was refunded. This links the refund to the original charge transaction.
reasonstringReason for the refund. This is the explanation provided when creating the refund.
statusstring · enumStatus of the refund. This field indicates where the refund is in the processing lifecycle.
Possible values:
pending: The refund has been created but not yet processed.processing: The refund is in the process of being completed.succeeded: The refund completed successfully.failed: The refund was attempted but failed.cancelled: The refund was cancelled.
Enum values:pendingprocessingsucceededfailedcancelledmetadataobjectA set of key-value pairs that can be attached to an object. This is useful for storing additional information about the refund in a structured way.
Metadata is not displayed to the customer and can be used for your internal systems to track refunds, correlate with other systems, etc.
failure_codestringError code for a failed refund. This field will be populated only if the refund failed. The code can be used to programmatically handle specific error cases.
If the refund was processed successfully, this field will be
null.failure_reasonstringA human-readable message providing more details about why the refund failed. This message can be displayed to the user or used for debugging.
If the refund was processed successfully, this field will be
null.refund_detailsobjectContains information about the refund details. This object provides detailed information about how the refund was processed.
The structure of this object depends on the payment method used for the original transaction. It will contain either a
mobile_moneyorcardobject depending on the original payment type.