> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# payment.failed

> A payment sale has failed.

# 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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.