Skip to documentationDocumentation
On this page

invoice.underpaid

The invoice closed with less than the requested amount accepted.

The invoice closed after only part of its amount was accepted: the payment window ended, or a timely payment could not be accepted. In the second case it can close before its deadline.

Money and processing#

This closes the invoice. The payload has cumulative amount_paid and the deadline, but no gross/fee/net increment. Usually earlier acceptance events already described the received payments and this event is not a new credit. When the invoice's last timely payment is accepted as the invoice closes, this event is the only one for that acceptance: retrieve the invoice and reconcile amount_paid and payments[] instead of relying on earlier events.

Apply your incomplete-order policy and do not fulfill automatically. A closed underpaid invoice with accepted funds is eligible for a refund within its remaining accepted-gross amount. Read the current invoice and refund rules before creating one.

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.underpaid" · 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

    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 · "underpaid" · Required

    —

  • data.expires_at · string · Required

    Format: date-time

Example — version 1#

json example
{
  "id": "00000000-0000-0000-0000-000000000001",
  "event_seq": 184203,
  "type": "invoice.underpaid",
  "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": "10.00",
    "status": "underpaid",
    "expires_at": "2026-09-14T10:00:00Z"
  }
}

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