Skip to main content

Start accepting recurring payments with Base Pay Subscriptions

Base Subscriptions enable you to build predictable, recurring revenue streams by accepting automatic USDC payments. Whether you’re running a SaaS platform, content subscription service, or any business model requiring regular payments, Base Subscriptions provide a seamless solution with no merchant fees. Key Capabilities:
Support any billing cycle that fits your business model:
  • Daily subscriptions for short-term services
  • Weekly for regular deliveries or services
  • Monthly for standard SaaS subscriptions
  • Annual for discounted long-term commitments
  • Custom periods (e.g., 14 days, 90 days) for unique models
Charge any amount up to the permitted limit:
  • Fixed recurring amounts for predictable billing
  • Variable usage-based charges within a cap
  • Tiered pricing with different charge amounts
  • Prorated charges for mid-cycle changes
Full control over the subscription lifecycle:
  • Real-time status checking to verify active subscriptions
  • Remaining charge amount for the current period
  • Next period start date for planning
  • Cancellation detection for immediate updates
Built for production use cases:
  • No transaction fees or platform cuts
  • Instant settlement in USDC stablecoin
  • Testnet support for development and testing
  • Detailed transaction history for accounting
  • Programmatic access via SDK

How It Works

Base Subscriptions leverage Spend Permissions – a powerful onchain primitive that allows users to grant revocable spending rights to applications. Here’s the complete flow:
1

User Approves Subscription

Your customer grants your application permission to charge their wallet up to a specified amount each billing period. This is a one-time approval that remains active until cancelled.
2

Application Charges Periodically

Your backend service charges the subscription when payment is due, without requiring any user interaction. You can charge up to the approved amount per period.
3

Smart Period Management

The spending limit automatically resets at the start of each new period. If you don’t charge the full amount in one period, it doesn’t roll over.
4

User Maintains Control

Customers can view and cancel their subscriptions anytime through their wallet, ensuring transparency and trust.

Implementation Guide

Architecture Overview

A complete subscription implementation requires both client and server components: Client-Side (Frontend):
  • User interface for subscription creation
  • Create wallet requests and handle user responses
Server-Side (Backend - Node.js):
  • CDP smart wallet for executing charges and revocations
  • Scheduled jobs for periodic billing
  • Database for subscription tracking
  • Handlers for status updates
  • Retry logic for failed charges
CDP-Powered BackendBase Subscriptions use CDP (Coinbase Developer Platform) server wallets for effortless backend management. The charge() and revoke() functions handle all transaction details automatically:
  • ✅ Automatic wallet management
  • ✅ Built-in transaction signing
  • ✅ Gas estimation and nonce handling
  • ✅ Optional paymaster support for gasless transactions
Get CDP credentials from CDP Portal.
Security RequirementsTo accept recurring payments, you need:
  1. CDP credentials (API key ID, secret, and wallet secret)
  2. Backend infrastructure (Node.js) to execute charges securely
  3. Database to store and manage subscription IDs
  4. Never expose CDP credentials in client-side code

Setup: Create Your Subscription Owner Wallet

First, set up your CDP smart wallet that will act as the subscription owner:
backend/setup.ts
Backend Only: This setup runs in your Node.js backend with CDP credentials. The resulting wallet address is public and safe to share with your frontend for use in subscribe() calls.
Keep CDP Credentials Private: Never expose CDP credentials (API key, secrets) to the frontend. Only the subscription owner wallet address needs to be accessible to the frontend.

Client-Side: Create Subscriptions

Users create subscriptions from your frontend application:
SubscriptionButton.tsx

Server-Side: Charge Subscriptions

Execute charges effortlessly from your backend using CDP:
chargeSubscriptions.ts

Server-Side: Revoke Subscriptions

Cancel subscriptions programmatically from your backend:
revokeSubscription.ts
Automatic Transaction Management: The charge() and revoke() functions handle all transaction details including wallet management, gas estimation, nonce handling, and transaction confirmation. Use the paymasterUrl parameter to enable gasless transactions for your users.
Gasless Transactions: Set the PAYMASTER_URL environment variable to sponsor gas fees for your subscription charges and revocations. This creates a seamless experience where your backend covers all gas costs. Get your paymaster URL from the CDP Portal.

Fund Management

By default, charged USDC remains in your subscription owner wallet. You can optionally specify a recipient address to automatically transfer funds to a different address:

Testing on Testnet

Test your subscription implementation on Base Sepolia before going live:
testnet-frontend.ts
testnet-backend.ts

Network and Token Support

Base Subscriptions (USDC on Base):
Custom Implementations Possible: While Base Subscriptions are optimized for USDC on Base, you can use the underlying Spend Permissions primitive to build custom subscription implementations with any ERC-20 token or native ETH on any EVM-compatible chain.

Advanced Topics

Custom Transaction Handling

For developers who need manual control over transaction execution or want to integrate with existing wallet infrastructure, use the lower-level utilities:
If you can’t use CDP wallets, prepareCharge() gives you call data to execute manually:
See prepareCharge reference for details.
Similarly, prepareRevoke() provides revocation call data:
See prepareRevoke reference for details.

API Reference

subscribe()

Create subscriptions from frontend

getStatus()

Check subscription status

charge()

Charge subscriptions from backend

revoke()

Cancel subscriptions from backend

Setup Owner Wallet

Setup CDP owner wallet for subscription management

prepareCharge()

Advanced: Custom charge execution

prepareRevoke()

Advanced: Custom revoke execution

Spend Permissions

Deep dive into the underlying primitive

One-Time Payments

Accept single payments