Invoices & checkout
Let a recipient sign a request, share its checkout link, and reconcile confirmed payouts.
Issue a signed request
Signing is off-chain and creates no application signing key. The API checks that the signer is a current merchant FullAccess key. Wallet control does not establish legal identity or KYB approval.
- Open Invoices and import an independently trusted testnet FT policy. Enter the matching API origin.
- Connect a merchant wallet supporting compatible NEP-413 message signing.
- Set the payout account, title/reference, 1–32 fixed-denomination units, and expiry.
- Review and sign. Download the signed JSON and share the checkout link through your own channel.
Keep an encrypted invoice library
On Invoices, connect the merchant wallet and create or unlock Your invoice library with a passphrase of 12–1,024 characters. Saving is explicit: create or open a signed invoice, then choose Save displayed invoice. Up to 100 requests can be kept per merchant/network.
Titles, references, policies and signatures are encrypted in this browser. Search the saved list and open a request to reuse its payment link. The library makes no API requests and stores no paid-status cache; refresh the opened invoice against its matching API for current indexed settlement.
Export an encrypted backup and retain its passphrase separately. Restore requires empty storage; an unlocked library can merge another encrypted backup, including one with a different passphrase. Conflicting signed terms are rejected instead of overwriting an existing ID.
Locking hides the library and an invoice opened from it. Switching merchant accounts closes the previous account’s library. Separately opened public files, shared links and current editor drafts remain readable in their own contexts. Removing a local copy does not cancel a signed invoice or change payment state.
Pay the signed terms
Current merchant ownership, invoice availability and local duplicate-note/unit checks run before and after proving, at public-plan import and again before signatures. Switching units or locking clears private note/proof state; public proving files remain available for the next unit.
Checkout polls public recovery up to ten times, two seconds apart, without signing or resending. An uncertain wallet response remains blocked for reconciliation. Fixed-recipient recovery of already accepted funds remains available after expiry or key rotation.
The CLI/public-plan path remains available with the exact selected unit. Independent concurrent payers can still overpay: deadlines and unit caps are application rules, not contract reservations. A prompt already handed to an external wallet can settle late.
- Open the request and review its recipient, asset, principal, fees and deadline.
- Independently import the trusted testnet FT policy and verify the matching API/current merchant key. Connect the fee payer wallet and unlock your encrypted journal.
- Select Payment unit, open an original-group encrypted note with its passphrase and select a payout vault. Import the reviewed proving files and independently obtained artifact-manifest SHA-256 under Trusted proving files.
- Choose Generate invoice proof. The disposable local worker verifies assets, rebuilds the tree and proves the signed recipient and selected unit reference. Cancel proof stops the job without importing or paying.
- Choose Review amount & fees. Check full principal, the additive 0.15% withdrawal fee in token atomic units and separate NEAR costs. Approve each prerequisite and payment in the wallet individually.
- Wait for the bound finalized withdrawal confirmation; invoice totals are indexed separately. Select a different funded note for each remaining unit and retain encrypted backups through reconciliation.
A distinct reference per payment unit
Terms v2 contain one signed random nonce per unit, deriving a separate disclosure reference for each payment. Legacy v1 requests retain their original common reference.
Checkout rejects references already observed as paid. This is an indexed application guard, not an on-chain reservation. Concurrent payers or index lag can still cause reuse or overpayment; actual payouts remain counted.
An arbitrary Evidence receipt root cannot replace a signed invoice unit reference. Checkout and reconciliation require the signed-derived root as the withdrawal disclosureRoot. Attaching arbitrary receipt evidence to the same action needs a separately designed/versioned combined commitment.
npm run cli -- invoice-action trusted-policy.json \
signed-invoice.json invoice-action.json 1
npm run cli -- shared-spend-args trusted-policy.json \
https://rpc.testnet.near.org encrypted-note.json \
invoice-action.json public-payment.jsonRead the settlement state
| State | Meaning at the index checkpoint |
|---|---|
| Awaiting / partial | No confirmed principal, or only part of the requested principal. |
| Paid / paid late | Exactly the requested principal, with timing distinguished by finalized records. |
| Overpaid | Excess principal requiring merchant reconciliation. |
| Expired / partial expired | The deadline has passed with an outstanding balance. |
| Review required | The known journal or bounded confirmation scan is incomplete. |
Sharing, retention, and recovery
Terms remain client-held. Link/JSON holders can read the business terms and derive its references. A fragment is omitted from the initial page URL request; page code, extensions, and link holders can still read it. Hosting access controls apply to shared checkout links.
Save the signed invoice before leaving. The public settlement API does not store invoice terms or send webhooks. The separate Organization API can store signed invoices with organization access controls, idempotency and encryption at rest; the local form does not automatically sync to it. Use Organization → Invoice payments to explicitly import signed JSON, search saved invoices and reconcile payments. Expiry is an application rule; contracts may settle late. Recovery keeps the original payout destination after expiry.
Prepare the receiving account
Use Check recipient on the invoice form before signing, or in checkout after independently importing the trusted policy and verifying its API. Prepared withdrawals also offer this check for their bound recipient. No wallet connection is needed for this read-only lookup.
Account activation, token registration and payment review are separate steps. A pre-registered token record does not activate a missing account. Activate the exact account with a compatible NEAR wallet, then refresh. The app does not estimate an account-creation amount or send a funding transfer.
For an existing, unregistered account, inspect the public storage_deposit call and exact token storage minimum read at the checked final block. The payment session presents registration separately for wallet approval; gas and protocol fees remain separate.
Ready for payment review is a snapshot of account existence and registration. It does not establish ownership, available gas, payer balance, vault liquidity or payment completion. Changing recipient, policy or API invalidates the result; failed refreshes clear previous readiness.
Track your organization’s payments
For persisted team records, open Organization → Invoice payments and explicitly save signed JSON. Search/filter the complete saved snapshot, verify finalized-index observations against an independently trusted Settlement API/policy and export all filtered rows as CSV or JSON. The optional local encrypted library stays separate.
The dashboard shows finalized successful payments with index block/time and linked transaction details. Unchecked, unavailable, stale, incomplete and reused-reference cases remain explicit. Exported status is an indexed snapshot, not current-chain freshness, complete business history or tax acceptance.