Quickstart to launch your first crypto subscription
Follow the documented Polygon USDC integration path for plans, checkout links and subscription events. V5 multichain routing is an offline prototype; no Base, Arbitrum, USDT or EUR-stablecoin payments are enabled by this guide.
Local V5 checkout only: after the merchant creates an offer, a signed-in payer may set optional plan-only monthly-equivalent and upfront budget limits plus a billing-period preference. The existing offer selection endpoint checks those limits again against locked merchant prices before creating a simulated child checkout. The separately itemized gas projection is nonbinding; no wallet debit, recurring authorization, receipt or live V5 network is created. Free 0% remains in force during prelaunch, with a future 1% fee inactive until explicit authorization.
For the local-only V5 multiprice checkout, use the existing POST /api/local/v5/offers/[token] compare_all action before submitting a selection. The version 3 selection constraint includes a named offline fixture scenario and requires a viable server-allowlisted USDC route. The compare_all response also contains a short-lived selectionProof for each offered price. Pass only the proof corresponding to the explicitly chosen plan as selectionProof alongside planId and version 3 constraints. The proof is bound to the authenticated payer, offer bearer, price and scenario; the server verifies it inside the locked selection transaction and repeats the simulated route check before creating a demonstration checkout. If the proof expires or the local server restarts, request a fresh compare_all rather than replaying the write. This does not inspect real wallet funds or enable Polygon, Base or Arbitrum settlement. Existing version 1/2 constraints remain compatible; no signature, charge or recurring consent is created by selection.
1. Open the dashboard API page
Go to /dashboard/developers with a signed merchant session. Generate or rotate your API key and store it only in your backend or secret manager. If you want the fastest path, create one plan first and come back here to wire the API second.
2. Create your first plan
Call POST /api/v1/plans with name, amount, currency, and interval. In this deployment the API is focused on Polygon + USDC.
3. Generate a checkout URL and place it in your pricing page
Call POST /api/v1/checkouts to create a customer-facing link that you can embed in your pricing page or onboarding flow.
4. Read subscriptions and events
Use GET /api/v1/subscriptions and GET /api/v1/events to power support tooling, internal billing views, and reconciliation workflows.
5. Configure webhooks
Set your webhook URL in the dashboard and consume lifecycle events so your app reflects subscription state changes quickly.
Stablecoin recurring billing API: a minimal USDC plan request
The documented API v1 accepts a merchant Bearer key and a plan body containing name, amount, currency and interval. The amount is a human-readable decimal string; the server converts USDC to six-decimal base units. Keep the key on your server, never in browser JavaScript.
curl -X POST https://www.recurcrypto.com/api/v1/plans \
-H "Authorization: Bearer YOUR_SERVER_SIDE_API_KEY" \
-H "Idempotency-Key: SaaS-Pro-Monthly-2026" \
-H "Content-Type: application/json" \
--data '{"name":"SaaS Pro Monthly","amount":"30.00","currency":"USDC","interval":"month"}'Keep the same Idempotency-Key when retrying this exact plan request after a timeout: the server returns the existing merchant plan with HTTP 200 and idempotentReplay: true instead of creating a second plan. Reusing the key for a different name, price or billing interval returns HTTP 409. Keys are scoped to each merchant and retained for the lifetime of the plan. This requires the additive database migration before using the feature; it is not proof of a payment.
A 201 response means the plan record was created, not that a blockchain transaction is final. Inspect data.status and the provision result before advertising a checkout. A plan still marked PROVISIONING must not be described as ready. When the plan is ready, POST /api/v1/checkouts accepts its planId; the returned link is not proof of payment.
The current Free platform fee is 0%, with no fixed platform charge and separate network gas. A future 1% fee requires explicit activation and fresh consent, never retroactive billing. USDC on Base and Arbitrum remains V5 offline simulation; this example does not enable those networks or USDT/EURC.
Create a Polygon USDC checkout link only for a ready plan
After the plan response reports data.status as ACTIVE, use the merchant-scoped plan ID to request a checkout link. The existing POST /api/v1/checkouts response includes data.planStatus and data.checkoutUrl. The API now rejects plans that are not ACTIVE or lack an on-chain plan ID with HTTP 409 PLAN_NOT_READY; never publish a URL from a provisioning response. A URL is not a paid invoice, blockchain receipt or permission to provision SaaS access.
curl -X POST https://www.recurcrypto.com/api/v1/checkouts \
-H "Authorization: Bearer YOUR_SERVER_SIDE_API_KEY" \
-H "Content-Type: application/json" \
--data '{"planId":"YOUR_ACTIVE_PLAN_ID"}'A database status of ACTIVE is necessary but not sufficient to charge. The V4 public plan lookup, hosted checkout and payment preflight must agree on the merchant, amount, billing period, Polygon USDC token contract, subscription contract, paused state and observed contract fee. Their read-only verification uses one observed block. If chain reads are unavailable, checkout fails closed: do not ask the customer to approve or retry a charge. A checkout URL alone never proves readiness or settlement.
If the plan remains PROVISIONING, data.checkoutUrl is null in the plan API, and the checkout API returns 409. Retry only the read after provisioning; do not create another plan or charge. Do not retry a wallet charge because an API response or webhook is delayed. Keep cancellation and renewal terms visible to the payer; verify final settlement separately. Free 0% is the prelaunch platform fee; the future 1% remains disabled until explicit activation and new informed consent, with gas separate.
See the stablecoin recurring billing API reference and webhook verification guide for subsequent steps. Multired V5 Polygon, Base and Arbitrum checkout routing is simulation-only. In the offline multi-price payer demo, compare every offered price before applying 30-day, upfront or gas-inclusive budget ceilings. The optional horizon budget can additionally constrain the complete simulated plan-plus-gas cost across 30, 90 or 365 days: full hypothetical cycles are counted, the one-time synthetic approval gas is not multiplied across renewals, and a price exceeding the selected horizon is blocked until the payer explicitly selects another viable offer. These totals are illustrative, not payment quotes or network estimates. A route-aware budget guard prevents proceeding with an unaffordable simulated option; a displayed alternative still requires explicit selection and separate demonstration consent. No bridge, swap, wallet debit, V5 payment or settlement is performed.
Recurring USDC payments for SaaS: a safe retry and settlement checklist
A checkout link, wallet popup, transaction hash and successful webhook delivery are four different states. Do not unlock a paid subscription based on any one of them. Your backend should persist the merchant-scoped plan ID, customer reference and idempotency key before presenting the hosted checkout.
- Before payment: confirm the plan is ACTIVE and its Polygon USDC contract details are verified. Show the exact billing period, cancellation path, Free prelaunch platform fee of 0%, and separately estimated wallet gas.
- While pending: reuse the same idempotency key for the same request. A network timeout does not prove failure; read the existing subscription and event state before inviting another wallet authorization.
- After settlement: reconcile the correct chain, token, merchant, amount, canonical block and verified event. Only a finalized, verified payment can justify an irreversible paid receipt or entitlement.
- On cancellation: distinguish stopping future renewals from revoking an already-paid period. A failed renewal must not be presented as a completed payment.
The V5 design evaluates USDC routes on Polygon, Base and Arbitrum in offline simulations only. It cannot automatically move tokens between networks, swap assets, or charge a customer today. A future 1% platform fee is inactive and would require a new server-side policy version and explicit fresh consent, without retroactive charges. See API contracts, webhook verification and settlement evidence.
Local payer preflight: read before a one-time selection
In the localhost-only multi-price demo, run compare_all to obtain the per-price comparison proof, then call the same offers endpoint with action: preflight, the chosen planId, V3 constraints and that proof. Check the returned immutable price, period and simulation flags. If preflight fails or the wallet session changes, do not submit the selection. If it succeeds, the explicit selection request still performs independent transactional validation. Preflight never reserves gas, debits USDC, grants a subscription or issues a receipt. All V5 Polygon/Base/Arbitrum routes remain fixtures; Free 0% is effective during prelaunch, future 1% inactive, gas separate.
Local V5: one locked quote per checkout session
The offline merchant sandbox now includes a versioned consent-audit design for product launches, single-price links and multi-price offers. On a disposable local PostgreSQL database, the simulated link and its tenant-scoped consent record are intended to commit together or roll back together. The audit contains a hash of the request identity and a server-side policy version, not a wallet secret or a payment authorization. A historical link can be recovered without inventing a consent record retroactively; its response explicitly identifies that limitation. The migration is deliberately excluded from production deployment pipelines and is not yet PostgreSQL-certified. Free remains 0% in prelaunch, a future 1% is disabled, gas is separate, and all three V5 USDC networks are simulations.
In the offline V5 prototype, the merchant configures a plan and a test checkout link. After a test wallet claims the link, the server derives a route from locked plan data and deterministic USDC fixtures. The request does not accept a payer-supplied chain, token address, gas quote or amount. This protects against stale prices and a changed network being substituted between preview and persistence.
- Identical retry
- The original unexpired quote is returned; no duplicate simulated charge or session is created.
- Different scenario or changed price
- The checkout fails closed; create a new link rather than silently replacing consent or quoted terms.
- Insufficient test balance or gas
- No route is quoted. The application never performs an unapproved bridge or swap.
- Simulated acknowledgement
- This confirms the demo disclaimer only. It is not an EIP-712 signature, on-chain receipt, paid entitlement or renewal mandate.
When a payer refreshes the localhost-only V5 demonstration, POST /api/local/v5/checkout/{token} with { "action": "session_status" } checks the authenticated wallet and current product, offer and price snapshots. It restores only an already-claimed session; it never claims an open link, signs an EIP-712 authorization, rotates a token or triggers a payment. If a merchant revokes an offer, archives a product or changes a price, the payer must start a fresh checkout instead of reusing stale consent.
Manual V5 renewal demonstrations now recheck a selected offer before enrollment and before each simulated cycle. Merchant revocation stops new demo cycles, while the historical event view and explicit cancellation remain accessible. A simulated acknowledgement is not authorization for recurring debits, and no receipts, webhooks to third parties, chain calls or paid entitlements are generated.
See the API boundary and Polygon USDC subscription guide. V5 Polygon, Base and Arbitrum are offline fixtures only; Free is 0% during prelaunch, future 1% is inactive and gas remains separate.
USDC subscription checkout: wallet and payment troubleshooting
For developers integrating recurring USDC payments into a SaaS product, separate wallet authorization from verified settlement. The customer should see the amount, platform fee and any network gas before confirming. A transaction hash alone does not mean a subscription has started.
- Wallet on the wrong network
- Explain why a wallet network change is required, and request it only for an available, verified payment route. Base and Arbitrum V5 routes are offline simulations, not supported live checkout options.
- Not enough USDC or network gas
- Show a clear insufficient-balance message; never initiate a bridge or swap without a separate, informed approval. Keep the payment pending rather than displaying success.
- Signature declined or transaction status unknown
- Do not create a second charge while the first outcome is uncertain. Preserve the idempotency key and reconcile against canonical chain evidence before allowing another attempt.
- Renewal, cancellation and receipt
- Explain the renewal authorization and next billing date, provide a cancellation path, and issue a final receipt only after a verified settlement event and the required finality threshold.
The V5 design has a Free 0% platform fee now; future 1% merchant-funded only after explicit activation and new consent, with no fixed payment charge; blockchain gas is separate. USDT and EUR stablecoin routes require independent verification before being offered to customers.
Why a USDC subscription quote may expire before wallet confirmation
A recurring USDC checkout can pass an initial balance check and still become unsafe before the customer signs. The merchant may change the plan price, the wallet may spend its native gas, or the quoted network fee may no longer match the subscription transaction. A trusted backend must revalidate the exact token amount, its display conversion, the exact 0% Free platform fee (future 1% requires separate consent) and the gas component after reserving an authorization.
If a server-side chain observation or quote signer lookup takes too long, discard the stale quote and ask for a fresh one. Do not automatically resubmit or create a second charge: first reconcile the existing payment reference and its pending state. Show the user whether they need to approve a token, retry a signature or wait for finality. No hidden swap or bridge is performed.
These post-reservation protections are tested in the offline V5 simulation; they are not public endpoints or proof of live Polygon, Base or Arbitrum multichain billing. The existing Polygon/USDC integration remains separate. See stablecoin recurring billing API documentation and USDC subscriptions for supported scope and consent.
Recurring USDC payments for SaaS: what to do when a checkout preview changes
A preview is not an authorization to transfer tokens. Between the first balance check and the final quote, a customer may revoke allowance, spend network gas, cancel a plan or lose access to a merchant account. A backend should re-check payer identity, merchant price, the allowlisted chain and token contracts, plan status, gas estimate and the subscription contract fee before presenting a wallet action.
If any observation changes, discard the preview and request a new one with fresh consent. Do not silently switch networks, bridge funds or reuse an earlier signature. A payment in an unknown state must be reconciled before retrying with the same idempotency key. A browser callback alone must never grant paid access or generate a final receipt.
The current V5 Free preview has a 0% platform fee; the proposed 1% rate is inactive and would require a new authorization. Network gas is separate. These double-observation checks run only in local V5 simulations and are not a transactional guarantee or a live Base/Arbitrum checkout. For production integration boundaries, read the stablecoin recurring billing API and Polygon USDC subscriptions guides.
Recurring USDC billing: prevent stale renewal consent
A subscription renewal preview must not trust a browser-supplied clock or two matching dates copied from the same request. A backend should independently read the subscription's next payment date, cancellation and pause state, tenant ownership, and current policy version. It must reject a preview when those server-owned facts differ from the wallet's view, even if the browser claims that the quote is still fresh.
Example: a payer opens a 30 USDC monthly renewal and the merchant cancels the plan while the wallet screen remains open. The safe response is to discard the unsigned preview and show that renewal is unavailable. Replaying the old date or setting the browser clock backwards cannot restore consent. No second charge should be attempted until the previous payment reference has been reconciled.
The current Free platform fee is 0%, with gas separate and no fixed fee. A future 1% merchant-funded rate is inactive and would require explicit activation and new consent; it must never apply retroactively. This independent-snapshot guard is exercised only by offline V5 simulations across Polygon, Base and Arbitrum, not by a deployed multichain signer or public renewal API. The existing Polygon/USDC V4 path remains separate.
// Illustrative decision logic, NOT a public RecurCrypto endpoint.
const server = await readTrustedSubscriptionSnapshot(tenant, subscriptionId);
if (server.cancelled || server.paused || server.policyFeeBps !== 0) {
return { status: "blocked", reason: "RENEWAL_NOT_AVAILABLE" };
}
if (server.nextPayment !== request.nextPayment || server.now !== verifiedClock) {
return { status: "blocked", reason: "STALE_CONSENT" };
}
// A preview is never a signed quote, paid receipt or charge.Testing a multichain USDC checkout without moving funds
The local-only V5 merchant sandbox lets a signed-in merchant create a draft plan, activate simulated Polygon, Base and Arbitrum fixtures, compare deterministic route costs, and pause new checkout previews. The scenario selector can model sufficient balance, a required approval, insufficient USDC, insufficient native gas, and four Base-only failures: missing gas, missing USDC, approval gas shortage and a network-fee spike. These test whether the server automatically falls back to a permitted lower-cost viable chain, with no bridge, swap or user-selected network. No wallet is connected, no contract is deployed and no payment intent, signature, receipt or transaction is created.
The sandbox endpoints are intentionally inaccessible outside localhost with a local PostgreSQL URL and an explicit simulation flag. A successful fixture preview is not evidence that a payer owns funds or has consented. Production integrations must replace these fixtures with authenticated wallet evidence, verified EIP-712 consent, a secure signer, transactional PostgreSQL checks and locally tested EVM reconciliation before enabling a network. Free prelaunch remains 0% platform fee; a future 1% rate is inactive and would require fresh consent. Network gas is separate.
To restrict a V5 local simulation to specific chains, the merchant may submit allowedRailIds to POST /api/local/v5/plans, for example ["base-usdc-v5-sim", "arbitrum-usdc-v5-sim"]. The server accepts only a nonempty subset of its three simulated USDC fixtures; unknown chains, token contracts, duplicated entries and a live asset cannot be added by the client. The plan snapshot and any multi-price offer preserve that exact selection. If Base runs out of fictitious gas and Arbitrum is allowed, the deterministic preview can choose Arbitrum; if only Base is allowed, it blocks rather than silently routing elsewhere. No bridging, swapping, blockchain signing, real funds or live multichain payments occur. Existing three-fixture local offers remain readable, and all V4 terms and consents are unchanged. Free 0% prelaunch remains effective, future 1% inactive, with network gas separate.
The payer-facing /local/v5/checkout/... demo now offers an optional Prepare simulated checkout automatically action. It reuses the existing signed-session API to bind the current wallet, compare the merchant-allowed Polygon/Base/Arbitrum USDC fixtures, create one immutable local quote only if a route is viable, and independently audit its price, network fee, policy version and fingerprint. A failed or uncertain response stops the sequence: the payer checks authenticated status rather than blindly creating a second quote. The final checkbox and demo acknowledgement remain separate, explicit user actions. No wallet network choice, on-chain signature, payment, recurring charge or receipt is created. Free is 0% during prelaunch; future 1% is inactive and gas is separate.
For local checkout-link creation, send a unique Idempotency-Key (8–128 safe characters) to POST /api/local/v5/plans/{id}/links. Retrying the same key never creates a second link. The server stores only the token hash, so a lost response cannot reveal the original secret link: inspect the merchant link list, revoke the orphaned link and use a new key. This localhost-only endpoint does not accept payments and is not part of the public V4 API.
To rehearse a payer choosing between different fixed prices or billing intervals, the local merchant can submit { "offerPlanIds": ["origin-plan-id", "alternative-plan-id"] } to that same localhost link endpoint, with a fresh idempotency key. The two to five plans must belong to the same merchant and remain active with unchanged commercial snapshots. The resulting /local/v5/offer/... link shows only the permitted simulated amounts and periods. A signed-in payer selects one price; the server atomically creates a single-use, wallet-bound demo checkout link. A changed plan, reused offer or competing payer blocks the selection. For a payer who sets a gas-inclusive or 30/90/365-day limit, the local offer selection also sends a version-2 constraints object. The server checks that limit using the locked plan amount and a conservative maximum simulated gas per cycle; it does not accept client gas quotes or turn a hypothetical comparison into a charge. The old version-1 plan-only preference remains compatible. This does not issue EIP-712 consent, start billing, or create a receipt.
For local product safety, authenticated merchants can inspect activity with GET /api/local/v5/products/{id}. A product may be retired with PATCH /api/local/v5/products/{id} and { "action": "retire", "expectedRevision": 1 }. This atomic local-only operation archives the product and revokes every live unquoted offer plus its selected child session. If any selected offer already has a quote, the entire operation is rejected and no records are changed. It never cancels V4 authorizations or sends funds. The normal archive action is allowed only when no live offers or selections remain. Otherwise the merchant must use explicit atomic retirement; historical quoted decisions are never silently rewritten.
A merchant can prepare a revised product description without editing an existing checkout: in the local V5 dashboard, open New version: name, description and prices, supply a distinct slug and revised product copy, then choose which previously attested prices to retain. The new version receives its own product ID; selecting no prices creates a draft to populate later. Previous payment links, prices, approvals and consent records remain unchanged. The local API accepts optional name and description with the clone request, validates them server-side and binds them to an idempotency digest. This is a local simulation, not a blockchain deployment or an enabled recurring payment.
Local V5 product versions are immutable: use POST /api/local/v5/products/{id} with Idempotency-Key and { "action": "clone", "expectedRevision": 1, "slug": "plan-v2", "selectedPlanIds": [] } to create a new product identity without changing old checkout offers or approvals. Optionally retain up to five existing, still-eligible source price IDs; then attach other current prices to the new product. The server checks tenant ownership, current price snapshots, policy version and idempotency in one local database transaction. Cloning is not a price edit or an authorization renewal. A fee change would require fresh informed consent; Free remains 0% in prelaunch, future 1% is disabled, and gas is separate. These routes remain local simulation only.
For a newly minted local V5 multi-price offer, first inspect the public offer, authenticate the payer, then call POST /api/local/v5/offers/{token} with { "action": "compare_all", "scenario": "funded" }. Review the simulated prices and gas separately, choose one price explicitly, and submit planId, selectionProof for that price and constraints with version: 3, the same fixture scenario and requireViableRoute: true. New offers reject bare selections and V1/V2 downgrades before creating any checkout. Proofs expire after two minutes and are invalid after a local process restart; repeat comparison rather than reusing them. Old stored local offers preserve their historical selection policy. This is not an EIP-712 signature, real payment or PostgreSQL certification. Free 0% prelaunch, future 1% inactive, gas separate and no live networks.
For standalone local V5 links and multi-price offers, POST /api/local/v5/plans/{id}/links requires a 256-bit client-held clientToken, an Idempotency-Key and an explicitly acknowledged, current consent object. The consent binds Free 0% prelaunch, inactive future 1%, separate gas and zero live networks. The server namespaces retries by operation type and consent policy; a timeout can be retried with the same key and bearer, but no payment, receipt or chain signature is created. Older V4 authorizations are unchanged. This endpoint works on localhost only and is not a public production API.
For product-backed demo checkout links, each new create_offer and rotate_offer request must include a fresh, explicitly acknowledged consent object matching the current server-side commercial policy. Obtain its shape from the local merchant UI or the local policy adapter; do not invent fee or chain values. The server rejects missing, stale or altered consent before database access, and rotation requires a new acknowledgement even when the previous link was valid. A successful response identifies the consent and policy versions; neither is a payment authorization. Free remains 0% in prelaunch, the future 1% is inactive, gas is separate and V5 has zero live chains and assets. Existing V4 authorizations are unchanged.
A localhost-only V5 product catalog now groups two to five existing active demo prices without changing their historical amounts, billing periods or approvals. A signed-in merchant can create a product with POST /api/local/v5/products and an Idempotency-Key, attach each existing V5 price with POST /api/local/v5/products/{id} using { "action": "attach_price", "planId": "..." }, then request one demo multi-price offer with { "action": "create_offer" } and a fresh idempotency key. The offer creation transaction rechecks merchant ownership, immutable price snapshots and product status. Archiving is rejected while live offers exist. Existing open product links are also checked against active product status and immutable price membership before display or selection. Use retirement to revoke unquoted links atomically; quoted decisions remain protected. No historical quotes or consents are rewritten. All these routes require loopback HTTP, a local PostgreSQL URL, the explicit simulation flag and an authenticated merchant session. They cannot charge funds or activate V5 chains.
If the payer loses the response after selecting a price, the same authenticated wallet can explicitly call POST /api/local/v5/offers/{token} with { "action": "recover" }. This rotates the child checkout bearer link (the previous link becomes invalid), preserves the same session and price, and allows at most two recoveries. It fails closed after a quote, expiration, revocation, wallet change or plan revision. Before any quote, the payer can use { "action": "cancel" } to revoke the selected child session; the merchant can revoke an unquoted selection in the local panel. Once a quote exists, cancellation must follow the checkout decision flow. These are localhost-only rehearsals, not payment authorization, refund or cancellation of a live subscription.
The local multi-price demonstration now checks the selected offer again inside the same serializable transaction that calculates and stores the simulated quote. Before showing a route, the server checks that the original offer has not been revoked, the product remains active, the signed-in payer owns the selected child session, and the plan revision, price, interval and gas ceiling still match the immutable offer. The intended database lock order is product, offer, child session, then plan; PostgreSQL concurrency testing is still required to certify this behavior. If any condition changes, the checkout returns a blocked state rather than silently switching to another price or chain. A successful local quote includes the server-verified amount and interval, but it is not an EIP-712 authorization, a receipt, an actual USDC balance or evidence of settlement. Free 0% prelaunch remains effective; a future 1% fee is disabled and requires renewed consent. Gas remains separate.
For current public API boundaries, continue with the API reference or the stablecoin recurring payments guide.
Minimal sequence
1. POST /api/v1/auth/keys
2. POST /api/v1/plans
3. POST /api/v1/checkouts
4. GET /api/v1/subscriptions
5. GET /api/v1/events