Refunds
Initiate, track and handle refunds, ensuring smooth reconciliation and customer satisfaction.
Create, retrieve and manage refund transactions within your account. Handle payment reversals and track refund history.
Initiate refund
Create a refund for a specific order or basket by specifying relevant details such as the amount and reason.
Initiate and manage refund requests, returning confirmation and status information upon successful processing.
Query parameters
- Name
api-version- Type
- string
- Description
The requested API version. The parameter is optional. Default value:
2.0.
Headers
- Name
X-Application-ID- Type
- string
- Description
The ID of the application making the request. This header parameter is required for authentication and identification purposes.
- Name
Ocp-Apim-Subscription-Key- Type
- string
- Description
A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.
Body parameters
- Name
orderIdentifier- Type
- string
- Description
The unique identifier of the order linked to the refund request.
- Name
reason- Type
- string(uuid)
- Description
The rationale for initiating the refund, such as customer request or product defect.
- Name
publicBasketId- Type
- string
- Description
The publicly exposed identifier of the basket associated with the refund, safe for external use.
- Name
basketId- Type
- integer
- Description
The unique identifier of the basket associated with the refund request.
- Name
amount- Type
- number
- Description
The amount to be refunded. The value must be greater than zero.
Response attributes
- Name
success- Type
- boolean
- Description
A boolean indicating whether the refund request was successfully processed.
- Name
data- Type
- object
- Description
Detailed information related to the refund request or response, including:
refund_id(string): The unique identifier assigned to the refund transaction.status(string): The current state of the refund process (e.g., pending, completed or failed).created_at(string): The timestamp indicating when the refund was created (ISO 8601 format).message(string): A human-readable message providing additional information about the refund request status or outcome.
- Name
message- Type
- string
- Description
A message associated with the refund.
- Name
errors- Type
- array
- Description
A list of error objects describing any issues encountered during the refund process,including:
code(string): A machine-readable code representing the refund outcome or error type if applicable.message(string): A human-readable message providing additional information about the refund request status or outcome.
- Name
metadata- Type
- object
- Description
A set of key-value pairs attached to the refund for storing additional structured information.
- Name
type- Type
- string
- Description
The classification of the refund, indicating its nature or category.
- Name
title- Type
- string
- Description
A brief, descriptive title summarizing the refund or related response message.
- Name
status- Type
- integer
- Description
The current state of the refund process (e.g., pending, completed or failed).
- Name
detail- Type
- string
- Description
Additional details providing context or explanation related to the refund response or errors.
- Name
instance- Type
- string
- Description
The specific instance or environment context in which the refund was processed.
Request
curl -X POST /refunds \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Application-ID: string' \
-H 'Ocp-Apim-Subscription-Key: string
-d '{
"orderIdentifier": "string",
"reason": "string",
"publicBasketId": "string",
"basketId": 0,
"amount": 0
}'
Response examples
{
"success": false,
"data": {
"refund_id": "",
"status": "",
"created_at": "",
"message": ""
},
"message": "",
"errors": [
{
"code": "",
"message": ""
}
],
"metadata": {}
}
Responses
| Status | Description | Notes |
|---|---|---|
| 201 | Created | Information for the initiated refund. |
| 400 | Bad Request | Invalid request. |
| 500 | Internal Error | Internal server error. |
Retrieve refunds by date
Retrieve a list of refunds processed within a specified date range.
Monitor and manage refund activity effectively. Filter all refund records by creation date, providing detailed information such as refund status, timestamps and associated messages.
Query parameters
- Name
api-version- Type
- string
- Description
The requested API version. The parameter is optional. Default value:
2.0.
- Name
dateFrom- Type
- date-time
- Description
Start date filter for retrieving refunds, formatted as
YYYY-MM-DD.
- Name
dateTo- Type
- date-time
- Description
End date filter for retrieving refunds, formatted as
YYYY-MM-DD.
Headers
- Name
X-Application-ID- Type
- string
- Description
The ID of the application making the request. This header parameter is required for authentication and identification purposes.
- Name
Ocp-Apim-Subscription-Key- Type
- string
- Description
A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.
Response attributes
- Name
success- Type
- boolean
- Description
A boolean indicating whether the refund request was successfully processed.
- Name
data- Type
- object
- Description
The detailed refund information returned by the API, including:
refund_id(string): The unique identifier for the refund transaction.status(string): The current status of the refund (e.g., pending, completed or failed).created_at(string): The timestamp indicating when the refund was created, formatted in ISO 8601.message(string): A descriptive message providing additional context or information about the refund status.
- Name
message- Type
- string
- Description
A message associated with the refund.
- Name
errors- Type
- array
- Description
A list of error objects describing any issues encountered during the refund request,including:
code(string): Error or status code associated with the refund response.message(string): A human-readable message providing additional information about the refund request status.
- Name
metadata- Type
- object
- Description
Key-value pairs with additional information related to the refund, provided by the client.
- Name
type- Type
- string
- Description
The classification of the refund, indicating its nature or category.
- Name
title- Type
- string
- Description
A brief, descriptive title summarizing the refund or related response message.
- Name
status- Type
- integer
- Description
The current state of the refund process (e.g., pending, completed or failed).
- Name
detail- Type
- string
- Description
Additional details providing context or explanation related to the refund response or errors.
- Name
instance- Type
- string
- Description
The specific instance or environment context in which the refund was processed.
Request
curl -X GET /refunds \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Application-ID: string' \
-H 'Ocp-Apim-Subscription-Key: string
Response examples
{
"success": true,
"data": [
{
"refund_id": "",
"status": "",
"created_at": "",
"message": ""
}
],
"message": "",
"errors": [
{
"code": "",
"message": ""
}
],
"metadata": {}
}
Responses
| Status | Description | Notes |
|---|---|---|
| 200 | Created | A collection of refunds in the given date range. |
| 400 | Bad Request | Invalid request. |
| 404 | Not Found | Not Found. |
| 500 | Internal Error | Internal server error. |
Find refund by id
Retrieve detailed information about a specific refund by providing its unique identifier.
Access the refund’s current status, creation time and associated metadata to effectively track and manage refund transactions.
Path parameters
- Name
refundId- Type
- string
- Description
The unique identifier of the refund to be retrieved.
Query parameters
- Name
api-version- Type
- string
- Description
The requested API version. The parameter is optional. Default value:
2.0.
Headers
- Name
X-Application-ID- Type
- string
- Description
The ID of the application making the request. This header parameter is required for authentication and identification purposes.
- Name
Ocp-Apim-Subscription-Key- Type
- string
- Description
A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.
Response attributes
- Name
success- Type
- boolean
- Description
A boolean indicating whether the refund request was successfully processed.
- Name
data- Type
- object
- Description
The detailed refund information returned by the API, including:
refund_id(string): The unique identifier for the refund transaction.status(string): The current status of the refund (e.g., pending, completed or failed).created_at(string): The timestamp indicating when the refund was created, formatted in ISO 8601.message(string): A descriptive message providing additional context or information about the refund status.
- Name
message- Type
- string
- Description
A message associated with the refund.
- Name
errors- Type
- array
- Description
A list of error objects describing any issues encountered during the refund request,including:
code(string): Error or status code associated with the refund response.message(string): A human-readable message providing additional information about the refund request status.
- Name
metadata- Type
- object
- Description
Key-value pairs with additional information related to the refund, provided by the client.
- Name
type- Type
- string
- Description
The classification of the refund, indicating its nature or category.
- Name
title- Type
- string
- Description
A brief, descriptive title summarizing the refund or related response message.
- Name
status- Type
- integer
- Description
The current state of the refund process (e.g., pending, completed or failed).
- Name
detail- Type
- string
- Description
Additional details providing context or explanation related to the refund response or errors.
- Name
instance- Type
- string
- Description
The specific instance or environment context in which the refund was processed.
Request
curl -X GET /refunds/{refundId} \
-H 'Accept: application/json' \
-H 'X-Application-ID: string' \
-H 'Ocp-Apim-Subscription-Key: string
Response examples
{
"success": true,
"data": {
"refund_id": "",
"status": "",
"created_at": "",
"message": ""
},
"message": "",
"errors": [
{
"code": "",
"message": ""
}
],
"metadata": {}
}
Responses
| Status | Description | Notes |
|---|---|---|
| 200 | Created | A collection of refunds in the given date range. |
| 400 | Bad Request | Invalid request. |
| 404 | Not Found | Not Found. |
| 500 | Internal Error | Internal server error. |