> 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

**Request Base URL**

```
Test Environment: https://gateway-test.pagsmile.com
Production Environment: https://gateway.pagsmile.com
```

**Endpoint**

```
/trade/refund
```

**Request Header**

<table><thead><tr><th width="147.9765625">Parameter</th><th width="157.96875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td>Recommended</td><td><code>application/json</code></td></tr><tr><td><code>Authorization</code></td><td>Yes</td><td><code>Basic Base64(app_id:security_key)</code></td></tr></tbody></table>

**Request Body (JSON format)**

<table><thead><tr><th width="248.8359375">Parameter</th><th width="85.71484375">Type</th><th width="122.62109375">Required</th><th>Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>Maximum 32 characters.</td><td>App ID available in the Pagsmile dashboard.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Must use the <code>yyyy-MM-dd HH:mm:ss</code> format and contain exactly 19 characters.</td><td>Time when the refund request is submitted.</td></tr><tr><td><code>trade_no</code></td><td>string</td><td>Conditional</td><td>Maximum 64 characters. Either <code>trade_no</code> or <code>out_trade_no</code> must be provided. They cannot both be empty.</td><td>Pagsmile transaction ID.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Conditional</td><td>Maximum 64 characters. Either <code>out_trade_no</code> or <code>trade_no</code> must be provided. They cannot both be empty.</td><td>Transaction ID assigned by the merchant.</td></tr><tr><td><code>out_request_no</code></td><td>string</td><td>Conditional</td><td>Maximum 16 characters. Required when submitting a partial refund. The value must uniquely identify the refund request.</td><td>Merchant-defined refund request ID.</td></tr><tr><td><code>refund_currency</code></td><td>string</td><td>Yes</td><td>Must be a valid three-letter currency code, such as <code>MXN</code> or <code>BRL</code>.</td><td>Currency of the refund.</td></tr><tr><td><code>refund_amount</code></td><td>decimal</td><td>Yes</td><td>Must be between <code>0.01</code> and <code>99999999999999.99</code>. The amount must not exceed the refundable amount of the original transaction.</td><td>Amount to refund.</td></tr><tr><td><code>refund_reason</code></td><td>string</td><td>No</td><td>Maximum 128 characters.</td><td>Reason for the refund.</td></tr><tr><td><code>user_info.identify.number</code></td><td>string</td><td>Yes</td><td><p>Maximum 16 characters. </p><p></p><p>Not required for  PIX, Wallet, SPEI and CreditCard. </p></td><td>User's identification number.</td></tr><tr><td><code>user_info.identify.type</code></td><td>string</td><td>No</td><td>Maximum 16 characters.</td><td>User's identification type.</td></tr><tr><td><code>user_info.name</code></td><td>string</td><td>Yes</td><td><p>Maximum 64 characters. </p><p></p><p>Not required for  PIX, Wallet, SPEI and CreditCard. </p></td><td>User's name.</td></tr><tr><td><code>user_info.email</code></td><td>string</td><td>Yes</td><td><p>Maximum 64 characters. If provided, it must be a valid email address.  </p><p></p><p>Not required for  PIX, Wallet, SPEI and CreditCard. </p></td><td>User's email address.</td></tr><tr><td><code>user_info.phone</code></td><td>string</td><td>No</td><td>Maximum 64 characters.</td><td>User's phone number.</td></tr><tr><td><code>bank_info.bank_id</code></td><td>string</td><td>No</td><td>Maximum 64 characters.  </td><td>User's bank ID. See the supported bank list.</td></tr><tr><td><code>bank_info.bank_name</code></td><td>string</td><td>No</td><td>Maximum 64 characters. </td><td>Name of the bank receiving the refund.</td></tr><tr><td><code>bank_info.agency</code></td><td>string</td><td>No</td><td>Maximum 64 characters.</td><td>Bank agency receiving the refund.</td></tr><tr><td><code>bank_info.type</code></td><td>string</td><td>No</td><td>Maximum 64 characters.</td><td>Bank account type receiving the refund.</td></tr></tbody></table>

**Request Sample**

The following example shows a SPEI refund request using only the required bank information:

```bash
curl --location --request POST 'https://gateway.pagsmile.com/trade/refund' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
      "app_id": "app_id",
      "timestamp": "",
      "trade_no": "trade_no", //Require when "out_trade_no" is empty
      "out_trade_no": "", //Require when "trade_no" is empty
      "out_request_no": "", //Require for partial refund
      "refund_amount": 10,
      "refund_currency": "BRL",
      "out_trade_no": "{{  
      "user_info": {
          "identify": {
              "number": "**********",
              "type": "document type"
          },
          "name": "refund name",
          "email": "refund@email.com" //If bank_info is empty, system will send email to this address to collect bank_info
      },
      "bank_info": {
          "bank_id": "****",
          "bank_name": "bank name"
          
      }
}'
```

**HTTP Response (JSON format)**

| Parameter       | Type   | Description                                        |
| --------------- | ------ | -------------------------------------------------- |
| `code`          | string | Return code.                                       |
| `msg`           | string | Return message.                                    |
| `sub_code`      | string | Error code returned when the request fails.        |
| `sub_msg`       | string | Error description returned when the request fails. |
| `refund_status` | string | Current refund status.                             |

**Return Sample (Success)**

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

**Return Sample (Fail)**

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