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

{
  "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.