> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/webhooks/readme/refunds.md).

# Refunds

Refund webhook events and example payloads.

Refund webhooks track refund creation, completion, and failure.

Use these events to keep refund state in sync with your support and ledger systems.

### Field descriptions

Refund webhook events use `data.refund`.

| Field                       | Type                       | Description                                                |
| --------------------------- | -------------------------- | ---------------------------------------------------------- |
| `data.refund.id`            | `string`                   | Unique refund identifier.                                  |
| `data.refund.entity`        | `string`                   | What was refunded: `session` or `invoice`.                 |
| `data.refund.reference`     | `string`                   | Reference of the refunded session or invoice.              |
| `data.refund.status`        | `string`                   | Refund status. See each event below.                       |
| `data.refund.reason`        | `string \| null`           | Optional reason for the refund.                            |
| `data.refund.chain`         | `string`                   | Blockchain network, such as `tron` or `ethereum`.          |
| `data.refund.asset`         | `string`                   | Crypto asset, such as `USDT`.                              |
| `data.refund.amount`        | `string`                   | Crypto amount refunded to the customer.                    |
| `data.refund.fee`           | `string`                   | Network fee for the refund.                                |
| `data.refund.feePaidBy`     | `'merchant' \| 'customer'` | Who paid the refund network fee.                           |
| `data.refund.fiatAmount`    | `string`                   | Fiat value of the refund amount.                           |
| `data.refund.fiatCurrency`  | `string`                   | Fiat currency.                                             |
| `data.refund.balanceSource` | `string`                   | Which balance paid for the refund: `settled` or `pending`. |
| `data.refund.refundAddress` | `string`                   | Customer wallet address that receives the refund.          |
| `data.refund.txHash`        | `string \| null`           | Transaction hash on the blockchain, once sent.             |
| `data.refund.explorerUrl`   | `string \| null`           | Block explorer link for the refund transaction.            |
| `data.refund.createdAt`     | `string`                   | When the refund was created (ISO 8601).                    |
| `data.refund.completedAt`   | `string \| null`           | When the refund completed. Null until then.                |
| `data.refund.failureReason` | `string \| null`           | Why the refund failed. Null unless it failed.              |

### Events

* `refund.created`
* `refund.success`
* `refund.failed`

### `refund.created`

Sent when a refund is created. `data.refund.status` is `pending` or `processing`.

Use this event to start refund tracking.

```json
{
  "event": "refund.created",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "pending",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "balanceSource": "settled",
      "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1",
      "txHash": null,
      "explorerUrl": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": null,
      "failureReason": null
    }
  }
}
```

### `refund.success`

Sent when a refund completes. `data.refund.status` is `success`.

Use this event to mark the refund as settled.

```json
{
  "event": "refund.success",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "success",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "balanceSource": "settled",
      "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1",
      "txHash": "7c2d4f9e1b3a5c8d0e6f2a4b9c1d3e5f7a8b0c2d4e6f8a1b3c5d7e9f0a2b4c6d",
      "explorerUrl": "https://tronscan.org/#/transaction/7c2d4f9e1b3a5c8d0e6f2a4b9c1d3e5f7a8b0c2d4e6f8a1b3c5d7e9f0a2b4c6d",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": "2024-01-15T10:45:00.000Z",
      "failureReason": null
    }
  }
}
```

### `refund.failed`

Sent when a refund fails. `data.refund.status` is `failed`.

Use this event to notify support or retry with a corrected address.

{% hint style="danger" %}
Check `data.refund.failureReason` for why the refund failed.
{% endhint %}

```json
{
  "event": "refund.failed",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "failed",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "balanceSource": "settled",
      "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1",
      "txHash": null,
      "explorerUrl": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": null,
      "failureReason": "Invalid address"
    }
  }
}
```