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

# Refund Status Webhook Payload

> Reference for the Atoa 'refund Status Webhook Response' webhook payload, the fields Atoa sends and an example JSON body to handle.

Delivered when a refund is completed, fails, or is cancelled. Excludes POS terminal voids, which are delivered under [`POS_PAYMENT_STATUS`](https://docs.paywithatoa.com/api-reference/webhook/pos-payment-status-webhook-response).

| Status | Description |
| - | - |
| **COMPLETED** | Refund has been completed and credited to the customer's bank account. |
| **FAILED** | Refund could not be processed at this time. |
| **CANCELLED** | Refund has been cancelled by one of your users. |

> [!NOTE]
>
> **V2 Webhook Signing:** If you have enabled [V2 webhook signing](https://docs.paywithatoa.com/api-reference/webhook/v2-signing.md), the `signatureHash` field is removed from the payload and an `eventType` field is added. The webhook signature is delivered in the `X-Atoa-Signature` HTTP header instead.

```json Completed theme={null}
{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "COMPLETED",
  "paidAmount": 785.25,
  "refundAmount": 50.75,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "892365417",
  "createdAt": "2025-04-12T09:23:45.612Z",
  "updatedAt": "2025-04-12T09:25:18.743Z",
  "signatureHash": "9a2b8c4d6e3f1a5b7c9d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  }
}
```

```json Failed theme={null}
{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "FAILED",
  "paidAmount": 785.25,
  "refundAmount": 50.75,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "892365417",
  "createdAt": "2025-04-12T09:23:45.612Z",
  "updatedAt": "2025-04-12T09:25:18.743Z",
  "errorMessage": "The customer’s bank rejected the refund. Please try again.",
  "signatureHash": "9a2b8c4d6e3f1a5b7c9d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  }
}
```

```json Cancelled theme={null}
{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "CANCELLED",
  "paidAmount": 785.25,
  "refundAmount": 50.75,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "892365417",
  "createdAt": "2025-04-12T09:23:45.612Z",
  "updatedAt": "2025-04-12T09:25:18.743Z",
  "signatureHash": "9a2b8c4d6e3f1a5b7c9d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  }
}
```

> [!NOTE]
>
> For V1 signing, `signatureHash` is computed from `orderId` and `refundId` — see the [V1 Signing guide](https://docs.paywithatoa.com/api-reference/webhook/v1-signing.md). With [V2 signing](https://docs.paywithatoa.com/api-reference/webhook/v2-signing.md) enabled, `signatureHash` is removed and replaced by the `X-Atoa-Signature` header.

> [!NOTE]
>
> Only present when metadata was supplied on the refund. See [Initiate Refund](https://docs.paywithatoa.com/api-reference/refund/initiate-refund.md) for the field limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.