Payment Requests

A Payment Request is a single receivable for one customer or counterparty. Unlike a reusable Payment Link, it has an exact balance, immutable finalized terms, a due date, and an allocation history across every payment attempt.

Lifecycle

draft → open → paid
          ├─→ canceled
          └─→ expired

draft can be edited and has no public payment URL.
open has locked terms and accepts payment through its public URL.
paid is reached only after confirmed funds are atomically allocated.
canceled and expired stop new collection attempts but preserve the audit trail.

Finalization is intentionally separate from creation. Review the draft before locking its amount, line items, supported tokens, due date, and branding snapshot.

Resource relationships

One Payment Request may create multiple historical Checkout Sessions and payment attempts. The payment_request_payments allocation ledger maps each PaymentIntent to the receivable and records the requested, received, applied, and unapplied amounts. Only one attempt may actively collect funds at a time; another browser may safely resume it.

Merchant endpoints

Method	Endpoint	Purpose
`POST`	`/api/v1/payment_requests`	Create a draft.
`GET`	`/api/v1/payment_requests`	List account-scoped requests.
`GET`	`/api/v1/payment_requests/:id`	Retrieve one request.
`PATCH`	`/api/v1/payment_requests/:id`	Edit a draft.
`POST`	`/api/v1/payment_requests/:id/finalize`	Lock terms and create the public URL.
`POST`	`/api/v1/payment_requests/:id/send`	Schedule email and an optional reminder.
`POST`	`/api/v1/payment_requests/:id/cancel`	Cancel an unpaid request.
`GET`	`/api/v1/payment_requests/:id/payments`	Inspect allocation attempts.
`GET`	`/api/v1/payment_requests/:id/deliveries`	Inspect email delivery attempts.
`GET`	`/api/v1/payment_requests/:id/timeline`	Read the combined lifecycle.

Every mutation requires an Idempotency-Key. Resources are isolated by merchant account and by test/live mode.

Payment Request object

Amounts are decimal strings in the request currency. Important fields include:

Field	Description
`amount_total`	Finalized amount due.
`amount_paid`	Confirmed amount allocated to the request.
`amount_remaining`	Balance still payable.
`line_items`	Normalized item snapshot and calculated totals.
`supported_tokens`	Allowed stablecoin/network combinations.
`url`	Public hosted collection URL; null for drafts.
`version`	Snapshot version copied to originating Checkout Sessions.

The API never changes a paid request back to open after a refund. Refunds are a separate funds lifecycle.