Refunds
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
limitNumber of records to return per page. Use with cursor-based pagination.
firstNumber of records to return for forward pagination. Use with after cursor.
afterCursor for forward pagination. Returns records after this cursor.
lastNumber of records to return for backward pagination. Use with before cursor.
beforeCursor for backward pagination. Returns records before this cursor.
statusFilter refunds by status.
currencyFilter refunds by currency ISO code.
start_dateFilter refunds created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_dateFilter refunds created on or before this date. Use ISO 8601 format (YYYY-MM-DD).
List all refunds › Responses
A list of refunds
objectType of the returned object.
Array of refund objects.
Pagination 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.
Create a new refund › Request Body
chargeThe identifier of the charge to refund. This is the ID of the original charge that you want to refund.
reasonReason 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.
A 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.
Create a new refund › Responses
Refund created successfully
idUnique identifier for the refund object. This ID is used to reference the refund in other API calls.
objectA string representing the type of the object. Always "refund" for
refund objects.
Contains the monetary value and currency information for the refund.
createdTime 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.
chargeID of the charge that was refunded. This links the refund to the original charge transaction.
reasonReason for the refund. This is the explanation provided when creating the refund.
statusStatus 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.
A 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_codeError 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_reasonA 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.
Contains 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_money or card
object 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
idUnique identifier for the refund
Retrieve a refund › Responses
Refund details retrieved successfully
idUnique identifier for the refund object. This ID is used to reference the refund in other API calls.
objectA string representing the type of the object. Always "refund" for
refund objects.
Contains the monetary value and currency information for the refund.
createdTime 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.
chargeID of the charge that was refunded. This links the refund to the original charge transaction.
reasonReason for the refund. This is the explanation provided when creating the refund.
statusStatus 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.
A 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_codeError 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_reasonA 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.
Contains 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_money or card
object depending on the original payment type.