Stablecoin Subscriptions

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.

Stage	What StablePay handles	What the merchant should do
Create subscription	Creates the subscription and returns a hosted checkout URL for initial authorization.	Store the `subscription_id` and redirect the customer to checkout.
Initial authorization	Customer 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 cycle	Creates an invoice for each period and attempts payment when due.	Update local state from invoice and subscription webhooks.
Renewal success	Payment succeeds, invoice is paid, and subscription remains active.	Extend or confirm entitlement and optionally notify the customer.
Renewal failure	Subscription can enter past_due and automatic retries begin.	Apply grace period, feature limits, or reminder policy.
Cancellation	Supports immediate cancellation or cancellation at period end.	Sync the cancellation state and end entitlement at the correct time.

How it works

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

Billing start modes

Mode	Description	Best for
Start now and charge immediately	The first invoice is due during checkout. The subscription becomes active after successful payment.	Standard paid subscriptions that start today.
Start now and charge later	The customer only authorizes during checkout, and the first invoice is charged on a future billing date.	Flows where service starts before first billing.
Trial	The 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:

Retry	Timing
1	5 minutes after failure
2	30 minutes after failure
3	2 hours after failure
4	20 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 type	Behavior	What the merchant should do
Cancel at period end	The 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 now	The 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

Event	When it fires	What the merchant should do
`subscription.created`	A subscription object is created successfully.	Create a local pending record and store customer, plan, subscription_id, and checkout_url.
`subscription.trialing`	The customer completes initial authorization and the subscription enters trial.	Grant trial access and show trial start/end timing plus future auto-charge context.
`subscription.active`	The 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_due`	The latest amount due failed to charge and the subscription is retrying.	Mark renewal failure, apply grace or restriction policy, and trigger one reminder.
`subscription.updated`	Mutable subscription fields change, such as cancel-at-period-end settings.	Sync cancellation state and show clear period-end cancellation messaging.
`subscription.canceled`	The subscription is terminated and will not generate new cycles.	End entitlement or mark access to expire, and stop renewal reminders.
`subscription.incomplete_expired`	The 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

Event	When it fires	What the merchant should do
`invoice.created`	A first-period or renewal invoice is created.	Store invoice_id, amount, currency, and billing period.
`invoice.paid`	The invoice is paid successfully.	Mark the invoice paid and extend or confirm entitlement.
`invoice.payment_failed`	First-period payment, renewal payment, or retry attempt fails.	Record failure and apply reminder or access policy based on subscription state.
`refund.created`	A refund request or refund record is created.	Create a local refund record and mark refund processing.
`refund.succeeded`	The refund completes successfully.	Mark refund succeeded and update order or invoice refund display.
`refund.failed`	Refund processing fails.	Mark refund failed and route to support or retry handling based on the failure reason.

State model

Key subscription state transitions:

Transition	Meaning
`incomplete` -> `incomplete_expired`	Initial authorization was not completed within the valid window.
`active` -> `past_due`	Renewal charge failed.
`past_due` -> `active`	Automatic retry succeeded.
`past_due` -> `canceled`	Retries were exhausted and the system canceled the subscription.
`active` / `trialing` / `past_due` -> `canceled`	Customer 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.

Pay In

Pay Out

Corporate Cards

Refunds

Reference

When to use it

Try the demo

Subscription demo storefront

Product model

How it works

Billing start modes

Retry and dunning

Cancellation

Webhook events

Subscription events

Invoice and refund events

State model

Launch guidance

New merchants launching subscriptions

Merchants adding stablecoin billing to existing card subscriptions

Payment methods, currency, and networks

Important notes

​When to use it

​Try the demo

Subscription demo storefront

​Product model

​How it works

​Billing start modes

​Retry and dunning

​Cancellation

​Webhook events

​Subscription events

​Invoice and refund events

​State model

​Launch guidance

​New merchants launching subscriptions

​Merchants adding stablecoin billing to existing card subscriptions

​Payment methods, currency, and networks

​Important notes

​Related pages

When to use it

Try the demo

Product model

How it works

Billing start modes

Retry and dunning

Cancellation

Webhook events

Subscription events

Invoice and refund events

State model

Launch guidance

New merchants launching subscriptions

Merchants adding stablecoin billing to existing card subscriptions

Payment methods, currency, and networks

Important notes

Related pages