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

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"
}

Compatibility

Fields may be added within the same major version. Removing or changing the meaning of a documented field requires a new event version.

​payment.failed

​Delivery Contract

​Payload Fields

​Example CloudEvent

​Compatibility

payment.failed

Delivery Contract

Payload Fields

Example CloudEvent

Compatibility