> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Refund

> Create a new refund. To initiate the refund, you must provide the unique identifier of the Pix or credit card payment in the {id} parameter.

## Some important rules

<Warning>
  * Only charges **credited to the wallet** can be refunded.
  * The customer must have at least the **refund amount available** in the wallet.
  * **Pix**: can only be returned with **90 days or less**.
  * **Credit card**: **180 days or less**.
</Warning>

## Sandbox Testing

<Note>
  To test refund scenarios in the sandbox environment, the field `amount` must be one of the following values: **100**, **1000**, or **10000**.

  Additionally, you must include the field `reason` with the value **"APRO"**.
</Note>

## Path Parameters

<ParamField path="id" type="integer" required>
  The cash-in ID (payin ID) for which the refund will be created.

  Example: `63730`
</ParamField>

## Request Body

<ParamField body="amount" type="integer" required>
  The refund amount.

  Example: `10`
</ParamField>

<ParamField body="reason" type="string" required>
  Reason for the refund.

  Example: `"Teste"`
</ParamField>

<ParamField body="notification_url" type="string">
  URL to receive webhook notifications about refund status changes.
</ParamField>

## Response

<ResponseField name="id" type="integer">
  Refund ID.
</ResponseField>

<ResponseField name="payin_id" type="integer">
  The ID of the payin (cash-in) being refunded.
</ResponseField>

<ResponseField name="status_id" type="integer">
  Current status ID of the refund.

  Status codes:

  * `2`: Requested
  * `4`: Paid (refund completed)
  * `5`: Error
</ResponseField>

<ResponseField name="user" type="object">
  User who created the refund.

  <Expandable title="User">
    <ResponseField name="id" type="integer">
      User ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      User name.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="client_id" type="integer">
  Client ID.
</ResponseField>

<ResponseField name="refund_amount" type="integer">
  Refund amount.
</ResponseField>

<ResponseField name="status_history" type="array">
  History of status changes.

  <Expandable title="Status History Item">
    <ResponseField name="id" type="integer">
      Status history ID.
    </ResponseField>

    <ResponseField name="status_id" type="integer">
      Status ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Status name.
    </ResponseField>

    <ResponseField name="notification" type="integer">
      Notification flag.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When this status was set.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="end_to_end_id" type="string">
  End-to-end ID (for Pix transactions). Can be `null`.
</ResponseField>

<ResponseField name="reason" type="string">
  Reason for the refund.
</ResponseField>

<ResponseField name="wallet_error_code" type="string">
  Error code from wallet (if any). Can be `null`.
</ResponseField>

<ResponseField name="notification_url" type="string">
  URL for webhook notifications. Can be `null`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Refund created date.
</ResponseField>

<ResponseField name="updated_at" type="string">
  Refund update date.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 123,
    "payin_id": 456,
    "status_id": 2,
    "user": {
      "id": 789,
      "name": "João Silva"
    },
    "client_id": 10,
    "refund_amount": 10000,
    "status_history": [
      {
        "id": 1,
        "payin_refund_id": 123,
        "statusId": 1,
        "status_id": 1,
        "name": "Check",
        "notification": 1,
        "created_at": "2026-02-19T12:34:56.000000Z"
      }
    ],
    "end_to_end_id": "E12345678202602191234567890AB",
    "reason": "Customer requested cancellation",
    "wallet_error_code": null,
    "notification_url": "https://example.com/webhook",
    "created_at": "2026-02-19T12:34:56.000000Z",
    "updated_at": "2026-02-19T12:34:56.000000Z"
  }

  ```

  ```json 400 theme={null}
  { 
    "message": "Bad request message" 
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized"
  }
  ```

  ```json 404 theme={null}
  {
    "message": "Payin not found"
  }
  ```

  ```json 422 theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "amount": [
        "The amount field is required."
      ]
    }
  }
  ```

  ```json 500 Internal server error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>

## Important Information About the Webhook metadata

### Refund Status

| Status    | Description                                  | Status ID |
| --------- | -------------------------------------------- | --------- |
| Requested | The refund has been requested.               | 2         |
| Paid      | The refund has been successfully paid.       | 4         |
| Error     | An error occurred during the refund process. | 5         |

<Warning>
  If an error occurs during the refund process (status 5), the field `total_refund_amount` will be **decremented** by the requested amount. When the refund is successfully paid, the amount will be **incremented** again.
</Warning>

### Webhook Payload Examples:

**Requested:**

```json theme={null}
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 2,
    "name": "Requested"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 250.75
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:34:56.000000Z"
}
```

**Error:**

```json theme={null}
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 5,
    "name": "Error"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 150.25
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:35:10.000000Z"
}
```

**Paid:**

```json theme={null}
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 4,
    "name": "Paid"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 250.75
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:36:22.000000Z"
}
```

## Refund Status Flow

**Success scenario:**

```
REQUESTED (2) → PAID (4) ✓
```

**Error scenario:**

```
REQUESTED (2) → ERROR (5) ✗
```