Auto-recharge

​

Wire the backend route

// app/api/auto-recharge/route.ts
import { NextRequest } from 'next/server'
import { disableAutoRecharge, getAutoRecharge, saveAutoRecharge } from '@solvapay/next'

export const GET = (request: NextRequest) => getAutoRecharge(request)
export const PUT = (request: NextRequest) => saveAutoRecharge(request)
export const DELETE = (request: NextRequest) => disableAutoRecharge(request)

import {
  getAutoRechargeCore,
  saveAutoRechargeCore,
  disableAutoRechargeCore,
} from '@solvapay/server'

// Read the current config (null when none exists)
const { config } = await getAutoRechargeCore(request)

// Set or update the config
const saved = await saveAutoRechargeCore(request, {
  enabled: true,
  triggerType: 'balance',
  thresholdAmountMajor: 5,
  topupAmountMajor: 10,
  maxMonthlySpendMajor: 100,
  currency: 'USD',
})

// Turn it off
await disableAutoRechargeCore(request)

​

Configuration input

​

Reading the config

​

React components and hooks

import { AutoRecharge } from '@solvapay/react'

function BillingSettings() {
  return (
    <section>
      <h2>Automatic top-ups</h2>
      <AutoRecharge currency="USD" />
    </section>
  )
}

​

Stage auto-recharge with the first top-up

1. Render <AutoRecharge deferCardSetup onPendingConfig={...}> alongside your top-up amount step.
2. Saving the form sends deferSetupIntent: true — the config is staged as pending_setup without creating a Stripe SetupIntent, and onPendingConfig receives the AutoRechargeInput.
3. Pass that payload into TopupForm.Root (or createTopupPaymentIntent) as autoRecharge.
4. The backend creates the payment intent with setup_future_usage: 'off_session', saves the card on that same charge, and flips the config from pending_setup to active when the confirmation webhook lands.

import { useMemo, useState } from 'react'
import type { AutoRechargeInput } from '@solvapay/server'
import { AutoRecharge, TopupForm, configToAutoRechargeInput, useAutoRecharge } from '@solvapay/react'

function TopupWithAutoRecharge({ amount, currency = 'USD' }: { amount: number; currency?: string }) {
  const { config: savedConfig } = useAutoRecharge()
  const [pending, setPending] = useState<AutoRechargeInput | null>(null)

  const autoRecharge = useMemo((): AutoRechargeInput | undefined => {
    if (pending) return pending
    if (!savedConfig?.enabled) return undefined
    return configToAutoRechargeInput(savedConfig, { currency }) ?? undefined
  }, [pending, savedConfig, currency])

  return (
    <>
      <AutoRecharge currency={currency} deferCardSetup onPendingConfig={setPending} />

      <TopupForm.Root amount={amount} currency={currency} autoRecharge={autoRecharge}>
        <TopupForm.Loading>Preparing payment…</TopupForm.Loading>
        <TopupForm.PaymentElement />
        <TopupForm.Error />
        <TopupForm.SubmitButton>Add credits</TopupForm.SubmitButton>
      </TopupForm.Root>
    </>
  )
}

​

Monthly spend cap

• Spend is tracked in monthlySpendMinor under the monthlySpendPeriod key (YYYY-MM, UTC).
• When the next recharge would exceed the cap, the charge is skipped. The config stays active — charges resume automatically when the UTC month rolls over. No webhook fires for a cap skip.
• The drop-in <AutoRecharge> shows current-period spend (for example $45 / $100 this month) and a Monthly spend limit reached status when applicable.

​

Handling failed recharges

• After repeated declines, config.status flips to 'failed' and failureCount increments.
• Declines are delivered via the customer.credit.auto_topup_failed webhook — they are not returned in the trackUsage / usage-debit response.
• autoRecharge.triggered: true on a usage-debit response means an off-session charge was initiated, not that credits were booked inline. Credits mint when the charge succeeds.

​

Next steps

• React guide — TopupForm, AutoRecharge, useTopup, and useAutoRecharge in depth
• Purchase lifecycle management — activatePlan and the topup_required flow that leads customers here
• Webhooks — handle customer.credit.topped_up and customer.credit.auto_topup_failed