Skip to main content

Migration guide

This guide explains what to do — and what to expect — as OrcaRail rolls out the non-custodial stack. The rollout is phased and opt-in per chain; no existing link or subscription is forced to migrate.

For merchants​

What changes in your integration​

Nothing required. The API response shape for payment links and subscriptions is additive during the transition:

  • Payment links get a new receiver.contract_address field (same value as the existing deposit address for on-chain-receiver links).
  • Subscriptions get auto_charge.approval_spender_address that points at the on-chain SubscriptionHub instead of a hot wallet. This field already exists in Auto-charge; only the value changes.
  • Webhooks fire at the same moments (payment.succeeded, subscription.charge.*, etc.).

What changes in the dashboard​

  • A "Non-custodial" badge appears on payment links and subscriptions using the new stack.
  • A banner on existing active subscriptions prompts you to offer migration to your payer at the next renewal.
  • A per-chain toggle in settings lets you opt in to non-custodial receivers chain-by-chain once the chain is canary-clean (Base first).

When to act​

  • Phase 1 (Base): nothing required. New links on Base automatically use the new receiver once your organization flag flips.
  • Phase 2: when the banner appears, forward the renewal notice to your subscribers so they re-sign approve to the new SubscriptionHub. Email template is pre-filled.
  • Phase 3 (other EVM chains): same pattern as Base, per chain.
  • Phase 4 (Solana): same pattern, triggered on your merchant's next SOL subscription cycle.
  • Phase 5 (Bitcoin): onboard a BTC signer (xpub) in the dashboard so new BTC links can use 2-of-2 multisig. See Bitcoin considerations.
  • Phase 7: if any of your subscribers are still on the legacy custodial path, contact them with the final 30-day notice we provide.

Legacy paths​

Existing legacy payment links settle as before until they expire. Existing legacy subscriptions continue pulling from the custodial hot wallet until migration or cancellation. No forced migration.

For payers​

One-off payments​

Nothing changes. You see the same payment link, the same address, the same wallet UI. Under the hood, the receiver is a smart contract instead of a server-held wallet — but your flow is identical.

Subscriptions​

The setup flow is the same as today: connect your wallet, sign approve (EVM) or SPL Approve (Solana), and you are done. The only observable difference is that the spender is a contract address (SubscriptionHub) instead of an OrcaRail hot wallet. Your wallet will show a clear indication that the spender is a contract.

Revoke at any time by revoking the allowance in your wallet's token-approvals UI. After revoke, the next scheduled charge will fail and you will receive an email. You can restart by signing a new approve.

If you are an existing subscriber​

When the migration banner appears in your subscription management page, you will see an offer to migrate. Clicking it:

  1. Prompts you to revoke the old allowance (optional; it becomes inert once migrated).
  2. Prompts you to sign a new approve to the SubscriptionHub contract.

That is all. Your subscription continues uninterrupted.

If you do not migrate, your subscription continues on the legacy path until cancellation or until the end of the final migration window announced in Phase 7.

For integrators (SDK users)​

Additive fields​

The API response shape is fully backward compatible. New fields:

  • payment_intent.receiver.contract_address
  • subscription.auto_charge.approval_spender_address (value may change to contract address)
  • subscription.on_chain.* (subscription hub address, chain id, subscription bytes32 id)
  • Webhooks add a non_custodial: true flag where applicable.

Deprecations​

No fields are removed during the transition. In Phase 7, fields that describe custodial signer addresses will be marked deprecated in the API reference and removed in a subsequent major SDK release (@orcarail/[email protected]) with 90 days of notice.

Webhook compatibility​

Event types and payload shapes for payment.*, subscription.*, and webhook.* are unchanged. The non-custodial path emits the same events at the same moments.

Revoking mid-cycle​

If a payer revokes their allowance between cycles:

  1. The next charge() emits ChargeSkipped(InsufficientAllowance) on-chain.
  2. The indexer updates the subscription to past_due.
  3. The existing subscription-insufficient-allowance.hbs email template fires to the payer.
  4. The merchant webhook subscription.payment_failed fires.
  5. The payer can restart the subscription by re-approving through the subscription management page.

Behavior matches what you have today under Auto-charge. Only the plumbing changed.

Cross-chain considerations​

If a payer pays on a different chain than the merchant's settlement chain, Relay handles the bridge (see Withdrawal strategy). The non-custodial stack changes who calls Relay (the receiver or the keeper EOA, not a custodial signer) without changing the bridge path itself.

Timeline reference​

See Roadmap for live status. Dates are targets, not commitments.

PhaseWhat you can expect
1Base payment links become non-custodial (opt-in canary, then default)
2EVM subscriptions migrate on renewal
3Ethereum, Arbitrum, Optimism, Polygon go live
4Solana payment links and subscriptions migrate
5Bitcoin moves to 2-of-2 multisig (BTC subscriptions remain unsupported)
6Optional: decentralized keeper. No change for merchants/payers.
7Legacy custody paths deleted; final migration notice for any holdouts

See also​