> ## Documentation Index > Fetch the complete documentation index at: https://docs.staging.cope-demo.com/llms.txt > Use this file to discover all available pages before exploring further. # payment.dispute.opened > A payment dispute has opened. # payment.dispute.opened > Generated from COPE public event contracts. Do not edit this page by hand. Use this event to pause risky fulfillment, alert operators, or start dispute evidence 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 | `dispute:` | | Category | Disputes | | Availability | Available in the public webhook reference. | | Schema title | payment.dispute.opened v1 payload | | Schema ID | `https://schemas.cope.com/events/payment.dispute.opened/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. Capped at 5 recipients. | | | `business` | yes | `object` | - | The business that sold the disputed order. `owner_email` is the email address of the account that owns the business, which COPE notifies when a dispute opens; it is null when the account has none on record, and events sent before it shipped omit it. | | | `buyer` | yes | `object` | - | The buyer as the checkout captured them. `locale` is the checkout's language; `communication_locale` is the language to address them in: the one their account chose, else the checkout's. | | | `currency` | no | `string` | - | - | | | `dispute` | no | `object` | - | Optional. The dispute itself, as the payment processor reported it when it opened. The rest of this payload describes the sale that is disputed, so `totals` is the sale's amount, while `dispute.amount_cents` and `dispute.currency` are the amount in dispute, which can be smaller. `reason` is the processor's reason code verbatim, `evidence_due_by` the deadline for contesting the dispute, and `fee_cents` the dispute fee charged to the business as a non-negative amount; each of those three is null when the processor has not reported it. Events sent before this field shipped omit it. | | | `event_type` | yes | `const` | `payment.dispute.opened` | - | | | `first_click_ref` | no | \`string | null\` | - | Raw, unvalidated affiliate reference captured from the inbound `?aff=` parameter. It is not a resolved or validated affiliate ID; COPE resolves and validates attribution downstream. | | `line_items` | yes | `array` | - | - | | | `occurred_at` | yes | `string` | - | - | | | `order` | yes | `object` | - | The order this payment is for. `order.metadata` is the metadata you attached to the cart, returned so you can reconcile the payment against your own system. | | | `order_overview_url` | no | `string` | - | - | | | `payment` | no | `object` | - | - | | | `payment_chunk` | no | `object` | - | The payment chunk this event concerns. Carries `object` (what it is) and `id` (which one); `id` is the public identifier a merchant addresses it by. | | | `payment_method` | yes | \`object | null\` | - | - | | `phone_offer_id` | no | \`string | null\` | - | Phone offer identifier associated with this sale, if any. Raw attribution signal only. | | `promo` | yes | \`object | null\` | - | - | | `promo_code` | no | \`string | null\` | - | Promo code applied to this sale, if any. Raw attribution signal only. | | `rail` | no | `string` | - | - | | | `schema_version` | yes | `const` | `1.5` | - | | | `seller_vat_info` | no | \`object | null\` | - | Seller identity used for invoicing when the creator is the VAT-liable party. Null when COPE is the VAT-liable party. | | `source_event_id` | no | `string` | - | - | | | `source_event_type` | no | `const` | `payment.dispute.opened` | - | | | `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. | | | `totals` | yes | `object` | - | - | | | `vat_mode` | no | `string` | `cope_vat`, `creator_vat` | Which party is liable for VAT on this sale: COPE (`cope_vat`) or the creator (`creator_vat`). | | | `vat_responsibility` | no | `string` | `cope`, `creator` | Which party remits VAT to the tax authority. | | ## Example CloudEvent ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "data": { "business": {}, "buyer": {}, "event_type": "payment.dispute.opened", "line_items": [ { "amounts": { "gross_cents": 1000, "net_cents": 1000, "tax_cents": 1000, "tax_percentage": 19 }, "is_trial": true, "payment_number": 1000, "product": {}, "quantity": 1000 } ], "occurred_at": "2026-05-05T12:00:00.000Z", "order": { "created_at": "2026-05-05T12:00:00.000Z", "currency": "EUR", "source": "example_source" }, "payment_method": {}, "promo": {}, "schema_version": "1.5", "totals": { "product": { "gross_cents": 1000, "net_cents": 1000, "tax_cents": 1000 }, "total": { "gross_cents": 1000, "net_cents": 1000, "tax_cents": 1000 } } }, "datacontenttype": "application/json", "dataschema": "https://schemas.cope.com/events/payment.dispute.opened/v1", "id": "payment.dispute.opened:example", "idempotency_key": "payment.dispute.opened:example", "source": "cope.payment", "specversion": "1.0", "subject": "dispute:example", "time": "2026-05-05T12:00:00.000Z", "type": "payment.dispute.opened" } ``` ## Compatibility Fields may be added within the same major version. Removing or changing the meaning of a documented field requires a new event version.