RecurCrypto API 路 Merchant documentation
Recurring payments API for crypto subscriptions
Use RecurCrypto as a recurring payments API for wallet-native subscriptions. Create plans, generate checkout links, read subscriptions, and sync lifecycle events into your product with a minimal merchant integration.
Quick start
- 1. Sign in to the dashboard with your merchant wallet.
- 2. Call
POST /api/v1/auth/keys to generate your merchant API key. - 3. Use that Bearer key to create plans, generate checkout links, and query subscriptions.
- 4. Configure webhooks so your product mirrors on-chain subscription activity.
Documented API v1 focus: Polygon + USDC. Separately, V5 Polygon/Base/Arbitrum checkout routes are localhost-only simulations with zero live networks and no settlement authority.
Local V5 selection: server-verified fixture route
A payer first requests compare_all for a simulated wallet scenario and explicitly chooses one immutable merchant price. The localhost-only selection endpoint independently checks a version 3 selection constraint, a short-lived server-issued comparison proof bound to the authenticated payer, offer bearer, selected price, fixture scenario and Free 0% policy, then the locked merchant price, its server-owned USDC rail allowlist, and deterministic fixture balance, allowance and gas conditions. Missing, expired, tampered or cross-payer comparison proofs fail closed before a child checkout is created. After a local server restart, compare again because the ephemeral proof key is intentionally not persisted. An unavailable route fails before any child checkout is created. This is a local simulation, not proof of funds, a binding gas quote, a signature, or a payment. No hidden bridge or swap is performed. Legacy version 1/2 selection constraints remain supported for historical demonstrations. Free 0% applies during prelaunch; future 1% remains inactive and would require new consent, with gas separate.
Local V5 payer preflight before selecting a price
On localhost only, a signed-in test payer may send POST /api/local/v5/offers/{token} with { "action": "preflight", "planId": "...", "constraints": { "version": 3, "fixtureScenario": "funded", "requireViableRoute": true }, "selectionProof": "..." } after compare_all. The server checks the offer, product status, locked price snapshots, short-lived comparison proof, simulated route availability and optional budget ceilings. A successful response is nonbinding: it does not consume the offer, reserve funds, create a checkout, sign a message, or prove gas availability. The subsequent selection repeats these checks in its own write transaction; the preflight response must never be treated as a payment authorization or receipt. A failed or unreachable preflight prevents the browser from sending the selection write.
This endpoint is not part of the public API v1 or the OpenAPI contract. V5 still has zero live networks and stablecoins. Free 0% remains effective during prelaunch; future 1% requires new consent and is inactive. Gas is separate and simulated.
V5 checkout simulation: an atomic quote is not a payment
The localhost-only V5 prototype locks the payer-bound checkout session and the merchant plan in one serializable database transaction. It then recomputes the cheapest eligible route from server-owned test fixtures, checks the plan version and simulated contract IDs, and stores one immutable quote. A repeated identical request retrieves that quote; a changed scenario cannot silently replace it. This is an implementation detail of the offline prototype, not an enabled public API or a verified blockchain transaction.
- Create a merchant plan and a checkout link on localhost using a signed test session and local PostgreSQL.
- Bind a signed-in test wallet to the link; no payment signature is requested.
- Request a simulated scenario. Polygon, Base and Arbitrum USDC fixtures are evaluated automatically; no network choice, bridge or swap is imposed on the payer.
- Review the amount, gas estimate, Free 0% platform fee and quote expiry. An acknowledgement records a demo decision only, never a charge or a receipt.
All three V5 routes and their tokens are simulated: zero V5 live networks and zero V5 live stablecoins. The future 1% platform fee is inactive, gas is separate, and any future activation requires a new policy and renewed consent. Read the quickstart, recurring payments overview, stablecoin renewal guide and USDC subscription guide.
Choosing a subscription price with simulated route availability
In the localhost-only V5 multi-price demonstration, POST /api/local/v5/offers/{token} with action: compare_all and a supported fixture scenario evaluates every merchant-offered price against simulated USDC routes on Polygon, Base and Arbitrum. The response includes a versioned, nonbinding viability guide with an explicit no-route state. Its 30-day equivalents use integer arithmetic, while the actual upfront plan amount and synthetic first-cycle gas are displayed separately. A low monthly equivalent does not mean the customer can afford an annual charge upfront. The optional 30-day and upfront all-in budget filters use the separate simulated gas estimates without folding gas into the merchant price; if no simulated route fits, the recommendation is empty. In the local payer interface, entering any maximum budget or a billing-period preference requires a verified full-price comparison before continuing; a chosen price that exceeds the stated plan-only or gas-inclusive limits is blocked and a viable alternative can be shown. The final selection also checks a conservative simulated gas ceiling server-side against the immutable price, although neither estimate certifies available funds or constitutes spending authorization. Budget filters never modify the merchant price, switch networks, create quotes or authorize payments: the payer must explicitly select a price and later confirm the demo-only decision.
Newly created local V5 multi-price offers now store an immutable selectionProofRequired policy. A payer must run compare_all and submit both version 3 constraints and the short-lived server-issued comparison proof before a child checkout can be created. A bare planId or legacy version 1/2 constraint cannot downgrade a new offer. Previously stored offers retain their earlier local-demo behavior through a database default of false; existing consent, historical V4 authorizations and price snapshots are not rewritten. The new policy is enforced inside the offer-selection transaction, and a separate database trigger prevents changing it after creation. This local code path has not been certified against PostgreSQL, EVM or a browser. No funds, real networks or tokens are enabled; Free remains 0% prelaunch, future 1% inactive pending explicit renewed consent, with gas separate.
The browser recomputes the ranking from validated offer and route data, rejecting altered fees, prices, expired offers and impossible routes. This is not a payment readiness check for live funds: V5 has zero enabled networks and stablecoins, Free remains 0% during prelaunch, the future 1% fee is inactive pending new consent, and network gas is always separate. The public API v1 and historical V4 authorizations are unchanged.
Recovering an uncertain checkout response without duplicating a write
A lost HTTP response does not prove that a database transaction rolled back. In the local-only V5 demonstration, the payer checks an authenticated read-only snapshot instead of repeating a write: session_status after wallet claim, audit after a quote, status after a demonstration acknowledgement or cancellation, and lifecycle_status after a manual simulated renewal event. A payer-session change returned after COMMIT is also treated as uncertain. The browser preserves the original event key until a definitive outcome has been verified. This procedure neither charges a wallet nor creates a payment receipt.
These recovery operations are not enabled public V5 payment endpoints. The future 1% fee is inactive, Free is 0% during prelaunch, gas is separate, and Polygon, Base and Arbitrum remain simulations. See the existing developer quickstart for the demo-only flow.
Auditing simulated product checkout consent
In the localhost-only V5 merchant sandbox, creating a product checkout offer or rotating an unclaimed offer writes a versioned acknowledgement in the same SQL transaction as the offer. A failed audit write aborts the operation; an idempotent retry returns the original record instead of inventing new acceptance. Historical offers without an audit record remain explicitly marked as unrecorded. None of these records authorizes a payment.
An authenticated merchant can inspect product-bound acknowledgements in pages of up to 30 using GET /api/local/v5/products/{id}?audit=1 on localhost. The response contains audits, hasMore and an opaque nextCursor when another page exists. Pass that cursor as the cursor query parameter on the same authenticated product URL; it expires after one hour and is bound to the merchant and product. On expiration, reload the first page rather than reusing a cursor from another merchant or product. The response includes the offer reference, policy version, Free 0% fee and timestamp, but never the checkout bearer or secret key. It is an audit of commercial acknowledgement, not an on-chain receipt, transaction confirmation or public production API. The future 1% fee remains inactive and blockchain gas is separate.
The local merchant plan view also supports GET /api/local/v5/plans/{id}?audit=1 for the recorded consent history of standalone checkout links and multi-price offers originating from that plan. The optional cursor is encrypted, expires after one hour and is bound to that merchant, plan and audit type. A returned integrityVerified flag means the internal SHA-256 fields agree with the stored record; it does not mean an independent signature, an EVM transaction, a payment or an immutable external witness exists. An empty history does not prove a historical link was consented to. Only the locally authenticated merchant can query this endpoint; it is not part of public API v1. Free 0% applies in prelaunch, the future 1% remains disabled, and gas is separate.
See the developer quickstart for the distinction between test flows and actual payment settlement. Polygon, Base and Arbitrum USDC V5 remain simulated with zero live rails.
Local V5 event audit: inspection is not delivery
In the localhost-only V5 multi-price offer, the payer may optionally submit {"planId":"...","constraints":{"version":1,"maxPlanPer30Minor":"1200","maxUpfrontPlanMinor":"1200","preferredPeriodSeconds":2592000} to the existing offer selection API. The backend recomputes the 30-day equivalent with exact integer ceiling arithmetic against the locked merchant price snapshot, rejects a budget or period mismatch before creating the one-time child checkout, and preserves the original request shape for older links. These are voluntary payer limits, not merchant price changes, a gas guarantee, a wallet authorization or a real charge. For optional V2 payer ceilings, send {"version":2,"maxCombinedPer30Minor":"1290","maxUpfrontCombinedMinor":"1290","horizonDays":90,"maxHorizonCombinedMinor":"3870"} inside constraints. The server uses the merchant-owned maximum simulated gas per cycle, not client-provided forecasts, to conservatively check the 30-day, initial and 30/90/365-day caps under the selection transaction. A route preview may estimate less gas than that conservative ceiling; an over-budget choice is rejected before a child session is created. V1 plan-only constraints remain compatible. Gas remains separate from the merchant price. Free is 0% in prelaunch; the future 1% remains inactive.
The V5 localhost merchant sandbox exposes a paginated manual outbox audit. Every event is represented by a short-lived, encrypted, merchant-and-plan-bound reference; internal checkout session identifiers and event keys are not returned to the dashboard. Inspecting an event changes its local review state only. A consumer rehearsal records a fictional acceptance or rejection, not an HTTP webhook delivery, blockchain payment, entitlement or receipt.
The sandbox requires an authenticated merchant session and a local database. References expire after one hour and become invalid after a process restart; stale references require reloading the local audit list. All Polygon, Base and Arbitrum V5 paths remain simulated, with a Free 0% platform fee, a disabled future 1% policy and separate gas. Do not use these development-only endpoints in production or infer payment finality from a local event.
Payer history uses encrypted, one-hour cursors bound to the authenticated wallet, checkout session, merchant and plan. An expired or revoked checkout can still show previously acknowledged simulated renewals and offer cancellation; it cannot restart charges. If a manual simulation response is lost, retry with the same event idempotency key rather than generating a new event. Cursors can expire or be invalidated by a local process restart: reload the first history page. These are offline safety properties, not evidence of on-chain settlement.
Local V5 renewal timeline: forecasts are not charges
The local merchant register, payer history and checkout recovery now display the same deterministic illustrative billing timeline. A simulated active subscription shows the next hypothetical due date based on enrollment time, period and manual cycle number. A simulated failed cycle shows its retry budget (maximum two failed retries); cancellation removes any future hypothetical due date. No cron job, wallet signature, automatic retry, transaction or receipt is generated.
These dates are planning examples, not on-chain evidence or promises of settlement. The local simulator accepts manual cycle advancement without enforcing real elapsed billing time. The current V5 sandbox uses only fictitious USDC Polygon, Base and Arbitrum paths; Free 0% applies during prelaunch, the future 1% remains disabled, and gas is separate. Actual collection and finality require separate, independently tested authorization and reconciliation flows.
Authentication
API v1 uses a merchant-specific Bearer key. Generate it from a signed merchant dashboard session, store it securely on your backend, and send it in the Authorization header.
Authorization: Bearer rp_live_xxxxxxxxxxxxxxxxxxxxxxxx
Keys are hashed in the database. When rotated, only the newly returned plaintext key should be kept by the merchant backend. For plan creation, send a stable Idempotency-Key from your backend: a matching retry returns 200 without creating a second plan, while conflicting reuse returns 409. Do not treat either response as payment settlement.
Why this API exists
Fast merchant integration
Create a plan, get a checkout URL, and connect your app to recurring wallet payments without building all billing primitives from scratch.
Operational clarity
The API exposes subscriptions and charge events in a SaaS-friendly shape while preserving on-chain identifiers for reconciliation.
Checkout links
A merchant can create a plan once and generate checkout links for pricing pages, onboarding flows, or upgrade prompts.
Webhook-ready model
Lifecycle updates can be pushed into your product so access control and entitlement sync do not depend on manual support work.
USDC subscription API: supported flow versus multichain roadmap
The documented v1 merchant API is focused on Polygon and USDC. The V5 payment-intent, signed-quote and automatic network-routing modules are offline development code, not public API endpoints. Do not send live Base, Arbitrum, USDT or EUR-stablecoin transactions to v1 expecting them to settle.
For checkout links, customerExternalId is an optional merchant-supplied reference, not an authentication credential or proof of payment. Keep it within 128 characters without control characters. The checkout preserves only bounded attribution parameters (userid, ref, source and utm_*); avoid putting secrets or access tokens in URLs. Receipt replays cannot rewrite an existing subscription's customer reference. API event feeds support an opaque cursor and return page.nextCursor when more events exist. Lifecycle events are deduplicated across webhook endpoints; delivery acceptance is not proof of settlement. Merchants can inspect the same read-only, paginated event timeline from the dashboard without placing a Bearer API key in browser JavaScript. A 2xx webhook response acknowledges HTTP transport, not entitlement processing. Continue using signed, idempotent webhooks and independent chain reconciliation before granting access.
What to verify before granting SaaS access
Create a merchant plan, obtain a checkout link and correlate the resulting subscription with your own customer identifier. A wallet signature, transaction hash or browser callback is not a settled payment. Grant access only after your backend has independently reconciled the payment state; handle duplicate events idempotently and revoke future billing authorization when a customer cancels.
Fees, tokens and network changes
The current Free platform fee is 0% until explicit activation; for 100 USDC the merchant receives 100 USDC. A future 1% merchant-funded fee would mean 99.00 USDC to the merchant and 1.00 USDC to RecurCrypto, only with fresh consent and no retroactive charges; blockchain gas is separate. V5 also requires a server-approved fee recipient and exact signed fee terms before tracking a transaction. Its multi-network verification has not been approved for live use.
How a future wallet-first multichain checkout chooses a payment route
A secure stablecoin subscription checkout must compare the customer鈥檚 actual token balance, supported contract addresses, network gas and merchant acceptance policy before presenting a payable quote. A token with the same ticker on a bridged contract is not interchangeable with native USDC. If no verified route can cover the charge and gas, the checkout must explain that payment is unavailable rather than claim success or silently swap assets.
The planned V5 design must calculate the current 0% Free fee or a future 1% fee in integer token units after explicit activation, bind the recipient and expiry to the signed quote, and keeps the receipt pending until canonical settlement and finality have been checked. The payer may still need to approve a wallet signature or network change. These are design and offline verification requirements, not a claim that Base, Arbitrum, USDT or EURC payments can be accepted today.
Stablecoin recurring billing API: what happens if a quote changes during checkout?
For a future USDC subscription payment, a quote can become invalid while a wallet is being checked: the customer might cancel, the merchant might change the plan price, a payment might already be submitted, or the authorization could expire. A safe integration must re-read the merchant-scoped payment intent after asynchronous wallet and contract checks, verify its revision and unchanged amount, and refuse a stale authorization rather than charge twice. The payer must approve any new quote with updated fees and gas shown separately.
This last-read safeguard exists only in the offline V5 simulation. It does not make a live stablecoin subscription gateway: a production signer must also claim and persist the authorization atomically in a transactional database, recover the EIP-712 signer and reconcile canonical blockchain finality. A cancelled or pending payment is not a paid subscription and must not generate a final receipt.
For the existing Polygon USDC subscription scope, see Polygon USDC subscriptions; for API integration steps, see developer quickstart. Base and Arbitrum remain simulation-only V5 routes.
USDC subscription API: signature expiry versus wallet confirmation
A future stablecoin recurring billing API must distinguish three different deadlines: the merchant quote expiry, the freshness of the verified network snapshot, and the EIP-712 signature deadline enforced by the contract. A quote that is valid for thirty seconds does not justify using chain evidence that is already five seconds old. The signature deadline should be capped to the earliest verified expiry, rounded down to the contract's whole-second timestamp. If the remaining interval is too short to authorize safely, issue a new quote instead of extending the old one.
For example, a customer begins a 20 USDC subscription while the wallet shows enough USDC and gas. If the database reread finishes after the evidence lease expires, the server must return an expired-quote response, not a reusable signing payload. During Free the fee is 0 USDC, leaving 20 USDC to the merchant; only after activation and new consent would 1% mean a 0.20 USDC fee and 19.80 USDC merchant net; wallet gas is quoted separately. The payer should see the refreshed terms and consent again before another attempt. Cancellation, duplicate references and chain reorganizations still require independent transactional and settlement checks.
This deadline fence is tested in the offline V5 prototype only. It is not a live Base or Arbitrum checkout, a production signing service, or evidence of successful payment. Review the developer quickstart and on-chain reconciliation before designing entitlement activation.
Recurring USDC payments for SaaS: Free 0% must match from quote to finality
For a hypothetical 30 USDC monthly checkout, a Free prelaunch quote must bind a 0-bps platform fee and a 0-bps payer ceiling. The simulated contract observation, EIP-712 typed data, wallet submission and canonical settlement event must agree: 30 USDC to the merchant and 0 USDC to the platform, with network gas separate. A historical 1% test quote must never be silently treated as Free consent.
An integration must retain its merchant-scoped idempotency key while the transaction is pending, verify the exact token and contract on the selected chain, and wait for the required finalized block before marking a subscription paid. Base and Arbitrum V5 remain offline fixtures, not accepted checkout networks. A future 1% fee would require explicit activation, a new policy version and fresh consent; existing charges are not repriced retroactively.
This is an integration design requirement, not a live V5 endpoint or a production payment guarantee. See USDC subscription payments and reconciliation and finality.
For a runnable integration sequence see the quickstart; for reconciliation semantics see on-chain reconciliation. Never treat offline test fixtures as payment confirmation.
Stablecoin recurring billing API: what if a finalized USDC payment is reorganized?
A finalized subscription record is evidence of a previously verified settlement, not an excuse to skip every later chain check. In an exceptional deep reorganization, the canonical block hash can change even after a payment was considered final. For high-value entitlements, a merchant backend should recheck the transaction receipt, canonical block, finalized height, payer, contract, token and settlement event before relying on a historical receipt again. A missing RPC response is unknown, not proof that payment succeeded or failed.
Safe entitlement decision
Keep the original merchant-scoped payment reference and idempotency key. If a finalized receipt no longer matches the canonical chain, flag it for review and prevent duplicate credits. Do not silently rewrite the customer ledger, resubmit a charge, or infer a refund from an absent event. A separate transactional process must resolve the subscription state and any customer communication.
Current implementation boundary
V5 contains a read-only, local finality-recheck prototype for Polygon, Base and Arbitrum USDC fixtures. It does not expose a production endpoint, suspend a live subscription or provide an audited automatic recovery worker. The documented merchant API remains focused on Polygon/USDC; gas is separate and the V5 Free platform fee is 0%. The future 1% is inactive and requires a new consent before any new charges.
Read on-chain reconciliation for confirmation and reorganization concepts, or the USDC quickstartfor the existing integration sequence. These are design notes, not a guarantee of live multichain settlement.
API endpoints
| Method | Path | Purpose |
|---|
| GET | /api/v1/health | Service health and documentation pointer. |
| GET | /api/v1/auth/keys | Returns merchant API key status for the signed-in dashboard session. |
| POST | /api/v1/auth/keys | Creates or rotates a merchant API key. |
| DELETE | /api/v1/auth/keys | Revokes the current merchant API key. |
| GET | /api/v1/plans | List merchant plans. |
| POST | /api/v1/plans | Create a plan in PROVISIONING state; Idempotency-Key prevents duplicate plans on retry (200 replay, 409 conflicting reuse). |
| POST | /api/v1/checkouts | Generate a checkout link only for an ACTIVE plan with an on-chain plan ID; otherwise 409 PLAN_NOT_READY. |
| GET | /api/v1/subscriptions | List merchant subscriptions. |
| GET | /api/v1/subscriptions/{id} | Read one subscription with its ledger. |
| GET | /api/v1/events | List lifecycle events and charge events exposed through API v1. |
Create a plan
POST /api/v1/plans
{
"name": "Pro",
"amount": "19.99",
"currency": "USDC",
"interval": "month"
}
Generate a checkout link
POST /api/v1/checkouts
{
"planId": "plan_xxx",
"customerExternalId": "user_123"
}
Stablecoin recurring billing API: plan readiness and checkout state
The current POST /api/v1/plans endpoint returns a plan with status: PROVISIONING after creating the database record. That response is not proof of a deployed on-chain plan. Wait until the merchant-scoped plan is ACTIVE before offering its checkout. A checkout link or wallet signature is not a settled USDC subscription: reconcile canonical on-chain payment evidence before granting access.
Use a stable customer reference and idempotent event processing when integrating SaaS entitlements. Cancellation must prevent future renewals; a deep reorganization requires a payment review rather than an automatic second charge. Polygon/USDC is the existing integration scope; Base and Arbitrum USDC routes remain offline V5 simulations. Free prelaunch platform fees are 0%; the future 1% is disabled until explicit activation and new consent, with network gas charged separately. See the API quickstartand settlement reconciliation guide.
Stablecoin recurring billing API: integration questions
Can I accept USDC subscription payments across multiple networks?
The documented v1 merchant endpoints target Polygon USDC. The Polygon, Base and Arbitrum routing and renewal-consent logic in V5 is offline simulation only. Do not interpret a simulated quote as a wallet payment instruction or use USDT/EURC fixtures as live token support.
What happens when the subscription fee changes?
V5 Free previews require a versioned 0% platform-fee policy and exact 0-bps consent. The future 1% rate is not active; it requires explicit owner activation and fresh payer consent, without retroactive charges. Network gas is separate. An old 1% authorization is not permission to charge under new terms.
When can my SaaS issue a final payment receipt?
A transaction hash, wallet callback or pending subscription row is not final settlement. Keep the payment pending until your backend has verified the correct chain, contract, token, payer, merchant, amount, event and required finality. Reconcile reorgs and duplicate notifications before granting or renewing access.
For a step-by-step integration see the USDC subscription quickstart; for a network-specific explanation see Polygon USDC subscriptions. These descriptions are not a promise that V5 multichain payments are enabled.
USDC recurring payments API: reconciliation and retry safety
Can I retry a stablecoin subscription payment after an RPC timeout?
An unavailable chain response is not proof that a payment failed. Keep the existing payment reference and idempotency key, show a pending or verification-required state, and reconcile the original transaction before considering another authorization. Do not create a new charge on another network just because the first provider is slow.
What if a finalized payment is affected by a chain reorganization?
A verified conflicting canonical block requires review of the original payment and subscription together. The offline V5 design uses REORG_REVIEW to prevent duplicate entitlement creation while retaining forensic evidence. A transient RPC outage, lower reported head or mismatched event index is not, by itself, proof of a reorganization. This V5 quarantine flow is not deployed or exposed as an API v1 endpoint.
How can I verify a checkout demonstration without mistaking it for a payment?
The localhost-only V5 checkout supports an authenticated POST /api/local/v5/checkout/{token} request with {"action":"audit"}. It reads a single transaction-consistent demonstration record and reports the simulated quote state, server-owned rail name, expiry, 0-bps Free policy, and whether demo acknowledgement remains eligible. Its fingerprint is unsigned and is not an on-chain receipt, wallet signature, authorization or entitlement. The response deliberately omits the payer address, merchant identity and bearer token. A future paid V5 integration must instead verify actual canonical blockchain settlement before issuing a receipt.
A second read-only audit returns terms only when the locked server-side merchant price is internally consistent: integer USD cents map exactly to six-decimal simulated USDC units, the chosen rail is on the merchant allowlist, the gas estimate stays within the merchant cap, and the original policy and offer remain valid. The payer interface compares this audit to the immutable quote fingerprint before permitting demo-only acknowledgement. The existing localhost multi-price comparison operation also returns a deterministic horizonGuide for 30, 90 and 365 days, with separate hypothetical plan, initial approval gas and subsequent gas components. A client independently recomputes the guide from every server-validated forecast; mismatched cycle counts, fees, routes or totals are rejected. A payer-entered maximum horizon total is a voluntary budget guard, not a payment authorization or a modification of merchant prices. Expired, revoked, altered or historical records retain their audit history but have no actionable terms. These localhost endpoints are not public billing APIs, EIP-712 consent, settlement evidence, or payment receipts.
How does a payer confirm exactly the simulated quote they saw?
The localhost V5 demo returns a quoteId and quoteFingerprint together with its immutable network, price, expiry and versioned Free 0% policy. A demo acknowledgement must send both values, the local-demo-v1 fingerprint version, the policy version, the 0-bps fee, inactive future-fee flag, gas-separate flag and explicit acknowledgement of the no-payment disclaimer. The backend recomputes the fingerprint from the locked database quote and rejects mismatches. This protects the demonstration against stale UI confirmations, but the unsigned digest is not EIP-712 consent, a token allowance, an on-chain payment, or a settlement receipt. V5 real payment networks remain disabled.
Can a merchant track a simulated checkout without accessing the payer wallet?
In the localhost-only V5 dashboard, a signed-in merchant can inspect their own checkout links and multiprice offers with the optional view=journey filter on the existing plan links API. A single transaction-consistent read joins the link, locked quote and manual demonstration lifecycle by merchant and plan. It distinguishes open, claimed, revoked-link, expired-link, quoted, expired-quote, acknowledged, manual active, manual past-due and cancelled simulation states, without returning payer wallet details, tokens or signatures. A merchant revocation or an expired link cannot erase a historical simulated quote; an offer selection is accepted in the audit only when its child checkout remains bound to the same payer, and the display never claims settlement. Acknowledgement and manual lifecycle progress are not proof of stablecoin settlement, recurring authorization, payment receipts or entitlements. The public V4 API is unchanged, Free remains 0% during prelaunch, future 1% is inactive and gas is separate.
How should merchants investigate simulated renewal failures and pending webhook events?
The localhost-only GET /api/local/v5/plans/{id}/demo-activity?kind=health endpoint returns a tenant-scoped, transaction-consistent snapshot. Its triage object orders manual review of simulated exhausted retries, past-due renewals, uninspected outbox records, rejected webhook rehearsals, expired quotes, checkout links and multiprice offers. Review controls open the existing read-only lifecycle, outbox, quote or link views; they never retry a charge, deliver a webhook, reactivate a plan or generate a receipt. Counters can overlap: exhausted retries are a subset of past-due cycles, so they must not be summed as independent payments. A zero-alert result is not evidence of settlement or production readiness. No remote blockchain, wallet signature, live USDC, bridge or paid fee is enabled; Free is 0% in prelaunch, future 1% is disabled and gas remains separate.
What if a checkout database transaction loses its connection?
A missing PostgreSQL COMMIT response does not establish whether a simulated checkout link or consent record was stored. Preserve the original merchant-scoped idempotency key and request digest, report the outcome as unknown, and reconcile using a fresh connection. Never mint a replacement token, retry a charge, or infer a receipt from a timeout. A query still in flight when the application exits its transaction must cause the connection to be discarded, not returned to another merchant or sent an overlapping ROLLBACK. If a SQL query fails, catching its exception inside the callback does not make the transaction safe to commit.
Both local V5 SQL adapters now reject multiple statements, transaction-control commands and malformed SQL before forwarding a parameterized query. A trailing semicolon inside a quoted value or SQL comment is not treated as a second command. The Prisma and pg adapters share the same offline-only guard; this does not replace merchant scoping, transaction isolation or real PostgreSQL certification. The safeguard cannot sign an EIP-712 intent, activate a network, collect a fee or establish payment finality. Free remains 0% during prelaunch; a future 1% requires explicit new consent, with gas charged separately.
These safeguards are exercised only with offline SQL-protocol fixtures. PostgreSQL driver integration, secure EIP-712 signing, and browser E2E remain uncertified. Free is 0% in prelaunch, the future 1% fee requires new consent and remains inactive, gas is separate, and all V5 USDC Polygon/Base/Arbitrum routes are simulated.
How do I check whether a V5 plan is ready before creating a checkout link?
For localhost-only simulation, an authenticated merchant can request GET /api/local/v5/plans/{id}?readiness=1. The read-only preflight checks the merchant-owned plan status and revision, its immutable price hash, the active Free 0% policy, the server-controlled Polygon/Base/Arbitrum USDC fixture allowlist, six-decimal token-unit consistency, supported billing period and separate gas ceiling. The result lists explicit blockers and a manual next step without minting a link, reserving funds, contacting a wallet or activating a network. A positive preflight is advisory: the actual checkout creation must revalidate the plan inside its own transaction, and cannot be treated as a real PostgreSQL, EVM, signature or settlement certification. The future 1% fee is inactive and requires a new versioned consent before any later activation.
How does guided local checkout handle uncertain responses?
The guided payer UI composes the claim, compare, preview and audit actions on the existing POST /api/local/v5/checkout/{token} endpoint. These are sequential, separately validated localhost operations, not one atomic payment. The server binds each mutation to the signed wallet and merchant-owned immutable price. If a comparison has no viable simulated route, no quote is requested. If a response is lost after a quote write, the UI stops and requires authenticated status recovery; it never treats an HTTP timeout as a rollback. Only an exact server audit of the quote fingerprint, merchant price, separate gas and Free 0% policy can enable the subsequent explicit demo acknowledgement. None of these actions authorizes payment or renewals. Polygon/Base/Arbitrum remain offline fixtures, future 1% inactive, and V4 permissions unchanged.
How can a payer safely recover a checkout or view a historical simulation?
The existing localhost POST /api/local/v5/checkout/{token} actions session_status, audit, lifecycle_portal, lifecycle_history and lifecycle_status provide payer-authenticated, tenant-bound read snapshots. The payer interface now rejects malformed snapshots, forged live-payment or entitlement flags, mismatched price or gas, unknown rail IDs, contradictory consent states and unsafe history cursors before rendering them. A restored quote is display-only until a fresh authenticated audit matches its fingerprint, price, fee policy and simulated rail. Historical cancellation remains a separate explicit action, never a payment or automatic renewal. These checks are client-side defense in depth, not proof of on-chain finality or a substitute for PostgreSQL transaction testing. Free is 0% during prelaunch, future 1% remains disabled until new consent, and gas is separate. Polygon, Base and Arbitrum V5 rails are offline simulations.
Can I safely replace an unclaimed checkout link?
In the localhost-only V5 simulator, a merchant can replace an unclaimed standalone checkout link using the existing POST /api/local/v5/plans/{id}/links endpoint with action: rotate_checkout, the old sourceSessionId, a new client-held 256-bit bearer and an explicit, renewed versioned consent. The server revokes the old link, creates the replacement and persists the consent audit in one serializable transaction. An idempotency key permits recovery after a lost HTTP response without minting duplicate links. A link claimed by a payer, linked to a multiprice offer or containing a quote cannot be rotated this way: historical payer decisions must be preserved, not silently repriced or reassigned. The replacement never initiates payment, signatures, transfers, receipt issuance or network access. Free is 0% during prelaunch, future 1% remains disabled, and gas is separate.
Does the API automatically bridge USDC between Polygon, Base and Arbitrum?
No. The documented integration is Polygon USDC; multichain V5 routing is simulation-only. No invisible bridge or swap is performed. The current Free prelaunch platform fee is 0%, the future 1% fee is inactive and requires fresh informed consent, and blockchain gas is separate.
Continue with the verified API quickstart, stablecoin recurring payment overview or on-chain reconciliation guide. These are implementation notes, not a guarantee of live multichain settlement.
Webhooks and lifecycle
The API is designed to complement the existing webhook system. Use webhooks to update access, account state, or internal billing logs whenever subscription lifecycle events occur. Delivery attempts are persisted with bounded retries and leased workers; delivery remains at least once, so recipients must deduplicate by event id. An HTTP 2xx only acknowledges delivery, not a finalized payment.
- subscription.created
- subscription.charged
- subscription.payment_failed
- subscription.cancel_at_period_end_set
- subscription.cancelled
- subscription.ended
Important behavior
- Chain-first state: on-chain subscription state remains authoritative for contractual and payment truth.
- DB as index: the database accelerates dashboards, webhooks, support tooling, and reconciliation without inventing chain state.
- USDC deployment: this version documents the current Polygon USDC integration already used by the product.
- Merchant-safe links: checkout URLs include merchant code and plan slug, and optionally accept an external user identifier.
API links
Use the documentation page for human-readable guidance and the OpenAPI file for tooling, SDK generation, and internal backend integration.