refund.failed
Triggered when the payment gateway fails or rejects a card refund, also after an earlier refund.succeeded. The money goes into the customer's invoice balance: ask for the refund again or tell the customer. status is FAILED or REJECTED_IN_GATEWAY_REVIEW.
X-Clocknext-Signature*stringt=<unix seconds>,v1=<hex HMAC-SHA256> — the HMAC of ${t}.${rawBody} keyed with the endpoint's signing secret. See Verify the signature.
X-Clocknext-Event-Id*stringThe event's id — the same as id in the body, and the same on every retry.
X-Clocknext-Event-Type*stringThe event name — the same as event_type in the body.
application/json- body
id*stringevt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.
event_type*stringAlways refund.failed.
triggered_at*stringWhen the event was triggered (ISO 8601).
date-timedata*The customer, the refund, its invoice and its credit note.
Answer any 2xx within 5 seconds; the body is ignored. Anything else counts as failed and is retried.
{ "id": "evt_01ed6ca855e160c76834eea7671432b3", "event_type": "refund.failed", "triggered_at": "2026-11-16T09:20:04.000Z", "data": { "customer": { "id": "cus_9", "name": "Acme" }, "refund": { "id": "re_1", "status": "FAILED", "gateway": "STRIPE", "gateway_refund_id": "re_3P0abc", "amount": 118, "currency_code": "usd", "charged_amount_minor": 985000, "charged_currency_code": "inr", "reason": "Duplicate charge", "failure_reason": "expired_or_canceled_card", "created_at": "2026-11-16T09:20:01.000Z", "settled_at": "2026-11-16T09:20:04.000Z" }, "invoice": { "id": "inv_42", "number": "INV-0042", "subscription_id": "pur_9" }, "credit_note": { "id": "cn_1", "number": "CN-007" } }}{ "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd", "X-Clocknext-Event-Id": "evt_01ed6ca855e160c76834eea7671432b3", "X-Clocknext-Event-Type": "refund.failed"}Types
Every object type on this page, with its fields.
RefundFailedEvent
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | evt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates. |
event_type | string | yes | Always refund.failed. |
triggered_at | string | yes | When the event was triggered (ISO 8601). |
data | RefundEventData | yes | The customer, the refund, its invoice and its credit note. |
RefundEventData
The data object of a refund.created, refund.succeeded or refund.failed event: the customer, the refund, the invoice whose card payment it refunds, and its credit note.
| Field | Type | Required | Description |
|---|---|---|---|
customer | WebhookCustomer | yes | The customer the event is about. |
refund | WebhookRefund | yes | The refund when the event is triggered. |
invoice | WebhookRefundInvoice | yes | The invoice whose card payment is refunded. |
credit_note | WebhookCreditNoteRef | null | yes | The credit note that asked for the refund. Null for a refund from the invoice balance. |
WebhookCustomer
The customer the event is about.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The customer's Clocknext id. |
name | string | yes | The customer's name. |
WebhookRefund
Money that goes back to a card, for one card payment. amount is in USD; charged_amount_minor is what goes back, in the currency the card was charged in. New values can be added to status and gateway.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The refund's id. |
status | "PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | yes | PENDING_AT_GATEWAY in refund.created, SUCCEEDED in refund.succeeded, else refund.failed. |
gateway | "STRIPE" | "PADDLE" | yes | The payment gateway that refunds the card. |
gateway_refund_id | string | null | yes | The gateway's refund id (Paddle's adjustment id). Always null in refund.created. |
amount | number | yes | This refund's amount, in USD. |
currency_code | string | yes | Always usd — amount is in USD. |
charged_amount_minor | integer | null | yes | What goes back to the card, in minor units of charged_currency_code. Null only on old refunds. |
charged_currency_code | string | null | yes | The currency the card was charged in, lowercase (ISO 4217). Null with charged_amount_minor. |
reason | string | null | yes | The credit note's reason, or the reason given with a refund from the invoice balance. |
failure_reason | string | null | yes | Why it failed, as stored. Null outside refund.failed, and when the gateway gave no reason. |
created_at | string | yes | When the refund was asked of the gateway (ISO 8601). |
settled_at | string | null | yes | When the refund got its last final status (ISO 8601). Null in refund.created. |
WebhookRefundInvoice
The invoice whose card payment is refunded.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
number | string | yes | The invoice's number. |
subscription_id | string | null | yes | The subscription's purchase id. Null when the invoice belongs to no subscription. |
WebhookCreditNoteRef
The credit note that asked for the refund.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The credit note's id. |
number | string | yes | The credit note's number. |
refund.succeeded POST
Triggered when the payment gateway confirms a card refund. Only this event means the money reached the card. A `refund.failed` can still follow if the gateway reverses it later.
Mint a customer-portal access token POST
Returns a short-lived HS256 JWT for the customer portal. A customer not in the key's organisation is reported as `400` here (not `404`); an `organizationId` mismatch is `403`. When your Clocknext plan does not include the Customer portal, every call is `403` `FEATURE_LOCKED`.