Recurring Payments

Recurring payments, also known as merchant-initiated transactions (MITs), let a customer approve once from their own wallet, then let you authorize payments later without asking again. The customer keeps their funds in their wallet until you authorize a payment. Each payment is a normal payment session, so capture, void, refund, webhooks, and settlement work exactly as they do for every other Payment Acceptance payment. The approval is called a mandate: the customer’s revocable consent for you to pull payments from their wallet, within limits you set.

What you can build

Subscriptions

Bill monthly or annual plans without sending the customer back to checkout every cycle.

Usage-based billing

Bill for metered usage at the end of each billing period, for any amount within your limits.

Auto top-ups

Refill a prepaid balance or credits automatically when it runs low.

One-click repeat purchases

Let returning customers pay without connecting a wallet and signing again.

Why recurring payments

One approval, many payments. The customer signs once. You authorize payments whenever your billing logic says so.
Customers keep custody. Funds stay in the customer’s wallet until a payment pulls them. Nothing is prefunded or locked up.
No gas fees for customers. Approving is gasless and so is every payment. Customers pay the exact amount, nothing more.
The lifecycle you already built. Each payment is a payment session. Capture, void, refund, webhooks, and reporting don’t change.
Pay from any supported network. Customers approve from Base, Ethereum, Arbitrum, Optimism, Polygon, or Solana. Every payment settles the same way as other wallet payments. Solana uses the network name solana in every environment, including sandbox.
Customers stay in control. Every mandate has spending limits, and customers can remove their approval at any time.

How it works

Create a mandate

Call POST /v2/mandates with the spending limits for this customer.

The customer approves once

Send the customer to Coinbase’s hosted approval page, or embed it in your app. They connect their self-custody wallet and sign a single gasless approval.

Get paid on your schedule

For each payment, create a payment session and authorize it with the mandateId. The customer doesn’t need to be present.

1. Create a mandate

Create one mandate per customer relationship, such as one per subscription. Set spending limits that fit your billing model.

cdp api -X POST /platform/v2/mandates -e sandbox \
  asset=usdc \
  policy.maxPerAuthorization=50.00 \
  policy.maxPerPeriod.amount=100.00 \
  policy.maxPerPeriod.period=month \
  metadata.customer_id=cust_12345

Field	Description
`asset`	The stablecoin the spending limits are denominated in, such as `usdc`.
`policy`	Spending limits. Optional. See Spending limits.
`expiresAt`	Optional date after which you can no longer authorize payments with the mandate. Omit for no expiry.
`metadata`	Up to 10 key-value pairs, such as your customer or subscription ID.

Example response

{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "asset": "usdc",
  "policy": {
    "maxPerAuthorization": "50.00",
    "maxPerPeriod": {
      "amount": "100.00",
      "period": "month"
    }
  },
  "status": "created",
  "url": "https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "metadata": {
    "customer_id": "cust_12345"
  },
  "createdAt": "2026-06-15T12:00:00.000Z",
  "updatedAt": "2026-06-15T12:00:00.000Z"
}

Coinbase generates the mandateId. You can’t set it yourself, so save it with your customer record. You’ll need it to authorize every payment. To attach your own identifiers, such as a customer or subscription ID, use metadata.

export MANDATE_ID="mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

The mandate starts in created status. You can’t authorize payments with it until the customer approves it.

2. Get the customer’s approval

The customer approves the mandate once from their self-custody wallet, for example during signup or checkout. Redirect the customer to the mandate’s url, or embed the approval in your page by calling render({ mandateId }) on the <coinbase-payment> web component. Coinbase connects the wallet, picks the best-funded network, and collects the signature. See Hosted Checkout for setup. The approval returns in pending status and confirms onchain shortly after. Wait for the acceptance.mandate.approval_succeeded webhook before you authorize a payment. At that point the mandate moves to approval_succeeded and its source shows the wallet address and network the customer approved from. If approval fails, the mandate moves to approval_failed and the customer can try again.

Build your own approval UI

You only need these endpoints if you’re not using the hosted page or embedded component. They don’t use your API key, because the customer’s wallet signature is the proof of consent, so you can call them from your frontend. The flow mirrors wallet authorization.

Get approval options for one to five of the customer’s wallet addresses:
curl "https://sandbox.cdp.coinbase.com/platform/v2/mandates/$MANDATE_ID/approvals/wallet/options?addresses=0xAbC1234567890aBcDeF1234567890AbCdEf123456"
Coinbase returns at most one option, choosing the address and network with the highest stablecoin balance, including Solana. Pass network only when the customer must approve from one network. The Solana network name is solana in every environment, including sandbox. Addresses that can’t be used appear in ineligibleAddresses with a reason, such as insufficient_funds.

Sign the payload for the option’s type:

`type`	How the customer signs	What you submit as `signature`
`eip2612`	Pass `data` to `eth_signTypedData_v4`	`0x`-prefixed hex signature
`solana_subscription`	Sign the transaction. See Solana signatures.	Base58-encoded 64-byte signature

Submit the signature:

curl -X POST "https://sandbox.cdp.coinbase.com/platform/v2/mandates/$MANDATE_ID/approvals/wallet" \
  -H "Content-Type: application/json" \
  -d '{
    "optionId": "opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signedPayloads": [
      { "payloadId": "payload_af2937b0-...", "signature": "0xabcdef..." }
    ]
  }'

The example signature is an EVM hex signature. A Solana approval uses the same request body. Its signature is the base58 string from Solana signatures.

Sign and submit payloads from a single options response. Each response includes fresh signing data, so don’t cache options.Revocation uses the same signing rules. Call GET /v2/mandates/{mandateId}/revocations/wallet/options, have the customer sign the returned payload (eip2612 on EVM, solana_subscription on Solana, where the transaction is revokeDelegation), and submit the signature to POST /v2/mandates/{mandateId}/revocations/wallet.

3. Authorize a payment

For each payment, create a payment session for the amount due, then authorize it with the mandate. The customer doesn’t need to take any action.

cdp api -X POST /platform/v2/payment-sessions -e sandbox \
  amount=19.99 \
  asset=usdc \
  target.accountId=$ACCOUNT_ID \
  target.asset=usd \
  'autoCapture:=true' \
  externalReferenceId=invoice-2026-07

cdp api -X POST /platform/v2/payment-sessions/$SESSION_ID/authorizations/mandate -e sandbox \
  "Header:X-Idempotency-Key:8e03978e-40d5-43e8-bc93-6894a57f9324" \
  mandateId=$MANDATE_ID

The authorization returns in pending status and moves to succeeded or failed. From there the session follows the standard lifecycle:

Auto-capture suits most recurring payments, because you’ve already delivered the service or are about to.
Voids and refunds always return funds to the wallet and network the customer approved from.
Idempotency keys let you retry an authorization safely. Always send X-Idempotency-Key from your billing jobs so a retry never pulls funds twice.

An authorization is rejected before any funds move if the mandate isn’t usable or the amount breaks the spending limits. See Errors. If the customer’s wallet doesn’t hold enough to cover the payment, the authorization fails with insufficient_funds. See Prevent failed payments for how to catch that before billing day.

Spending limits

Every mandate has a policy that caps what you can authorize. Coinbase checks the policy on every authorization.

Limit	What it caps
`maxPerAuthorization`	The largest single authorization.
`maxPerPeriod`	The total you can authorize in a rolling `day`, `week`, `month`, or `year`. Windows are measured back from now, so `month` means the trailing 30 days, not the calendar month.
`minSetupBalance`	The minimum stablecoin balance the customer needs to approve the mandate. Customers always need at least $1. Set a higher value to require more. It doesn’t affect payment amounts.

All limits are optional. Any limit you omit gets a Coinbase default, and limits above Coinbase’s maximums are lowered to the maximum. The response always shows the limits that apply. An authorization over a limit is rejected with 422 mandate_policy_violation, and no funds move. We recommend setting your own limits that match your billing model. Your business is responsible for payments authorized with its mandates, so tight limits protect your customers from misuse. Leave some headroom above your expected payment amounts for plan upgrades, taxes, or usage spikes. Mandate terms can’t be edited after you create the mandate. To change them, cancel the mandate, create a new one, and ask the customer to approve it.

Ending a mandate

There are two ways to end a mandate, and they’re independent.

	Cancel	Revoke
Who	You	The customer
How	`POST /v2/mandates/{mandateId}/cancel`	The hosted `revocationUrl` or embedded component, or directly from their wallet
Effect	Blocks new authorizations immediately. Authorizations already in progress aren’t affected.	Removes the onchain approval from the customer’s wallet
Timing	Instant	Confirms onchain shortly after the customer signs

When a customer ends their subscription, cancel the mandate so no further payments can be authorized, and point them to revocationUrl if they also want to remove the wallet approval. If a customer removes the approval directly from their wallet, your next authorization fails.

cdp api -X POST /platform/v2/mandates/$MANDATE_ID/cancel -e sandbox \
  reason="Customer canceled their subscription."

Prevent failed payments

A payment fails with insufficient_funds when the customer’s wallet doesn’t hold enough of the mandate asset on the approved network. No funds move and the mandate stays usable, but the payment doesn’t go through until you retry. Unlike a card, a wallet’s balance is public onchain, so you can spot a shortfall before you authorize. We recommend checking the balance in your billing job before every mandate payment and letting the customer know when they’re short. Coinbase doesn’t contact your customers.

Check the balance before you authorize

Get source.address, source.network, and source.asset from the mandate, either from the acceptance.mandate.approval_succeeded webhook or GET /v2/mandates/{mandateId}. Payments are only pulled from this wallet, on this network, in this asset.

List the wallet’s balances on source.network with the Token Balances API:

cdp api /platform/v2/evm/token-balances/$SOURCE_NETWORK/$SOURCE_ADDRESS

Example response

{
  "balances": [
    {
      "amount": { "amount": "4100000", "decimals": 6 },
      "token": {
        "network": "base",
        "symbol": "USDC",
        "name": "USD Coin",
        "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  ]
}

The Token Balances API covers Base and Ethereum. For mandates approved from Arbitrum, Optimism, or Polygon, read the USDC balance of source.address with your own node or indexer, then continue from step 4.

Find the USDC entry by token.contractAddress (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 on Base, 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum), not by symbol. Results are paginated: if the response includes nextPageToken, pass it as pageToken to get the next page. If USDC isn’t on any page, the balance is zero.
Compare the balance to the amount due. The API returns amount as an integer in USDC’s smallest unit, where 1 USDC is 1,000,000 units (decimals: 6). Payment amounts like 19.99 are in whole USDC, so convert the amount due before you compare:
Whole USDC Smallest units
Wallet balance 4.10 4100000
Amount due 19.99 19990000
4100000 is less than 19990000, so the customer is 15.89 USDC short.
If the balance is below the amount due, tell the customer how much to add and the address, network, and asset to send it to. Funds on another network or in another token don’t count.

	Whole USDC	Smallest units
Wallet balance	4.10	`4100000`
Amount due	19.99	`19990000`

If the payment fails anyway

A passing check doesn’t guarantee the payment goes through, because the customer can move funds after you check. When an authorization fails, the acceptance.payment_session.authorization_failed webhook carries the reason in data.authorization.error.code. If the reason is insufficient_funds, no funds moved and the mandate is still usable. To try again, create a new payment session and authorize it with the same mandateId and a new X-Idempotency-Key. Other failure reasons, such as a revoked mandate, need a different response. See Errors.

Mandate statuses

status reflects the most recent action on the mandate.

Status	Meaning
`created`	Waiting for the customer to approve.
`approval_pending`	Approval is confirming onchain.
`approval_succeeded`	Approved. You can authorize payments with it.
`approval_failed`	The last approval attempt failed. The customer can try again.
`canceled`	You canceled it. No further authorizations.
`revocation_pending`	The customer’s revocation is confirming onchain.
`revocation_succeeded`	The customer removed their approval. No further authorizations.
`revocation_failed`	The revocation didn’t complete. The approval is still in place.

To decide whether you can authorize a payment with a mandate, check its timestamps rather than relying on status alone. A mandate is usable when approvedAt is set, canceledAt and revokedAt are empty, expiresAt is empty or in the future, and no revocation is in progress (status isn’t revocation_pending). For example, a mandate in revocation_failed is still usable because the approval was never removed.

Webhooks

Subscribe to acceptance.mandate.* events to track approvals and cancellations. Payments authorized with a mandate use the existing payment session events.

Event	Fires when
`acceptance.mandate.created`	You create a mandate
`acceptance.mandate.approval_initiated`	The customer signs and approval starts confirming
`acceptance.mandate.approval_succeeded`	The mandate is approved and ready to use
`acceptance.mandate.approval_failed`	Approval failed. The customer can retry
`acceptance.mandate.canceled`	You cancel the mandate
`acceptance.mandate.revocation_initiated`	The customer signs a revocation
`acceptance.mandate.revocation_succeeded`	The approval is removed from the customer’s wallet
`acceptance.mandate.revocation_failed`	Revocation failed. The customer can retry

Every mandate event’s data contains the full mandate. Approval events also include approval, and revocation events include revocation, each with an error when the attempt fails. See example payloads and Webhooks for setup.

Errors

These errors mean Coinbase rejected a mandate authorization before any funds moved. Coinbase checks the mandate in this order and returns the first match.

Error	HTTP status	What to do
`mandate_action_pending`	409	An approval or revocation is still confirming. Retry after it resolves.
`mandate_revoked`	422	The customer removed their approval. Ask them to approve a new mandate.
`mandate_canceled`	422	You canceled the mandate. Create a new one if the customer wants to continue.
`mandate_expired`	400	The mandate is past its `expiresAt`. Create a new one.
`mandate_invalid_status`	422	The mandate hasn’t been approved yet. Wait for `approval_succeeded`.
`mandate_policy_violation`	422	The amount exceeds `maxPerAuthorization` or `maxPerPeriod`. Authorize a smaller amount, wait for room in the rolling window, or ask the customer to approve a new mandate with higher limits.

Standard payment session errors, such as an expired authorization window, also apply. An insufficient_funds failure arrives asynchronously through the acceptance.payment_session.authorization_failed webhook rather than as an HTTP error. See Prevent failed payments.

Payment Sessions

Create the session you authorize with a mandate

Authorization

Compare mandate, wallet, Coinbase, and x402 authorization

Webhooks

Subscribe to mandate and payment session events

Example payloads

See the shape of mandate webhook events

GET STARTED

AI AGENTS

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

What you can build

Subscriptions

Usage-based billing

Auto top-ups

One-click repeat purchases

Why recurring payments

How it works

1. Create a mandate

2. Get the customer’s approval

3. Authorize a payment

Spending limits

Ending a mandate

Prevent failed payments

Check the balance before you authorize

If the payment fails anyway

Mandate statuses

Webhooks

Errors

What to read next

Payment Sessions

Authorization

Webhooks

Example payloads

​What you can build

Subscriptions

Usage-based billing

Auto top-ups

One-click repeat purchases

​Why recurring payments

​How it works

​1. Create a mandate

​2. Get the customer’s approval

​3. Authorize a payment

​Spending limits

​Ending a mandate

​Prevent failed payments

​Check the balance before you authorize

​If the payment fails anyway

​Mandate statuses

​Webhooks

​Errors

​What to read next

Payment Sessions

Authorization

Webhooks

Example payloads

What you can build

Why recurring payments

How it works

1. Create a mandate

2. Get the customer’s approval

3. Authorize a payment

Spending limits

Ending a mandate

Prevent failed payments

Check the balance before you authorize

If the payment fails anyway

Mandate statuses

Webhooks

Errors

What to read next