Retrieve All Refunds: /refunds
Purpose
This API retrieves a list of all refunds recorded in the system. Each refund entry includes details such as refund ID, amount, payment method, reference, associated credit note, custom attributes, and metadata such as creation and update details. It supports pagination for efficiently handling large datasets.
Use Case
- Retrieve a complete list of refunds processed within an account.
- View refund details such as amount, payment method, and reference information.
- Track refund transactions against associated credit notes.
- Access audit details like created/updated timestamps and user information.
- Support pagination for large refund datasets to improve performance and manageability.
Path Parameters
No path parameters required for this endpoint.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | Integer | Maximum number of refund records to return per page (default: 20). |
offset | Integer | Number of records to skip before starting to return results (for pagination). |
Request Body
No request body is required for this endpoint.
Response
On success, this endpoint returns a collection of refund objects under the refunds array. Each refund contains details like status, ID, amount, payment details, associated credit note, and custom attributes. The response also includes pagination details to navigate through multiple pages of refund data.
Response Body
{
"refunds": [
{
"status": "ACTIVE",
"id": "{{refund_id}}",
"amount": "{{refund_amount}}",
"reference": "{{reference_number}}",
"note": "{{refund_note}}",
"payment_method": "{{payment_method}}",
"payment_processor": "{{payment_processor}}",
"gateway_response": "{{gateway_response_message}}",
"credit_note_id": "{{credit_note_id}}",
"custom_attributes": [
{
"name": "{{attribute_name}}",
"value": "{{attribute_value}}"
}
],
"version": "{{version_number}}",
"created_by": "{{created_user}}",
"created_on": "{{created_timestamp}}",
"last_updated_by": "{{updated_user}}",
"last_updated_on": "{{updated_timestamp}}",
"uuid": "{{refund_uuid}}"
}
],
"pagination": {
"records": "{{total_records}}",
"limit": "{{limit_value}}",
"offset": "{{offset_value}}",
"previous_page": "{{previous_page_url}}",
"next_page": "{{next_page_url}}"
}
}
| Attribute | Type | Description |
|---|---|---|
| refunds | Array | List of refund objects retrieved from the system. |
| status | String | Status of the refund (example: ACTIVE, INACTIVE). |
| id | String | Unique identifier for the refund transaction. |
| amount | String | Total refund amount. |
| reference | String | External or internal reference number linked to the refund. |
| note | String | Additional notes or comments associated with the refund. |
| payment_method | String | Method used for refund payment (example: Cash, SecurePay). |
| payment_processor | String | Processor responsible for handling the payment. |
| gateway_response | String | Response message returned from the payment gateway, if applicable. |
| credit_note_id | String | Identifier of the credit note associated with this refund. |
| custom_attributes | Array | List of user-defined custom attributes assigned to the refund. |
| custom_attributes.name | String | Name of the custom attribute. |
| custom_attributes.value | String | Value of the custom attribute. |
| version | String | Version number of the refund record. |
| created_by | String | Name of the user who created the refund entry. |
| created_on | String (ISO 8601) | Timestamp of when the refund was created. |
| last_updated_by | String | Name of the user who last updated the refund record. |
| last_updated_on | String (ISO 8601) | Timestamp of when the refund record was last updated. |
| uuid | String | System-generated unique identifier for the refund record. |
| pagination | Object | Pagination details for navigating through refund records. |
| pagination.records | Integer | Total number of refund records available. |
| pagination.limit | Integer | Number of records returned per page. |
| pagination.offset | Integer | Offset index for current page of results. |
| pagination.previous_page | String | URL of the previous page, if available. |
| pagination.next_page | String | URL of the next page, if available. |
Retrieve Specific Refund Details : /refunds/{refund_id}
Purpose
This endpoint retrieves the details of a specific refund using its unique identifier. It provides comprehensive information about the refund, including status, amount, associated credit note, payment method, custom attributes, and audit metadata.
Use Case
The endpoint is used to fetch and review the details of a specific refund transaction. This allows businesses to verify refund history, reconcile payments, and ensure that refunds are processed and recorded correctly against credit notes or payments.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| refund_id | String | Unique identifier of the refund to be retrieved. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
No request body is required for this endpoint.
Response
The endpoint response returns the complete details of the refund, including its status, refund ID, refunded amount, payment method, payment processor, related credit note ID, and any custom attributes. It also provides audit details such as who created or updated the refund, timestamps, versioning information, and the unique UUID for tracking.
Response Body
{
"refund": {
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "REFUND_REFERENCE",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Current status of the refund (example: ACTIVE). |
| id | String | Unique identifier of the refund. |
| amount | String | The refunded amount. |
| reference | String | Reference associated with the refund. |
| note | String | Additional notes about the refund. |
| payment_method | String | Method used for the refund (example: Cash, Card). |
| payment_processor | String | Processor used for handling the refund. |
| gateway_response | String | Response details from the payment gateway, if applicable. |
| credit_note_id | String | Identifier of the related credit note. |
| custom_attributes | Array | List of custom attributes linked to the refund. |
| version | String | Version number of the refund record. |
| created_by | String | User who created the refund record. |
| created_on | String | Timestamp of when the refund was created. |
| last_updated_by | String | User who last updated the refund. |
| last_updated_on | String | Timestamp of the last update. |
| uuid | String | Unique UUID of the refund record. |
Retrieve refund list of a particular account : /accounts/{account_id}/refunds
Purpose
This endpoint retrieves a list of refunds associated with a specific account. It provides details of each refund, including amount, payment method, credit note reference, audit information, and pagination data for navigating through multiple refund records.
Use Case
This API endpoint is used to track all refunds linked to a particular account. It allows businesses to review refund histories, reconcile credit note applications, and check financial records for an account. Pagination support ensures efficient retrieval of large refund datasets.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| account_id | String | Unique identifier of the account for which refunds are to be retrieved. |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Maximum number of records to return per page. |
| offset | Integer | Number of records to skip before starting to return results. |
Request Body
No request body is required for this endpoint.
Response
The API endpoint response includes a list of refund records with details such as refund status, ID, amount, payment information, credit note association, audit trail, and custom attributes. It also provides pagination details to navigate through refund records.
Response Body
{
"account": {
"refunds": [
{
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "EMPTY",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
},
{
"status": "STATUS",
"id": "REFUND_ID",
"amount": "NUMBER",
"reference": "EMPTY",
"note": "REFUND_NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"gateway_response": "EMPTY",
"credit_note_id": "CREDIT_NOTE_ID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "EMPTY"
}
],
"version": "VERSION",
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "TIMESTAMP",
"uuid": "UUID"
}
],
"pagination": {
"records": "NUMBER",
"limit": "NUMBER",
"offset": "NUMBER",
"previous_page": "URL",
"next_page": "URL"
}
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Status of the refund (example: ACTIVE). |
| id | String | Unique identifier of the refund. |
| amount | String | Refunded amount. |
| reference | String | Optional reference for the refund. |
| note | String | Note associated with the refund. |
| payment_method | String | Method used for refund (example: Cash). |
| payment_processor | String | Processor handling the refund. |
| gateway_response | String | Response from payment gateway. |
| credit_note_id | String | Associated credit note ID. |
| custom_attributes | Array | List of custom attributes attached to refund. |
| version | String | Version of the refund record. |
| created_by | String | User who created the refund. |
| created_on | String | Timestamp when the refund was created. |
| last_updated_by | String | User who last updated the refund. |
| last_updated_on | String | Timestamp when refund was last updated. |
| uuid | String | Unique UUID for the refund record. |
| records | Integer | Total number of refund records available. |
| limit | Integer | Maximum number of refunds returned per page. |
| offset | Integer | Starting point of records in the current response. |
| previous_page | String | URL for the previous page of refunds. |
| next_page | String | URL for the next page of refunds. |