Subscriptions
Zyrox supports recurring crypto payments (subscriptions). The customer approves the billing once, pays the first period right away, and every next period is charged automatically in the same token and network.
How Subscriptions Work
- Customer opens a subscription payment link: the URL includes the
subscriptionparameter with the billing interval - Customer connects a wallet and approves the billing: one token approval lets the Zyrox subscription contract (SubscriptionRouter) charge up to 24 billing amounts, for example about two years of monthly payments
- The first payment is taken in the same step: the contract moves the first amount from the customer's wallet straight to the merchant's address. This activates the subscription
- Zyrox records the subscription: payer address, network, token and amount
- At each billing interval, Zyrox asks the contract to charge the next period. The contract moves exactly the agreed amount from the customer's wallet to the merchant's address. Zyrox never holds the funds
- On successful charge, the merchant receives a webhook and the customer receives an email
- On failed charge (for example, low balance or the approval was revoked), Zyrox retries up to 5 times. After 5 consecutive failures the subscription is paused and the merchant is notified by email
Supported Tokens and Networks
Recurring billing works with USDT and USDC on the EVM networks shown at checkout. Bitcoin and Tron payments are available as one-time payments.
Buyer Approval and Network Fees
| Step | Who sends the transaction | Who pays the network fee (gas) |
|---|---|---|
| Token approval | Customer | Customer |
| First payment | Customer | Customer |
| Every renewal | Zyrox billing wallet | Zyrox |
- The customer needs a small amount of the network's native coin (for example ETH) in the wallet to pay gas for the approval and the first payment. Checkout warns if there is not enough.
- One approval covers up to 24 billing amounts. When it is used up or revoked, renewals stop until the customer approves again.
- Each renewal must match the agreed amount exactly. The contract refuses a charge that is too early, larger than agreed, or not covered by the approval or balance.
Cancelling a Subscription
A customer can stop a subscription in two ways:
- On the Zyrox subscriptions page (
https://app.zyrox.io/pay/subscriptions?address={payer_wallet_address}). Zyrox stops future charges immediately. The link is in every subscription email. - In the wallet, by revoking the token approval for the subscription contract. Without an approval the contract cannot charge, so renewals fail and the subscription is paused after 5 attempts.
Cancelling on the Zyrox page does not remove the token approval from the customer's wallet. The customer can also revoke it in the wallet at any time.
Billing Intervals
| Interval | Parameter Value | Duration |
|---|---|---|
| Hourly | hourly | 1 hour (for testing) |
| Daily | daily | 24 hours |
| Weekly | weekly | 7 days |
| Monthly | monthly | 30 days |
| Yearly | yearly | 365 days |
Tip: Use the
hourlyinterval for testing subscription flows without waiting days between charges.
Creating Subscription Payment Links
To create a subscription, add the subscription query parameter to a standard payment link:
https://app.zyrox.io/pay/{merchant}/{invoice}?amount=XX.XX&subscription={interval}
Examples
Monthly subscription for $29.99
https://app.zyrox.io/pay/my-store/SUB-PREMIUM-001?amount=29.99&subscription=monthly
Weekly subscription with specific token and network
https://app.zyrox.io/pay/my-store/SUB-WEEKLY-001?amount=9.99&subscription=weekly&token_symbol=USDT&network_id=3
Yearly subscription ($99/year)
https://app.zyrox.io/pay/my-store/SUB-ANNUAL-001?amount=99&subscription=yearly
Test subscription (hourly, testnet)
https://app.zyrox.io/pay/my-store/SUB-TEST-001?amount=1&subscription=hourly&test=true
Query Parameters
| Parameter | Required | Description |
|---|---|---|
amount | Yes | Billing amount in USD per interval |
subscription | Yes | Billing interval: hourly, daily, weekly, monthly, yearly |
token_symbol | No | Limit to a specific token (e.g., USDT, USDC) |
network_id | No | Limit to a specific blockchain network |
email | No | Customer email, enables email notifications |
test | No | Set to true for testnet subscriptions |
package_id | No | Custom package/product ID stored in metadata |
Subscription Lifecycle
Statuses
- Pending: subscription created, waiting for the approval and first payment
- Active: first payment received, renewals will be charged
- Paused: automatically paused after 5 consecutive failed charge attempts
- Cancelled: cancelled by the customer
Flow
[Pending] -> (approval + first payment) -> [Active] -> (renewals)
|
(5 failed attempts) -> [Paused]
|
(customer cancels) -> [Cancelled]
Managing Subscriptions (Customer Side)
Customers can view and manage their subscriptions at:
https://app.zyrox.io/pay/subscriptions?address={payer_wallet_address}
On this page, customers can:
- View all active subscriptions linked to their wallet address
- See billing history: past payments, next billing date
- Cancel a subscription: stops future charges immediately
This URL is included in all subscription-related email notifications, so customers always have easy access to manage their subscriptions.
Email Notifications
If the customer provides an email address during the first payment (via the email query parameter or on the checkout page), Zyrox sends automated email notifications for subscription events:
Subscription Created
Sent after the first payment is confirmed. Includes:
- Merchant name and subscription details
- Payment amount and cryptocurrency used
- Billing interval and next billing date
- Transaction ID with a link to the block explorer
- Link to manage or cancel the subscription
Subscription Renewed
Sent after each successful renewal. Includes:
- Payment confirmation with amount and transaction ID
- Next billing date
- Link to manage or cancel the subscription
Subscription Payment Failed
Sent when a renewal attempt fails. Includes:
- Error details
- Current attempt count (e.g., "Attempt 2 of 5")
- Warning that the subscription will be paused after 5 failures
Merchant Notifications
Merchants (account managers) receive email notifications when:
- A subscription payment fails: subscription ID, attempt count and error details
- A subscription is paused after the maximum number of failed attempts
API Integration (Stripe-Compatible)
If you use the Stripe-compatible API, subscriptions are created via checkout sessions with mode: 'subscription':
const session = await stripe.checkout.sessions.create({
mode: 'subscription',
line_items: [{
price_data: {
currency: 'usd',
product_data: { name: 'Monthly Plan' },
unit_amount: 2999, // $29.99 in cents
recurring: { interval: 'month' },
},
quantity: 1,
}],
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel',
});
Webhook events for subscriptions:
checkout.session.completed: first subscription paymentinvoice.paid: each renewalinvoice.payment_failed: a failed renewal attemptcustomer.subscription.updated: the subscription was paused after failed attemptscustomer.subscription.deleted: the subscription was cancelled
Renewal Scheduler
A background scheduler checks every 5 minutes for subscriptions that are due.
When a subscription is due:
- Zyrox calls the subscription contract to charge the agreed amount in the same token and network as the first payment
- The contract checks the timing, the approval and the customer's balance, then moves the funds from the customer's wallet to the merchant's address
- On success: Zyrox records the payment, sends integration callbacks and webhooks, and emails the customer
- On failure: Zyrox increases the failed attempt counter and sends a failure notification
After 5 consecutive failures, the subscription is automatically paused to prevent further charge attempts. The merchant is notified by email.
Need help with subscriptions? See Invoices and Payment Rules for how payments are matched, Fees for pricing, the Payment Links guide for URL parameters, or the API Integration guide for programmatic subscriptions.
© 2026 Zyrox. Simple and secure crypto payment processing.