Webhook event

`order.overpaid`

More than the price arrived (beyond the over-tolerance), at first payment or by a later duplicate. Do not fulfil on this event: order.paid is the fulfilment event and was or is sent as well. This one tells you there is an excess in the merchant wallet to refund or keep as credit.

Type: order.overpaid
The object it carries: the order object
Subscribe with: order.overpaid, order.* or *

Example payload

The body of the request your endpoint receives, shown here over several lines. On the wire it is compact JSON; check its signature over the bytes exactly as they arrive.

Example payload

{
  "id": "evt_kppvr6csnhzt76aj77y71zv7",
  "object": "event",
  "livemode": true,
  "created": "2026-10-11T14:09:55.764Z",
  "type": "order.overpaid",
  "api_version": "2026-10-11",
  "data": {
    "object": {
      "id": "ord_0zymngngvf12b8b2cra7tb8e",
      "object": "order",
      "livemode": true,
      "created": "2026-10-11T14:03:22.418Z",
      "updated": "2026-10-11T14:09:55.764Z",
      "status": "overpaid",
      "source": "checkout",
      "amount": "21.99",
      "currency": "USD",
      "value": {
        "amount": "21.99",
        "currency": "USD"
      },
      "fx": null,
      "description": "Order #1042",
      "reference": "1042",
      "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
      "customer_email": "jane@example.com",
      "line_items": [
        {
          "name": "Ethiopia Yirgacheffe, 1 kg",
          "quantity": 1,
          "unit_amount": "21.99",
          "amount": "21.99",
          "price": "price_mbk5s5r45kwheaq89dbmk2gz"
        }
      ],
      "settlement": {
        "mode": "convert",
        "asset": "base:usdc",
        "amount_expected": "21.990000",
        "amount_received": "25.000000",
        "wallet": "wal_bsfw07hymawmda7gg8jsyy3g"
      },
      "fee_bearer": "payer",
      "amount_paid": "25.00",
      "amount_due": "0.00",
      "amount_refunded": "0.00",
      "paid_late": false,
      "accepted_short": false,
      "refunded": false,
      "partially_refunded": false,
      "finalized": true,
      "has_unconfirmed": false,
      "screening_hold": false,
      "provider_refund_received": false,
      "overpayment": {
        "amount": "3.01",
        "currency": "USD",
        "asset": "base:usdc",
        "asset_amount": "3.010000",
        "resolution": null
      },
      "rails_allowed": [
        "orrerie_app",
        "relay",
        "direct"
      ],
      "accept": [],
      "app_pay_allowed": true,
      "active_instruction": null,
      "instructions": [
        "pin_h73hkjr8dyp4zymaet5e2gbv"
      ],
      "payments": [
        "pay_2pe50hae6w2jk4sp1rcq5pae"
      ],
      "checkout_session": "cs_z7ek5wj68fyz80j7bz1eq4e0",
      "payment_link": null,
      "invoice": null,
      "subscription": null,
      "pos_device": null,
      "receipt": "rcpt_ppaxx20nbqv0kqgkwcxcc5xh",
      "expires_at": "2026-10-11T15:03:22.418Z",
      "paid_at": "2026-10-11T14:09:55.764Z",
      "cancelled_at": null,
      "metadata": {
        "cart_id": "c_7781"
      },
      "screening": {
        "status": "clear"
      }
    },
    "previous_attributes": {
      "status": "processing",
      "amount_paid": "0.00",
      "amount_due": "21.99",
      "overpayment": null
    }
  },
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "pending_webhooks": 1
}

Fields of data.object

Fields of data.object in order.overpaid
Field	In this example
`id`	`"ord_0zymngngvf12b8b2cra7tb8e"`
`object`	`"order"`
`livemode`	`true`
`created`	`"2026-10-11T14:03:22.418Z"`
`updated`	`"2026-10-11T14:09:55.764Z"`
`status`	`"overpaid"`
`source`	`"checkout"`
`amount`	`"21.99"`
`currency`	`"USD"`
`value`	An object with `amount`, `currency`
`fx`	`null`
`description`	`"Order #1042"`
`reference`	`"1042"`
`customer`	`"cus_8ea07c40qsvv19f7rgmeb8ha"`
`customer_email`	`"jane@example.com"`
`line_items`	A list of 1 item
`settlement`	An object with `mode`, `asset`, `amount_expected`, `amount_received`, `wallet`
`fee_bearer`	`"payer"`
`amount_paid`	`"25.00"`
`amount_due`	`"0.00"`
`amount_refunded`	`"0.00"`
`paid_late`	`false`
`accepted_short`	`false`
`refunded`	`false`
`partially_refunded`	`false`
`finalized`	`true`
`has_unconfirmed`	`false`
`screening_hold`	`false`
`provider_refund_received`	`false`
`overpayment`	An object with `amount`, `currency`, `asset`, `asset_amount`, `resolution`
`rails_allowed`	A list of 3 items
`accept`	A list of 0 items
`app_pay_allowed`	`true`
`active_instruction`	`null`
`instructions`	A list of 1 item
`payments`	A list of 1 item
`checkout_session`	`"cs_z7ek5wj68fyz80j7bz1eq4e0"`
`payment_link`	`null`
`invoice`	`null`
`subscription`	`null`
`pos_device`	`null`
`receipt`	`"rcpt_ppaxx20nbqv0kqgkwcxcc5xh"`
`expires_at`	`"2026-10-11T15:03:22.418Z"`
`paid_at`	`"2026-10-11T14:09:55.764Z"`
`cancelled_at`	`null`
`metadata`	An object with `cart_id`
`screening`	An object with `status`

What each field means is on the page of the order object. data.previous_attributes holds the old values of exactly the fields that changed: here status, amount_paid, amount_due, overpayment.

Endpoints behind it

Calls that change orders. An event is also sent when a payer, the network, a timer or a person in the dashboard causes the change; the sentence above says which.