payment.failed
Triggered when an automatic card charge for an invoice is refused — declined, or the bank asks the customer to confirm it.
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 payment.failed.
triggered_at*stringWhen the event was triggered (ISO 8601).
date-timedata*The customer, the refused charge, and the invoice it was for.
Answer any 2xx within 5 seconds; the body is ignored. Anything else counts as failed and is retried.
{ "id": "evt_d89d1054e5e76d216375a3be437191dd", "event_type": "payment.failed", "triggered_at": "2026-11-01T00:00:06.920Z", "data": { "customer": { "id": "cus_abc123", "name": "Acme Corp" }, "payment": { "amount": 118, "currency_code": "usd", "display_amount": 118, "display_currency_code": "usd", "method": "STRIPE", "automatic": true, "failure_message": "Your card was declined." }, "invoice": { "id": "inv_def456", "number": "INV-0042" }, "item": null }}{ "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd", "X-Clocknext-Event-Id": "evt_d89d1054e5e76d216375a3be437191dd", "X-Clocknext-Event-Type": "payment.failed"}Types
Every object type on this page, with its fields.
PaymentFailedEvent
| 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 payment.failed. |
triggered_at | string | yes | When the event was triggered (ISO 8601). |
data | PaymentFailedData | yes | The customer, the refused charge, and the invoice it was for. |
PaymentFailedData
The data object of a payment.failed event: the customer, the automatic charge that was refused, and the invoice it was for.
| Field | Type | Required | Description |
|---|---|---|---|
customer | WebhookCustomer | yes | The customer the event is about. |
payment | object | yes | The automatic charge that was refused. |
invoice | WebhookInvoiceRef | yes | The invoice the payment is for. |
item | null | yes | Always null — only invoice charges trigger this event. |
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. |
PaymentFailedData.payment
The automatic charge that was refused.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | yes | The amount that was charged, in USD. |
currency_code | string | yes | Always usd — amount is in USD. |
display_amount | number | yes | The same as amount, in USD (Clocknext converts no money). |
display_currency_code | string | yes | Always usd. |
method | "STRIPE" | "PADDLE" | yes | The payment gateway that refused the charge. |
automatic | boolean | yes | Always true — only automatic charges trigger this event. |
failure_message | string | yes | The payment gateway's reason, as it gave it. |
WebhookInvoiceRef
The invoice the payment is for.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
number | string | yes | The invoice's number. |
payment.succeeded POST
Triggered when money arrives — an invoice is paid, or the customer buys something in the customer portal.
credit_note.created POST
Triggered when a credit note is issued on an invoice: by hand, through the API, by a cancel with a refund, or by a plan change. When `invoice.credit_notes_amount` equals `invoice.amount`, the invoice is credited in full.