Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Stablecoin Subscriptions is StablePay’s product for recurring stablecoin billing. It helps merchants manage the full subscription lifecycle: creating subscriptions, completing initial wallet authorization, charging automatically by billing cycle, handling renewal failures and retries, canceling subscriptions, and synchronizing business state through webhooks. The product is different from Stablecoin Checkout. Checkout is for one-time payments. Subscriptions are for repeat billing. The customer first completes an on-session wallet authorization in StablePay Hosted Checkout. StablePay then creates invoices for each billing cycle and attempts off-session renewal charges using the saved authorization.

​
When to use it

Use Stablecoin Subscriptions when you have an ongoing commercial relationship with the customer. Common fit examples include:
  • Monthly or annual SaaS plans.
  • Memberships, subscriptions, and paid communities.
  • Premium access to software, content, games, or services.
  • Retainers, recurring support plans, or account-managed service packages.
  • Usage models where access should continue only while billing remains active.

​
Try the demo

You can try a demo subscription storefront here:

Subscription demo storefront

Open the demo storefront to see the initial StablePay Subscriptions Checkout authorization flow.
For a single customer bill that is not part of a recurring plan, use Invoicing. For one-time checkout, use Stablecoin Checkout.

​
Product model

The subscription model is built around initial authorization, billing-cycle invoices, automatic renewal, and webhook-driven entitlement.
StageWhat StablePay handlesWhat the merchant should do
Create subscriptionCreates the subscription and returns a hosted checkout URL for initial authorization.Store the subscription_id and redirect the customer to checkout.
Initial authorizationCustomer selects a wallet, authorizes on-chain, and may pay the first period.Wait for webhooks. Do not grant final paid access from creation alone.
Billing cycleCreates an invoice for each period and attempts payment when due.Update local state from invoice and subscription webhooks.
Renewal successPayment succeeds, invoice is paid, and subscription remains active.Extend or confirm entitlement and optionally notify the customer.
Renewal failureSubscription can enter past_due and automatic retries begin.Apply grace period, feature limits, or reminder policy.
CancellationSupports immediate cancellation or cancellation at period end.Sync the cancellation state and end entitlement at the correct time.

​
How it works

  1. Your backend creates a subscription for a customer and plan, with amount, billing interval, start mode, and redirect context.
  2. StablePay returns a hosted checkout URL for the first authorization or first payment.
  3. The customer opens StablePay Hosted Checkout, chooses a wallet, confirms details, signs the authorization, and pays the first invoice if required.
  4. StablePay saves the reusable authorization / payment method for future billing cycles.
  5. When each billing cycle arrives, StablePay creates an invoice and attempts an off-session renewal charge.
  6. StablePay sends webhooks for subscription, invoice, and payment outcomes.
  7. Your system grants, extends, restricts, or ends customer access based on webhook events.

​
Billing start modes

ModeDescriptionBest for
Start now and charge immediatelyThe first invoice is due during checkout. The subscription becomes active after successful payment.Standard paid subscriptions that start today.
Start now and charge laterThe customer only authorizes during checkout, and the first invoice is charged on a future billing date.Flows where service starts before first billing.
TrialThe customer only authorizes during checkout, and the first invoice is created and charged after the trial ends.Free trials, delayed conversion, or try-before-pay flows.

​
Retry and dunning

Automatic recovery after a failed renewal is called dunning. Renewal payments can fail because of wallet balance, authorization, network, or compliance conditions. When the latest amount due cannot be charged, StablePay can move the subscription to past_due, send webhooks, and apply the default retry strategy. Default retry timing:
RetryTiming
15 minutes after failure
230 minutes after failure
32 hours after failure
420 hours after failure
If any retry succeeds, the invoice becomes paid, the subscription can return to active, and the next billing cycle continues. If all retries fail, the subscription automatically becomes canceled and no new billing cycles are generated. Merchants should avoid notifying customers on every retry failure. A better pattern is to send one balance or wallet reminder after the first failure, then apply your product policy for grace periods, feature restrictions, or temporary continued access.

​
Cancellation

StablePay supports two cancellation patterns:
Cancellation typeBehaviorWhat the merchant should do
Cancel at period endThe current billing period remains valid. The subscription becomes canceled when the period ends.Show that the subscription will end at period end, then remove entitlement after current_period_end.
Cancel nowThe subscription ends immediately.End entitlement immediately or enter your refund / support workflow.
Cancel-at-period-end usually updates cancellation fields first, such as cancel_at_period_end=true. The subscription is not actually ended until subscription.canceled is received. Merchants should not treat subscription.updated as final cancellation.

​
Webhook events

Webhooks are the source of truth for subscription integrations. Use subscription.id and event_id for idempotency, and apply the latest object from the webhook payload to avoid state rollback from out-of-order events.

​
Subscription events

EventWhen it firesWhat the merchant should do
subscription.createdA subscription object is created successfully.Create a local pending record and store customer, plan, subscription_id, and checkout_url.
subscription.trialingThe customer completes initial authorization and the subscription enters trial.Grant trial access and show trial start/end timing plus future auto-charge context.
subscription.activeThe subscription enters a renewable state, or recovers from past_due after a successful retry.Grant or restore active entitlement. Use invoice.paid to confirm payment for the period.
subscription.past_dueThe latest amount due failed to charge and the subscription is retrying.Mark renewal failure, apply grace or restriction policy, and trigger one reminder.
subscription.updatedMutable subscription fields change, such as cancel-at-period-end settings.Sync cancellation state and show clear period-end cancellation messaging.
subscription.canceledThe subscription is terminated and will not generate new cycles.End entitlement or mark access to expire, and stop renewal reminders.
subscription.incomplete_expiredThe customer did not complete initial authorization within the valid window, such as 30 minutes.Mark onboarding failed / expired and allow the customer to start a new subscription.

​
Invoice and refund events

EventWhen it firesWhat the merchant should do
invoice.createdA first-period or renewal invoice is created.Store invoice_id, amount, currency, and billing period.
invoice.paidThe invoice is paid successfully.Mark the invoice paid and extend or confirm entitlement.
invoice.payment_failedFirst-period payment, renewal payment, or retry attempt fails.Record failure and apply reminder or access policy based on subscription state.
refund.createdA refund request or refund record is created.Create a local refund record and mark refund processing.
refund.succeededThe refund completes successfully.Mark refund succeeded and update order or invoice refund display.
refund.failedRefund processing fails.Mark refund failed and route to support or retry handling based on the failure reason.

​
State model

Key subscription state transitions:
TransitionMeaning
incomplete -> incomplete_expiredInitial authorization was not completed within the valid window.
active -> past_dueRenewal charge failed.
past_due -> activeAutomatic retry succeeded.
past_due -> canceledRetries were exhausted and the system canceled the subscription.
active / trialing / past_due -> canceledCustomer or merchant canceled immediately or at period end.
Do not rely only on frontend redirect results to determine subscription state. Business state should be webhook-driven.

​
Launch guidance

​
New merchants launching subscriptions

Start with “start now and charge immediately” to validate conversion, customer support load, webhook processing, and reconciliation. Add trial after activation and renewal handling are stable. Add “start now and charge later” only when the business needs aligned billing dates or future first-charge behavior.

​
Merchants adding stablecoin billing to existing card subscriptions

Offer StablePay as a parallel subscription payment option instead of replacing existing card subscriptions directly. When a customer chooses to switch, create a new StablePay subscription and set the original card subscription to cancel at period end to avoid charging twice for the same entitlement.

​
Payment methods, currency, and networks

Stablecoin Subscriptions currently support creating subscriptions in USD, with stablecoin charging and settlement in USDT / USDC. Subscription flows can support wallets such as MetaMask, Binance Wallet, OKX Wallet, and WalletConnect, and networks such as Ethereum, BNB Smart Chain, and Solana. StablePay Subscriptions Checkout does not support scan-to-address or copy-address transfer payment. Recurring billing requires the customer to authorize future charges through a supported connected-wallet flow. Actual availability can vary by merchant configuration, environment, and compliance requirements. For complete coverage, see Supported Wallets, Supported Networks, and Currencies & Auto Currency Conversion.

​
Important notes

  • Initial wallet authorization is required before automatic renewal charges can occur.
  • Subscriptions Checkout supports connected-wallet authorization only and does not support QR/address transfer payment.
  • subscription.created does not mean the customer has authorized or paid. Grant final paid access from webhook outcomes.
  • subscription.active means the subscription is in a renewable state, but invoice.paid is the more direct signal that money was received for a billing period.
  • Refunds happen against payments, not directly against subscription objects.
  • Webhooks should be treated as the source of truth for entitlement, service access, and internal billing state.
Last modified on April 23, 2026