Recurring plans

Set up automated subscription billing with scheduled USDC payments.

v1 architecture, awaiting audit sign-off. Recurring plans are part of v1 and ship via a customer-signed ERC-7715 grant to the public recurring-pull executor contract. The customer signs once at subscription setup; the merchant (or any permissionless keeper) redeems the grant on each cycle. The caveat enforcer verifies every pull against the pre-agreed per-charge cap, frequency window, and expiry — JoPay never holds a signing key. Enabling the feature in the UI is gated on the caveat-enforcer suite audit.

What are recurring plans?

Recurring plans let you charge a customer on a regular schedule (weekly, biweekly, or monthly) without creating individual payment requests each time. The customer authorizes the plan once, and JoPay handles billing automatically on each cycle.

This is ideal for subscriptions, memberships, ongoing services, and any scenario where a fixed amount is billed at regular intervals.

Requirements

The customer uses one of the three supported v1 wallet buckets. Sequence WaaS (email / Google sign-in), Bucket A smart-contract wallets (Safe, Coinbase Smart Wallet, Argent, Ambire), or Bucket B delegator-capable wallets (MetaMask Delegator, EIP-7702 EOAs). All three sign a canonical ERC-7715 grant to the public recurring-pull executor. Hardware wallets (Ledger, Trezor) are not supported in v1. See Non-custodyfor why JoPay never holds a signing key in any of these paths.
Customer authorization — The customer explicitly signs the grant once at signup. The caveat enforcer holds the per-charge cap, frequency, total cap, and expiry on-chain. Any pull outside those bounds reverts at redeem time even if JoPay or the merchant submits it.

Creating a plan

Go to Recurring Plans

Open the Recurring Plans section from the navigation menu. You will see a list of your existing plans (if any) and a button to create a new one.

Set the amount

Enter the recurring amount in your display currency. JoPay converts this to USDC using the current FX rate. The USDC amount is what will be charged each cycle.

Choose the frequency

Select how often the customer will be charged:

Weekly — Every 7 days.
Biweekly — Every 14 days.
Monthly — Every 30 days.

Enter the customer wallet address

Enter the wallet address of the customer who will be charged. This must be a valid EVM address (0x...).

Send the authorization link

After creating the plan, JoPay generates an authorization link. Share this with the customer. The customer opens the link and approves the recurring charge from their wallet.

The plan will not start billing until the customer has authorized it. No charges occur without explicit customer approval.

Plan states

Each recurring plan has a state that reflects its current status:

Active — The plan is authorized and billing on schedule. The next charge will occur at the scheduled time.
Paused — Billing is temporarily stopped. No charges will occur until the plan is resumed. This can happen manually (you pause it) or automatically (after repeated failures).
Cancelled — The plan has been permanently stopped. No further charges will occur. Cancelled plans cannot be reactivated; create a new plan instead.
Failed — The most recent charge attempt failed. The plan may retry or pause depending on how many consecutive failures have occurred.

Managing plans

Pause a plan

To temporarily stop billing, open the plan and tap Pause. The plan moves to Paused state. No charges will occur while paused. You can resume it at any time.

Resume a plan

To restart billing on a paused plan, open the plan and tap Resume. The plan moves back to Active state and billing resumes on the next scheduled cycle.

Cancel a plan

To permanently stop a plan, open the plan and tap Cancel. The plan moves to Cancelled state. This is irreversible. If you need to bill the same customer again, create a new plan.

Cancelling a plan is permanent. You cannot undo it. Use Pause if you only need to temporarily stop billing.

Customer authorization page

When a customer opens the authorization link, they see a page showing:

The merchant name and plan details (amount, frequency).
An Authorize button to approve the recurring charge.
The wallet address that will be charged.

The customer must connect their wallet and sign an approval transaction. This grants JoPay permission to charge the specified amount at the specified frequency. The customer can revoke authorization at any time by contacting the merchant or through the subscription management page.

Failure handling

If a scheduled charge fails (e.g. insufficient USDC balance in the customer's wallet, network issues, or revoked authorization), JoPay records the failure and retries on subsequent cycles.

After 3 consecutive failures, the plan is automatically paused.

When a plan is auto-paused due to failures:

You are notified (if email notifications are enabled).
No further charges are attempted until you manually resume the plan.
Before resuming, verify that the customer has sufficient USDC in their wallet and that their authorization is still valid.

The most common reason for recurring failures is the customer's wallet running out of USDC. Contact your customer to ensure they maintain a sufficient balance.