Subscriptions on OrcaRail: Auto-Charge and Multichain

March 25, 2026 — OrcaRail supports recurring subscriptions in the same API-first model as one-off payments: you create a subscription, we track billing periods, and payers complete each cycle—either by opening a payment link or by auto-charge, where they authorize us to pull stablecoins each period after a one-time on-chain approval.

Why subscriptions on OrcaRail

Subscriptions are for SaaS, memberships, retainers, and any product billed on a fixed interval (day, week, month, year) with optional trials, cycle limits, and cancellation rules. You use the same Payments Auth as the rest of the platform, and you can react to lifecycle events with subscription webhooks.

Two ways to collect: payment links vs auto-charge

• send_payment_link (default): Each billing cycle, the payer gets a payment link (email and/or hosted flow). They pay when they open the link—familiar for crypto checkout and easy to combine with Relay routes and wallet choice.
• auto_charge: The payer pre-authorizes OrcaRail’s hot wallet to pull the period amount on each renewal. After setup, renewals do not require the payer to click a new link each time—as long as balance and authorization remain valid.

Create and configure collection with POST /api/v1/subscriptions; list, update, pause, and cancel with manage subscriptions. Full request fields and examples live in those guides.

Auto-charge: how we handle it

1. Merchant creates a subscription with collection_method: "auto_charge" and the usual amount, interval, token_id, network_id, and payer contact fields.
2. Payer opens the subscription or first-cycle payment experience. They see the total approval scope (for example, the sum of upcoming charges you ask them to cover) and signs an on-chain authorization:
   • On EVM chains, that is a standard ERC-20 approve(spender, amount) to our hot wallet as spender.
   • On Solana, the analogous step is SPL token delegation of at least one period’s amount to our Solana hot wallet.
3. Payer calls the public POST /api/v1/subscriptions/:id/approve-auto-charge endpoint with the allowance (or delegation) transaction hash, payer_wallet_address, payer_network_id, and payer_token_id. No merchant API key is required—the payer proves intent by having signed the chain transaction.
4. OrcaRail verifies on-chain that the allowance or delegation is at least one billing cycle for the expected hot wallet before marking auto-charge approved. Before each pull, we can re-check authorization so transient RPC issues are not confused with a revoked allowance.
5. Each billing cycle, the billing pipeline attempts the pull (EVM transferFrom-style flow from the payer to settlement; Solana uses the delegated balance). On success, the period advances; on repeated failure (e.g. insufficient balance or revoked approval), the subscription can move to past_due and the payer is notified—you can listen for webhooks such as subscription.payment_link.payment_failed or subscription.past_due as described in Auto-charge and webhooks.

Revoke and fallback: If the payer revokes on-chain, later pulls fail. They can also complete POST .../revoke-auto-charge after revoking so we record the state and can switch collection to send_payment_link, with email guidance to manage the subscription and pay via links again. Details are in Auto-charge and Manage subscriptions.

Security and clarity: Only the wallet that completed approval is used for pulls; we align UX with clear totals and cycle counts so payers know what they authorized. For very long or open-ended plans, consider capping approved amounts and refreshing approval periodically, or staying on payment links—see Auto-charge.

Multichain: how it fits subscriptions

• Merchant anchor: Every subscription is created with a network_id and token_id that define how the subscription is priced and settled in API terms—the “home” network and asset for that plan.
• Payer context for auto-charge: Auto-charge stores payer_network_id and payer_token_id—the network and token where the payer actually set allowance or delegation. That can differ from the subscription’s primary fields when payers fund from another supported chain or asset, consistent with how quotes and checkout resolve payer-side routes.
• Relay-aligned coverage: Supported networks and currencies stay aligned with Relay; when Relay expands chains and tokens, our inventory follows. We summarized that model in Supported networks and currencies: powered by Relay.
• Where proceeds land: Merchants still configure withdrawal addresses per chain type (and can override per payment where supported). For the full picture of multichain withdrawals and multiple addresses per chain, see OrcaRail is multichain: withdrawals and Relay alignment.

Summary

Topic	OrcaRail behavior
Collection	send_payment_link per cycle, or auto_charge with on-chain approval
Auto-charge	EVM ERC-20 approve or Solana SPL delegate → public approve API → on-chain verification → per-cycle pull, with past_due and webhooks on failure
Revoke	On-chain revoke + optional revoke-auto-charge; can fall back to payment links
Multichain	Subscription network_id / token_id; payer approval stores payer_network_id / payer_token_id; Relay-aligned networks; per-chain-type withdrawals

Subscriptions on OrcaRail combine RESTful subscription resources with non-custodial payer authorization for auto-charge and multichain payouts—without giving up the hosted pay experience and APIs you already use for one-off payments.

---

OrcaRail App · Docs · Relay