Skip to documentationDocumentation
On this page

invoice.overpaid

Invoice received more than the requested amount.

The invoice's cumulative accepted amount exceeds its requested amount beyond the overpayment tolerance. The current classification threshold is strictly more than 0.1% above the requested total.

Money and processing#

GET the invoice and fulfill the order once. Handle the excess according to your business policy; a refund is a separate operation.

amount_paid is the cumulative gross total, while gross/fee/net describe the payment just accepted. Do not add this event to a late-payment event for the same acceptance.

Schema version 1#

Fields are taken from the public OpenAPI contract. Required nullable fields must be present and may contain null.

  • id · string · Required

    Stable event UUID for merchant-side idempotency. · Format: uuid

  • event_seq · integer · Required

    Global event sequence. Gaps are possible; it does not establish delivery or processing order. · Format: int64

  • type · "invoice.overpaid" · Required

    —

  • schema_version · 1 · Required

    —

  • environment · "live" | "test" · Required

    —

  • merchant_id · string · Required

    Format: uuid

  • subject_type · "invoice" · Required

    —

  • subject_id · string · Required

    Format: uuid

  • occurred_at · string · Required

    Canonical business occurrence timestamp. · Format: date-time

  • data · object · Required

    Amounts except reversed_amount are denominated in the invoice's currency and network; reversed_amount uses reversed_currency and reversed_network. For a recovered payment in another asset, gross_amount, fee_total and net_amount are frozen invoice-equivalent values, not an exchange or a balance credit in that asset. Read the invoice payments and their settlement for actual payment and credited amounts. · Unknown properties are rejected

  • data.invoice_id · string · Required

    Format: uuid

  • data.external_id · string | null · Required

    —

  • data.currency · string · Required

    —

  • data.network · string · Required

    —

  • data.environment · "live" | "test" · Required

    —

  • data.amount_requested · string · Required

    Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.amount_paid · string · Required

    Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.status · "overpaid" · Required

    —

  • data.paid_at · string · Required

    Format: date-time

  • data.gross_amount · string · Required

    Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.fee_total · string · Required

    Charges withheld from this payment, expressed in invoice units — service fee, payer-priced conversion spread and recovery fee. Platform-paid service fees are excluded. gross_amount − fee_total = net_amount. · Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.net_amount · string · Required

    Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.reversed_amount · string · Optional

    Format: decimal · Pattern: ^\d+(.\d+)?$

  • data.reversed_currency · string · Optional

    —

  • data.reversed_network · string · Optional

    —

Example — version 1#

json example
{
  "id": "00000000-0000-0000-0000-000000000001",
  "event_seq": 184203,
  "type": "invoice.overpaid",
  "schema_version": 1,
  "environment": "live",
  "merchant_id": "00000000-0000-0000-0000-000000000002",
  "subject_type": "invoice",
  "subject_id": "00000000-0000-0000-0000-000000000003",
  "occurred_at": "2026-09-14T10:00:00Z",
  "data": {
    "invoice_id": "00000000-0000-0000-0000-000000000003",
    "external_id": null,
    "currency": "USDC",
    "network": "ethereum",
    "environment": "live",
    "amount_requested": "25.00",
    "amount_paid": "26.00",
    "status": "overpaid",
    "paid_at": "2026-09-14T10:00:00Z",
    "gross_amount": "26.00",
    "fee_total": "0.26",
    "net_amount": "25.74"
  }
}

See delivery and envelope, signature verification, and business processes.