Payments — Rivet API

Payments are live here

These reads are live on this environment, with a key holding payments:read. They are scoped to your organization and project exactly what the app projects for you.

Payment context

The rollups the dashboard is built from: counts and totals by status, from both sides.

Payment context

From the live spec

curl "https://api.rivet.network/v1/payments/context?since=2026-08-01" \
  -H "Authorization: Bearer rk_live_…"

PaymentsContext
Field	Type	Notes
payable*	Rollup	What this organization owes — invoices it received (its bills).
receivable*	Rollup	What this organization is owed — invoices it issued.
window*	object
payment_methods*	object

payable — what you owe: invoices you received.
receivable — what you are owed: invoices you issued.
outstanding — always present in both, summing every unpaid status. A status bucket with no documents is absent rather than zero, so read defensively.

The optional window applies per status to the date that matters for it: the document date for open statuses, the due date for due and overdue, the scheduled date for payment_scheduled, the paid date for paid. That is why a month’s window can move a document between buckets rather than dropping it.

Payment methods

From the live spec

curl "https://api.rivet.network/v1/payment-methods" \
  -H "Authorization: Bearer rk_live_…"

PaymentMethod
Field	Type	Notes
id*	string	A Rivet resource id.
type*	string \| null	bank_account · card · wire · check · lender · null
bank_name*	string \| null
last4*	string \| null
verification_status*	string \| null	pending · verified · failed · null

A bank name, the last four digits, and a verification status. That is all there is — deliberately.

The API returns a documented subset of what the app itself holds, never a wider one. Account and routing numbers are not omitted from this endpoint because we forgot them; they are not in the projection at all, so no key, no scope and no bug can return them. An integration that cannot leak a bank account is a better integration to hand your customers.

Making a payment

Payments are document-anchored: you pay a bill, you collect on an invoice — with your network counterparties. There is no standalone “send money” call. POST /v1/documents/{id}/pay schedules the document's full balance due on the fiat rail (partial amounts aren't accepted), needs payments:write, and takes an Idempotency-Key like every write. The same move is available as a transition to payment_scheduled — /pay is the one-call form.

Pay a bill

From the published contract

curl -X POST "https://api.rivet.network/v1/documents/{documentId}/pay" \
  -H "Authorization: Bearer rk_live_…" \
  -H "Idempotency-Key: pay-inv-0042-2026-09-03"

Sandbox: simulated. The document settles in place — no money moves — so the whole lifecycle is practicable end to end.
Live: on the real rail, once your organization's payment processor is connected (capability_unavailable until then).
Per-key limits, set at mint. A key can carry payment_limits — max_per_payment and daily_volume. Exceeding either answers payment_limit_exceeded naming which limit and the numbers, and a refused payment never consumes daily volume.
Idempotent across the async gap. Replaying a confirmed pay returns the original response with Idempotent-Replay: true — never a second payment, even after settlement.
The document is the status surface. A scheduled payment settles (paid) or fails (the document reverts to payable). Read the document, or subscribe to payment.settled / payment.failed on webhooks — failures carry the reason.

Paying an invoice as an agent

An invoice whose payee accepts USDC from agents carries a pay reference — on its PDF and on the payer’s document read as pay_url. Anyone holding it, with no account and no key, can settle that one invoice in USDC on Base through x402: GET the reference for the 402 challenge, sign the authorization, POST it back. Your own key takes the same road with payment_method usdc on POST /v1/documents/{id}/pay. The whole flow, the headers and the refusals are on Pay by agent.