Payment Requests and Invoices
Request payments from one person, a group, or anyone. Track separate shares, installments, partial payments, and reusable payment links.
An invoice groups payment obligations in one collection. Each obligation specifies who can pay, the recipients and amounts, and when payment is allowed. Payment moves directly from the signing payer to the recipients in the same transaction. Creating an invoice does not authorize a future debit.
The Standards reference explains every invoice variant and its tracking model. Agents can generate editable terms with bb build payment-request-v2 --list-examples and follow Main-Wallet Payment Requests to ask the human to sign each exact payment.
Choose the payment model
| Need | Model | Completion |
|---|---|---|
| Bill one person | One obligation restricted to that address | That obligation is paid |
| Let anyone settle a bill | One obligation open to anyone | The first successful payment |
| Let any member of a group settle a bill | One obligation with a fixed address list | One eligible member pays |
| Collect from everyone | One obligation per person, with equal or custom shares | Every obligation is paid |
| Collect from K distinct members | One obligation with a payment count and a per-address limit | K eligible addresses have each paid |
| Collect installments | Separate obligations with their own amounts and payment windows | Every installment is paid |
| Accept partial payments or a shared target | An obligation with an integer payment quantum and cumulative target | The target is reached |
| Accept repeat payments | A reusable payment link | Each payment is tracked; the link does not become globally paid |
| Renew access or membership | Subscriptions | Each authorized period is tracked by the subscription standard |
| Hold funds until approval, or allow refunds | Smart token escrow or Bounties | Release and refund use the escrow's balance and approval rules |
For an all-of-group invoice, Alice's payment settles Alice's obligation. It does not settle Bob's share. A shared target instead lets eligible contributors collectively fill one amount. These are different agreements even when their headline totals match.
The new direct-payment standards are PaymentRequestV2 for finite invoices and PaymentLinkV1 for reusable links. Existing PaymentRequest collections retain their original interpretation; creating a new invoice does not migrate an existing collection.
Amounts and recipient splits
Each obligation has one or more payouts. The chain executes all payouts atomically: it does not mark a payment complete after paying only one recipient. Different denoms remain separate amounts; a client must not add BADGE and USDC into one total or imply an exchange rate.
SDK payout amounts are integer strings in base units. Display forms convert the selected asset's decimals before building the transaction. For partial payments, each payout specifies the amount per payment quantum; every payout scales by the same positive integer multiplier. A 60/40 split can use a quantum of 60 and 40 base units. It cannot accept a contribution that requires fractional base units or silently round the split.
An overall approval amount caps the cumulative number of quanta. The per-transaction scaling limit alone does not cap the invoice total. Payments beyond the remaining target fail instead of becoming an accidental tip. A payer may still need to refresh and retry if another payer settles the remaining amount first.
Dates and state
A payment window has a start and an inclusive end. Before the start, that obligation is scheduled. After the end, further payment is disallowed. An optional due date communicates when payment is expected; it does not close the payment window.
Track progress and lifecycle separately. An expired invoice can have completed shares or a partial contribution. Expiry does not undo earlier payments, and a paid invoice does not become unpaid after its deadline. A reusable link tracks payment activity while remaining open until its cutoff.
The indexer resolves the configured tracker for each obligation using the collection, approval level, approval owner, approval ID, tracker ID, tracker type, and tracked address. Two approvals with the same tracker ID do not share a counter: the approval ID is part of the key. Missing or failed tracking reads must be presented as unavailable, not as evidence that nothing has been paid.
Frozen terms and consent
Payer lists, payout amounts, destinations, limits, and windows are frozen when the collection is created. A named group uses an embedded address list rather than a mutable external roster. For K-of-N payments, the chain enforces both the overall count and the per-initiator count; repeated payments from one wallet cannot count as several distinct addresses. One person can control multiple wallets, so this does not prove unique human identities.
Direct payments settle immediately. A cancel or refund label cannot reverse a bank transfer or disable an independent approval. The legacy specific-payer PaymentRequest deny action records refusal; its separate counter does not make the pay approval unexecutable. New direct-payment invoices do not offer that marker as cancellation.
Use the existing subscription standard for recurring consent and access periods. Use an escrow standard when deposits must remain held, release requires approval, or contributors need enforceable refund rights. Scheduled invoice installments alone do not certify completion of work or authorize automatic withdrawals.
Build and integrate
The SDK exposes buildPaymentRequestV2, validatePaymentRequestV2Collection, extractPaymentRequestV2Details, and buildPaymentRequestV2PayMsg. Use the same validated terms for creation, display, parsing, and transaction review. A standard marker or metadata label alone is not proof that the approvals enforce those terms.
Before signing, review the obligation, actual payer, every recipient and denom, payment units, and deadline. Keep transaction receipts separate from the invoice's aggregate progress so repeated link payments remain individually identifiable.