Invoice Payments

Invoice Payments track individual payment transactions toward invoices. Each payment is recorded with its amount, status, network, asset, and transaction hash.

Payment Lifecycle

Payments progress through statuses:

PENDING → SETTLED
    ↓
FAILED / CANCELLED

PENDING: Payment initiated, awaiting confirmation
SETTLED: Payment confirmed on-chain, invoice balance updated
FAILED: Payment failed (network error, insufficient funds, etc.)
CANCELLED: Payment was cancelled before settlement

Payment Fields

amount: Payment amount
currency: Currency/asset (e.g., "USDC")
network: Blockchain network (e.g., "base-mainnet")
asset: Token identifier (e.g., "USDC")
tx_hash: Transaction hash on the blockchain
status: Payment status
external_ref: Reference linking to invoice and x402 (format: inv:{invoice_id}:pay:{payment_id})

Multiple Payments per Invoice

Invoices support multiple payments:

Each payment is tracked separately
Invoice balance = sum of SETTLED payments
Remaining amount = invoice amount - total paid
Status updates: sent → partially_paid → paid

Viewing Payments

Via Dashboard

Navigate to Collections → Payments to see all invoice payments.

Via API

GET /v1/invoices/{invoice_id}/payments

Returns all payments for an invoice, ordered by creation date.