> ## 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.

# Refund Webhook

> Receive real-time notifications about credit card refund status changes

Refund webhooks allow you to receive automatic notifications whenever the status of a credit card refund changes. When you [create a refund](/api-reference/cash-in/refund/create-refund) for a credit card charge, WEpayments processes it asynchronously through the card processor and sends a POST request to your notification URL each time the refund reaches a new status.

<Note>
  This webhook is **specific to refunds** and is separate from the [Credit Card Webhook](/credit-card/webhook), which notifies you about the charge (payin) status. A refund generates its own independent notifications.
</Note>

<Warning>
  The payload format described on this page applies to **credit card** refunds. Refunds for other payment methods (such as Pix) may use a different payload structure — see [Create Refund](/api-reference/cash-in/refund/create-refund).
</Warning>

## How It Works

1. **Create a refund** for a credited credit card charge and provide a `notification_url`
2. **Receive notifications** automatically each time the refund status changes
3. **Process the payload** containing the refund details and amounts
4. **Return a 200 OK** response to acknowledge receipt

<Warning>
  A credit card charge can only be refunded if it is **credited to the wallet** and the refund is requested within **180 days** of the original payment. See [Create Refund](/api-reference/cash-in/refund/create-refund) for all refund rules.
</Warning>

## Setting Up the Refund Webhook

To receive notifications, include the `notification_url` parameter when [creating the refund](/api-reference/cash-in/refund/create-refund):

```json theme={null}
{
  "amount": 10000,
  "reason": "Customer requested cancellation",
  "notification_url": "https://your-domain.com/webhooks/credit-card-refund"
}
```

Each refund can have its own notification URL, allowing you to route refund notifications to a dedicated endpoint.

## Refund Statuses

You will receive a webhook for each of the following refund statuses:

| Status ID | Status Name | Description                                                                 |
| --------- | ----------- | --------------------------------------------------------------------------- |
| 2         | Requested   | The refund has been requested and is being processed by the card processor. |
| 4         | Paid        | The refund has been successfully completed.                                 |
| 5         | Error       | An error occurred while processing the refund.                              |

### Refund Status Flow

**Success scenario:**

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

**Error scenario:**

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

## Webhook Payload

When a credit card refund status changes, you'll receive a POST request with the following data:

<ResponseField name="id" type="integer">
  Unique identifier of the refund.

  Example: `123`
</ResponseField>

<ResponseField name="payinId" type="integer">
  ID of the credit card charge (payin) being refunded.

  Example: `456`
</ResponseField>

<ResponseField name="statusId" type="integer">
  Current refund status ID (`2`, `4`, or `5`).
</ResponseField>

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

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

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

<ResponseField name="clientId" type="integer">
  Your client ID in the WEpayments system.
</ResponseField>

<ResponseField name="amountCents" type="integer">
  Amount of this refund, **in cents**.

  Example: `10000`
</ResponseField>

<ResponseField name="statuses" type="array">
  History of all status changes for this refund.

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

    <ResponseField name="statusId" type="integer">
      Status ID (`2`, `4`, or `5`).
    </ResponseField>

    <ResponseField name="status_id" type="integer">
      Same value as `statusId` (kept for backward compatibility).
    </ResponseField>

    <ResponseField name="name" type="string">
      Status name (`Requested`, `Paid`, or `Error`).
    </ResponseField>

    <ResponseField name="notification" type="integer">
      Whether this status change generated a notification (`1`) or not (`0`).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      When this status was set (ISO 8601 format).
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Same value as `createdAt` (kept for backward compatibility).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="endToEndId" type="string">
  End-to-end identifier. Used for Pix refunds; typically `null` for credit card refunds.
</ResponseField>

<ResponseField name="reason" type="string">
  Reason provided when the refund was created.
</ResponseField>

<ResponseField name="walletErrorCode" type="string">
  Error code returned by the processor when the refund fails (status `5`). `null` otherwise.
</ResponseField>

<ResponseField name="callbackUrl" type="string">
  The notification URL configured for this refund.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Refund creation timestamp (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp of the last update (ISO 8601 format).
</ResponseField>

## Example Payloads

<CodeGroup>
  ```json Requested theme={null}
  {
    "id": 123,
    "payinId": 456,
    "statusId": 2,
    "user": {
      "id": 789,
      "name": "João Silva"
    },
    "clientId": 10,
    "amountCents": 10000,
    "statuses": [
      {
        "id": 1,
        "statusId": 2,
        "status_id": 2,
        "name": "Requested",
        "notification": 1,
        "createdAt": "2026-02-19T12:34:56.000000Z",
        "created_at": "2026-02-19T12:34:56.000000Z"
      }
    ],
    "endToEndId": null,
    "reason": "Customer requested cancellation",
    "walletErrorCode": null,
    "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
    "createdAt": "2026-02-19T12:34:56.000000Z",
    "updatedAt": "2026-02-19T12:34:56.000000Z"
  }
  ```

  ```json Paid theme={null}
  {
    "id": 123,
    "payinId": 456,
    "statusId": 4,
    "user": {
      "id": 789,
      "name": "João Silva"
    },
    "clientId": 10,
    "amountCents": 10000,
    "statuses": [
      {
        "id": 1,
        "statusId": 2,
        "status_id": 2,
        "name": "Requested",
        "notification": 1,
        "createdAt": "2026-02-19T12:34:56.000000Z",
        "created_at": "2026-02-19T12:34:56.000000Z"
      },
      {
        "id": 2,
        "statusId": 4,
        "status_id": 4,
        "name": "Paid",
        "notification": 1,
        "createdAt": "2026-02-19T12:36:22.000000Z",
        "created_at": "2026-02-19T12:36:22.000000Z"
      }
    ],
    "endToEndId": null,
    "reason": "Customer requested cancellation",
    "walletErrorCode": null,
    "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
    "createdAt": "2026-02-19T12:34:56.000000Z",
    "updatedAt": "2026-02-19T12:36:22.000000Z"
  }
  ```

  ```json Error theme={null}
  {
    "id": 123,
    "payinId": 456,
    "statusId": 5,
    "user": {
      "id": 789,
      "name": "João Silva"
    },
    "clientId": 10,
    "amountCents": 10000,
    "statuses": [
      {
        "id": 1,
        "statusId": 2,
        "status_id": 2,
        "name": "Requested",
        "notification": 1,
        "createdAt": "2026-02-19T12:34:56.000000Z",
        "created_at": "2026-02-19T12:34:56.000000Z"
      },
      {
        "id": 2,
        "statusId": 5,
        "status_id": 5,
        "name": "Error",
        "notification": 1,
        "createdAt": "2026-02-19T12:35:10.000000Z",
        "created_at": "2026-02-19T12:35:10.000000Z"
      }
    ],
    "endToEndId": null,
    "reason": "Customer requested cancellation",
    "walletErrorCode": "PROCESSOR_ERROR",
    "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
    "createdAt": "2026-02-19T12:34:56.000000Z",
    "updatedAt": "2026-02-19T12:35:10.000000Z"
  }
  ```
</CodeGroup>

## Authentication

Credit card refund webhooks are delivered with the following headers:

| Header         | Value              |
| -------------- | ------------------ |
| `Accept`       | `application/json` |
| `Content-type` | `application/json` |
| `User-Agent`   | `WEpayments`       |

<Note>
  If you have configured a **custom authentication header** for your account (callback authentication key and value), it will be included in every refund webhook request. Contact our support team to set up a custom authentication header so you can validate that the request was sent by WEpayments.
</Note>

## Webhook Endpoint Requirements

Your webhook endpoint must:

* **Accept POST requests** - All webhook notifications are sent via POST
* **Use HTTPS** - Only secure HTTPS URLs are accepted
* **Return 200 OK** - Respond with a 200 status code within 5 seconds
* **Be publicly accessible** - The endpoint must be reachable from the internet

## Retry Policy

<Note>
  If your endpoint responds with a status code other than 200, the notification will be retried up to **15 times**, with a 5-minute interval between attempts.
</Note>

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Refund" icon="rotate-left" href="/api-reference/cash-in/refund/create-refund">
    Create a refund for a credit card charge
  </Card>

  <Card title="Credit Card Webhook" icon="webhook" href="/credit-card/webhook">
    Notifications about the charge status
  </Card>

  <Card title="About Credit Card" icon="credit-card" href="/credit-card/about-credit-card">
    How credit card charges and refund modes work
  </Card>

  <Card title="Create Credit Card Charge" icon="plus" href="/api-reference/credit-card/create-charge">
    Create a new credit card charge
  </Card>
</CardGroup>