> For the complete documentation index, see [llms.txt](https://docs.zimo-pagos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zimo-pagos.com/api-documentation/deposits-api/endpoints/refund-status-endpoint.md).
# Refund Status Endpoint
Retrieve the status of a previously created refund
## Refund Status
`GET` `https://api-stg.zimo-pagos.com/v3/refunds/{refund_id}`
This endpoint allows you to retrieve the status of a refund request.
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------- | -------------------------------------------------------------- |
| refund\_id\* | Integer | Zimo-pagos refund\_id. It is obtained when creating the refund |
#### Query Parameters
| Name | Type | Description |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| voucher | Boolean | `true` / `false` value, The request with True value will return the refund invoice in base64 to be decoded to create a .pdf. |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------------------------------------------- |
| X-Date\* | String | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` |
| X-Login\* | String | Merchant X-Login API Key |
| Authorization\* | String | Authentication signature hash |
{% tabs %}
{% tab title="200 Refund status successfully retrieved." %}
```java
{
"deposit_id": 300533646,
"merchant_invoice_id": "newIUnit45328731",
"status": "PENDING"
}
```
{% endtab %}
{% tab title="404 The refund with the refund\_id specified could not be found." %}
```java
{
"code": 208,
"description": "Resource not found",
"type": "RESOURCE_NOT_FOUND"
}
```
{% endtab %}
{% endtabs %}
## Description
You can trigger the check of the status of a refund at any moment you consider pertinent. However, every time a refund changes its status, we will send you a [notification](/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications.md) containing the ID of the refund so that you can check its status back to retrieve the new refund's status.
## Refunds Status Request
In order to check the status of the refunds, you need to:
1. Send the request with **GET** method.
2. Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects.md#headers).
3. Specify a valid `refund_id` in the URL of the request as PATH PARAMETERS.
4. Send the Authorization header, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature.md).
Regarding the Authorization value, since the body of the requests will be empty, you should use an empty ("") string or nothing as the `jsonPayload` field.
{% tabs %}
{% tab title="cURL" %}
curl --location --request GET 'https://api-stg.zimo-pagos.com/v3/refunds/1682844' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--data-raw ''
{% endtab %}
{% tab title="JAVA" %}
import java.io.*;
import okhttp3.*;
public class main {
public static void main(String []args) throws IOException{
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api-stg.zimo-pagos.com/v3/refunds/1682844")
.method("GET", null)
.addHeader("X-Login", "{{X-Login}}")
.addHeader("X-Date", "{{X-Date}}")
.addHeader("Authorization", "{{Authorization}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
{% endtab %}
{% tab title="C#" %}
using System;
using RestSharp;
namespace HelloWorldApplication {
class HelloWorld {
static void Main(string[] args) {
var client = new RestClient("https://api-stg.zimo-pagos.com/v3/refunds/1682844");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("X-Login", "{{X-Login}}");
request.AddHeader("X-Date", "{{X-Date}}");
request.AddHeader("Authorization", "{{Authorization}}");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
}
}
}
{% endtab %}
{% tab title="PHP" %}
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-stg.zimo-pagos.com/v3/refunds/1682844",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"X-Login: {{X-Login}}",
"X-Date: {{X-Date}}",
"Authorization: {{Authorization}}",
"Content-Type: application/json"
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
{% endtab %}
{% endtabs %}
## Example response
{% tabs %}
{% tab title="COMPLETED" %}
```java
{
"deposit_id": 300533569,
"merchant_invoice_id": "84044",
"status": "COMPLETED",
"amount": 100.00
}
```
{% endtab %}
{% tab title="PENDING" %}
```java
{
"deposit_id": 300502126,
"merchant_invoice_id": "84121",
"status": "PENDING"
}
```
{% endtab %}
{% endtabs %}
### Response fields
| Field name | Format | Description |
|---|
| Field name | Format | Description |
deposit_id | Integer | ID of the deposit refunded |
merchant_invoice_id | String | Merchant invoice id of the deposit refunded |
status | Enum | Status of the refund. Click here for the full list of refund codes. |
amount | Number | Amount of the refund |
voucher | String | Proof of refund in base64 coding for generation of .pdf file.
Included in response only if voucher is sent as true in query params. |
{% hint style="warning" %}
In order to make the experience more personalized, we may add more fields to this response's object in the future. Please develop your integration to be able to ignore new fields considering that it will continue working fine no matter if we add new fields.
{% endhint %}
## Proof of refund
In order to generate an invoice as proof of refund, you need to:
1. Send the request with **GET** method.
2. Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects.md#headers).
3. Specify a valid `refund_id` in the URL of the request as PATH PARAMETERS.
4. Send the query parameter `voucher` as `true.`
5. Send the Authorization header, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature.md).
Requesting a Refund and including the field `voucher` as a query parameter with value `true` will generate a voucher in base64, this voucher will need to be decoded to create the .pdf
## Status Flow
[Click here](/api-documentation/deposits-api/api-codes.md#refunds-status-codes) to see each Refund Status meaning.
### Refund Status Flow
{% hint style="info" %}
1. DECLINED is not a status by itself. It means the refund failed to be created.
2. As soon as the refund request is created, its status will be PENDING.
3. In case we need more information to complete the request or any of the details were incorrect, we will change the status to INCORRECT\_DETAILS and you will need to provide the correct details. Once the details have been provided, its status will be PENDING again.
4. The status CANCELLED means the refund was manually cancelled by you. Only refunds in PENDING or INCORRECT\_DETAILS can be cancelled. Final status.
5. If everything is fine we will send the refund for processing and the status will be marked as DELIVERED. It can't be cancelled at this point.
6. As soon as the processor/bank confirms the refund, it will be marked as COMPLETED or REJECTED (by the bank).
7. There are some **corner cases** in which the receiver's bank tell us that the refund was completed but days after it gets rejected. In those cases the status changes from COMPLETED to REJECTED.
{% endhint %}
## Status codes
Check all the possible status in the following page:
{% content-ref url="/pages/-M8MAwZ0r4Szs2f\_lbbI" %}
[API Codes](/api-documentation/deposits-api/api-codes.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.zimo-pagos.com/api-documentation/deposits-api/endpoints/refund-status-endpoint.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.