payment.failed
Generated from COPE public event contracts. Do not edit this page by hand.Use this event to handle failed sale attempts, renewal failures, or buyer recovery workflows.
Delivery Contract
| Field | Value |
|---|---|
| Encoding | CloudEvents 1.0 structured JSON |
| Delivery | At least once |
| Idempotency | Use the CloudEvents source + id tuple, or COPE idempotency_key when available. |
| Source | cope.payment |
| Subject pattern | payment:<identifier> |
| Category | Payments |
| Availability | Available in the public webhook reference. |
| Schema title | payment.failed v1 payload |
| Schema ID | https://schemas.cope.com/events/payment.failed/v1 |
Payload Fields
| Field | Required | Type | Allowed Values | Description | |
|---|---|---|---|---|---|
additional_recipients | no | array | - | Optional. Additional recipient email addresses configured in the vendor’s notification settings. Each recipient receives an individually addressed copy of the notification email. | |
amount_cents | yes | integer | - | - | |
business_name | no | `string | null` | - | - |
buyer | no | object | - | Buyer identity block. Additional fields may appear without a schema version bump; treat email as nullable. | |
checkout_id | no | `string | null` | - | - |
currency | yes | string | - | - | |
decline_code | no | `string | null` | - | Optional decline reason from the acquirer (e.g. Stripe outcome.reason). |
event_type | yes | const | payment.failed | - | |
failed_at | yes | string | - | - | |
failure_code | yes | string | - | - | |
failure_message | yes | string | - | - | |
is_recurring | no | boolean | - | True when the failure is against a recurring subscription charge (vs first-attempt checkout). Lets the buyer-facing template select copy and lets vendor CC filters reason about renewal vs new-sale failures. | |
metadata | no | object | - | - | |
occurred_at | yes | string | - | - | |
order_overview_url | no | `string | null` | - | URL the buyer can visit to retry payment. Rendered as the primary CTA in the payment-failed email template. |
processor | no | string | - | - | |
processor_payment_ref | no | `string | null` | - | - |
product_name | no | `string | null` | - | - |
schema_version | yes | const | 1.0 | - | |
supply_classification | no | string | - | Whether the underlying sale is an electronically supplied service (“ess”) or not (“non_ess”), decided by cart from the products on the payment: non_ess only when EVERY line is. It determines which document the buyer is owed — COPE is deemed supplier for an ESS sale and issues an invoice and credit note; for a non-ESS sale it is a payment agent and issues a payment confirmation and refund receipt. Absent means a producer that predates the field; consumers fall back to the invoice rather than silently downgrading a document. Deliberately not an enum so a new classification cannot reject events against an older schema. |
Example CloudEvent
{
"data": {
"amount_cents": 1000,
"currency": "EUR",
"event_type": "payment.failed",
"failed_at": "2026-05-05T12:00:00.000Z",
"failure_code": "example_failure_code",
"failure_message": "example_failure_message",
"occurred_at": "2026-05-05T12:00:00.000Z",
"schema_version": "1.0"
},
"datacontenttype": "application/json",
"dataschema": "https://schemas.cope.com/events/payment.failed/v1",
"id": "payment.failed:example",
"idempotency_key": "payment.failed:example",
"source": "cope.payment",
"specversion": "1.0",
"subject": "payment:example",
"time": "2026-05-05T12:00:00.000Z",
"type": "payment.failed"
}