> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/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`](/api-reference/Webhook/posPaymentStatusWebhookResponse).

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

<Info>
  **V2 Webhook Signing:** If you have enabled [V2 webhook signing](/api-reference/Webhook/v2-signing), 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.
</Info>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

<Note>
  For V1 signing, `signatureHash` is computed from `orderId` and `refundId` — see the [V1 Signing guide](/api-reference/Webhook/v1-signing). With [V2 signing](/api-reference/Webhook/v2-signing) enabled, `signatureHash` is removed and replaced by the `X-Atoa-Signature` header.
</Note>

<Note>
  Only present when metadata was supplied on the refund. See [Initiate Refund](/api-reference/Refund/initiateRefund) for the field limits.
</Note>