> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payin/refund.md).

# Refund

This endpoint allows you to submit a full or partial refund for an eligible payin. The example below shows a PIX refund, which is returned through the original payment route. Refund availability and support for partial refunds depend on the channel used for the original payment.

<mark style="color:green;">`POST`</mark> `https://gateway-test.pagsmile.com/trade/refund`

{% hint style="info" %}
A successful API response confirms that the refund request has been accepted. Use the subsequent payment status notification to determine the final refund result.
{% endhint %}

### Headers

| Name            | Type   | Required | Constraints                                                                                                    | Description                                                                      |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Content-Type`  | string | Yes      | Fixed value: `application/json; charset=UTF-8`.                                                                | Media type of the request body.                                                  |
| `Authorization` | string | Yes      | Use `Basic Base64(app_id:security_key)`. The App ID in the credential must match `app_id` in the request body. | HTTP Basic authentication credential generated with the App ID and security key. |

### Request Body

| Name              | Type   | Required    | Constraints                                                                                                                                                                                                                          | Description                                         |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `app_id`          | string | Yes         | Must match the App ID used in the `Authorization` header.                                                                                                                                                                            | Merchant application ID assigned by Pagsmile.       |
| `timestamp`       | string | Yes         | Format: `yyyy-MM-dd HH:mm:ss`.                                                                                                                                                                                                       | Date and time when the refund request is submitted. |
| `trade_no`        | string | Conditional | Either `trade_no` or `out_trade_no` must be provided. If both are provided, the API uses `trade_no` to locate the original payment.                                                                                                  | Pagsmile transaction ID of the original payment.    |
| `out_trade_no`    | string | Conditional | Either `out_trade_no` or `trade_no` must be provided.                                                                                                                                                                                | Merchant order number of the original payment.      |
| `out_request_no`  | string | Conditional | Maximum length: 255 characters. Required for a partial refund. It must be unique for each refund request and must not be the same as the original `trade_no`. For a full refund, the API generates a value if this field is omitted. | Merchant-defined refund request ID.                 |
| `refund_currency` | string | Yes         | For a PIX refund, use `BRL`. The value must match the order currency or payment currency of the original payment.                                                                                                                    | Currency of the refund.                             |
| `refund_amount`   | string | Yes         | Numeric string. Minimum: `0.01 BRL`. Supports up to two decimal places. It must not exceed the remaining refundable amount. The API-level numeric ceiling is `9,999,999,999,999.99`.                                                 | Amount to refund.                                   |
| `refund_reason`   | string | No          | No request-level length validation is currently applied.                                                                                                                                                                             | Reason for requesting the refund.                   |

{% hint style="warning" %}
The original payment must be in a refundable status, and only one refund request for the same payment can be processing at a time. The total refunded amount must not exceed the amount paid.
{% endhint %}

### Request Sample

```json
{
  "app_id": "166***1",
  "trade_no": "2026***67",
  "out_trade_no": "0d9***ab",
  "out_request_no": "38***0",
  "refund_currency": "BRL",
  "refund_amount": "1.4",
  "refund_reason": "Customer requested a refund",
  "timestamp": "2026-10-08 10:38:28"
}
```

### Response

<table><thead><tr><th width="157.2890625">Name</th><th width="110.1875">Type</th><th width="122.8359375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td>string</td><td>Yes</td><td>Response code. <code>10000</code> indicates that the request was accepted successfully.</td></tr><tr><td><code>msg</code></td><td>string</td><td>Yes</td><td>Response message.</td></tr><tr><td><code>refund_status</code></td><td>string</td><td>Conditional</td><td>Returned when the refund request is accepted. Current refund status returned by the refund processor, such as <code>REFUND_PROCESSING</code>.</td></tr><tr><td><code>sub_code</code></td><td>string</td><td>No</td><td>Detailed error or processing code returned when applicable.</td></tr><tr><td><code>sub_msg</code></td><td>string</td><td>No</td><td>Detailed error or processing message returned when applicable.</td></tr></tbody></table>

#### Response Sample

{% tabs %}
{% tab title="Success" %}

```
{
  "code": "10000",
  "msg": "Success",
  "refund_status": "REFUND_PROCESSING"
}
```

{% endtab %}

{% tab title="Error" %}

```
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "invalid-signature",
  "sub_msg": "invalid signature"
}
```

{% endtab %}
{% endtabs %}