Recurring payments

AlgoVoi supports three recurring-style models. Choose based on who pays and how they fund.

	Recurr	MPP subscriptions	Mandates (APM)
Who pays	Human, from their own wallet	AI agent, autonomously from their wallet	AI agent, from a human-funded fiat balance
Funding	Customer’s crypto wallet	Customer’s crypto wallet	Human’s GBP balance (PayPal top-up)
Auth model	Invoice email each cycle — customer pays manually	One-time on-chain authority tx; AlgoVoi pulls each period	JWT mandate token; agent calls `/mandate/pay` per use
Cadence options	daily / weekly / monthly / quarterly / annual / custom	Any `day` / `week` / `month` interval	Pay-per-call (with daily/weekly/monthly caps)
AlgoVoi custody	None	None — authority tx grants bounded pull rights per chain	AlgoVoi pays merchants from custodial wallet, bills the human
Spec	AlgoVoi proprietary	paymentauth.org MPP `intent="subscription"`	AlgoVoi proprietary
Status	Tier 1 live; Tier 2 pull live	Live	Live

Recurr — human-facing invoice subscriptions

Recurr generates a fresh payment link each billing cycle and delivers it to the customer. The customer pays from their own wallet. AlgoVoi never holds keys or standing authority.

How it works

Merchant creates a customer (wallet address) and a subscription (amount, chain, cadence)
Each cycle, Recurr generates a standard payment link and emails it to the customer
Customer clicks the link and pays on-chain — same flow as any AlgoVoi checkout
Recurr marks the invoice paid and schedules the next cycle

Subscription lifecycle

active  →  cancelled   (operator cancel, customer self-cancel, or dunning limit reached)
        →  paused      (operator pause)
paused  →  active      (operator resume; next_due_at shifts forward by pause duration)

Creating a customer

curl -X POST https://api.algovoi.co.uk/v1/customers \
  -H "Authorization: Bearer $ALGOVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "CUSTOMER_WALLET",
    "email": "customer@example.com"
  }'

Creating a subscription

curl -X POST https://api.algovoi.co.uk/v1/subscriptions \
  -H "Authorization: Bearer $ALGOVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "uuid",
    "amount_minor": 1000000,
    "currency": "USDC",
    "chain": "algorand_mainnet",
    "cadence": "monthly",
    "notify_lead_hours": 48
  }'

amount_minor is in microunits (1,000,000 = 1.00 USDC). notify_lead_hours controls how early the invoice-ready email is sent before the due date.

Dunning

When an invoice is unpaid past the cycle window, Recurr sends follow-up emails on an exponential backoff schedule (1 day, 3 days, 7 days). After the configured maximum attempts the subscription moves to cancelled.

Customer self-cancel

Every subscription includes a cancel_url — a single-use link in every invoice email. Clicking it shows a confirmation page; submitting cancels immediately and rotates the secret so the link cannot be replayed. No login required.

Customer portal

recurr.algovoi.co.uk lets customers connect a wallet and view or cancel all subscriptions across every merchant that has billed that wallet. Supported wallets:

EVM (Base, Tempo, ARC testnet): MetaMask
Solana: Phantom
Algorand / VOI: AlgoVoi Extension, Pera, Defly, Lute
Stellar: Freighter, Albedo, xBull, LOBSTR
Hedera: HashPack, Blade, Kabila (via WalletConnect)

Webhooks

Event	Fired when
`subscription.created`	New subscription created
`subscription.invoice.paid`	Customer pays an invoice
`subscription.cancelled`	Subscription cancelled (any reason)
`subscription.paused`	Subscription paused
`subscription.resumed`	Subscription resumed

MPP subscriptions — agent-native standing authority

MPP subscriptions are designed for AI agents paying for resources autonomously. They follow the paymentauth.org MPP spec with intent="subscription", meaning the full lifecycle — authorisation, activation, and periodic pulls — happens without human intervention.

How it works

Challenge — the agent calls a subscription resource and receives a 402 with an MPP challenge:

WWW-Authenticate: Payment protocol="MPP" intent="subscription"
  periodCount=1 periodUnit="month"
  subscriptionExpires="2027-05-12T00:00:00Z"
  ...

Authority tx — the agent signs an on-chain transaction that grants AlgoVoi permission to pull amount each period. This is an approve/allowance tx (not a payment tx).
Credential post — the agent re-submits the request with Authorization: Payment containing the authority tx ID and signed proof.
Activation (atomic with first-period charge) — AlgoVoi verifies the authority tx inline, then executes the first-period pull on chain synchronously before returning. Activation succeeds only when the first pull is broadcast-accepted by the chain (the “soft success” threshold). The response carries status: "active", a base64url subscriptionId, a first_pull_tx_id, and a Payment-Receipt header. A background finality monitor watches the first-pull tx until the configured per-chain depth is reached; if the tx is dropped or orphaned before finality, the subscription is flipped to status: "revoked" and the agent must restart with a fresh authority.
Autonomous renewals — AlgoVoi’s pull reaper fires every 120 seconds, finds active subscriptions where next_due_at ≤ now (next_due_at = activation_anchor + 1 period after the first-period charge above), executes the on-chain pull, and advances next_due_at anchor-relative. Missed periods don’t accumulate authority — a delayed reaper skips past missed boundaries to the next future one in a single step (per draft-payment-intent-subscription-00 L422-425).

Resource setup

Mark a resource as a subscription when creating or updating it via the API:

curl -X POST https://api.algovoi.co.uk/v1/resources \
  -H "Authorization: Bearer $ALGOVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "premium-data-feed",
    "price_minor": 5000000,
    "currency": "USDC",
    "chain": "algorand_mainnet",
    "is_subscription": true,
    "sub_period_count": 1,
    "sub_period_unit": "month"
  }'

sub_period_unit accepts day, week, or month.

Wire format

An MPP subscription challenge looks like this:

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment protocol="MPP" version="1.0"
  intent="subscription"
  network="algorand_mainnet"
  receiver="ALGOVOI_WALLET"
  amount="5000000"
  asset="31566704"
  periodCount="1"
  periodUnit="month"
  subscriptionExpires="2027-05-12T00:00:00Z"
  nonce="..."
  expires="..."
  request="BASE64URL_REQUEST_OBJECT"

When the agent posts a valid credential, the gateway returns HTTP/1.1 200 OK with:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private
Payment-Receipt: subscriptionId="gIom4-F_S4qDyD7Hq9EFjw", intent="subscription",
                 periodCount="1", periodUnit="month"

{
  "subscriptionId": "gIom4-F_S4qDyD7Hq9EFjw",
  "status": "active",
  "periodCount": 1,
  "periodUnit": "month",
  "nextDueAt": "2026-06-12T12:00:00Z",
  "expiresAt": "2027-05-12T00:00:00Z",
  "first_pull_tx_id": "0xabc..."
}

subscriptionId is the base64url-no-padding form of an internal UUID per draft-payment-intent-subscription-00 §Subscription Identifier. The same value is also returned in the Payment-Receipt response header so clients following the I-D.httpauth-payment receipt convention can consume it without parsing the JSON body. first_pull_tx_id is the chain tx that collected the first period’s charge as part of activation; clients may inspect it on-chain or wait for the finality monitor to mark first_pull_finalized_at (the same status surfaces through the revoked lifecycle transition if finality is never reached).

Idempotency

Subscription activation honours the Idempotency-Key request header per draft-ietf-httpapi-idempotency-key-header §2.5:

Same Idempotency-Key + same request payload (resource + credential) → cached 200 response, byte-identical to the first activation (same subscriptionId, same Payment-Receipt).
Same Idempotency-Key + a different request payload → 422 Unprocessable Entity. The key has been reused with a new payload, which the spec treats as misuse.
No Idempotency-Key header → a credential replay of the same challenge is rejected as 401 (single-use per draft-payment-intent-subscription-00 §Single-Use). Send a fresh challenge to retry.

Keys are tenant-scoped, so two tenants can independently use the same opaque string without colliding.

Subscription lifecycle

(synchronous activation)
  authority verify → first-period pull broadcast-accepted → active
                                                          → 402 / 504 (pull failed)

(post-activation, async)
  active  →  revoked   (first-pull tx dropped pre-finality or finality timeout)
          →  cancelled (operator cancel or agent request)
          →  expired   (sub_expires_at reached or pull authority lapsed)

revoked is distinct from cancelled and expired: it signals that activation returned success but the on-chain first-period charge subsequently failed to reach finality. Agents that see status: "revoked" on a subscription they believed was active should treat it as a hard fail and restart with a fresh authority.

Supported chains

All 8 AlgoVoi chains support MPP subscriptions: Algorand, VOI, Hedera, Stellar, Base (EVM), Solana, Tempo (EVM), ARC (EVM testnet).

Key differences from Recurr

No emails, no dunning, no customer portal — fully autonomous
The authority tx is a one-time on-chain approval; subsequent pulls need no agent involvement
The agent receives a subscriptionId it can reference to check status or request cancellation
Designed for the agent-to-agent and agent-to-service payment use case

Choosing between the two models

Use Recurr when:

Customers are humans who expect to review and approve each payment
You want dunning, email notifications, and a self-service cancel page
The subscription is between a merchant and an end customer

Use MPP subscriptions when:

The payer is an AI agent operating autonomously
You are building a tool or resource priced per period in an MCP/RPC context
You want zero human friction and fully autonomous billing

Get started

Concepts

Standards

Payment protocols

Chains

Integrations

Help

Recurring payments

Recurr — human-facing invoice subscriptions

How it works

Subscription lifecycle

Creating a customer

Creating a subscription

Dunning

Customer self-cancel

Customer portal

Webhooks

MPP subscriptions — agent-native standing authority

How it works

Resource setup

Wire format

Idempotency

Subscription lifecycle

Supported chains

Key differences from Recurr

Choosing between the two models

See also

Get started

Concepts

Standards

Payment protocols

Chains

Integrations

Help

Documentation Index

​Recurr — human-facing invoice subscriptions

​How it works

​Subscription lifecycle

​Creating a customer

​Creating a subscription

​Dunning

​Customer self-cancel

​Customer portal

​Webhooks

​MPP subscriptions — agent-native standing authority

​How it works

​Resource setup

​Wire format

​Idempotency

​Subscription lifecycle

​Supported chains

​Key differences from Recurr

​Choosing between the two models

​See also

Recurr — human-facing invoice subscriptions

How it works

Subscription lifecycle

Creating a customer

Creating a subscription

Dunning

Customer self-cancel

Customer portal

Webhooks

MPP subscriptions — agent-native standing authority

How it works

Resource setup

Wire format

Idempotency

Subscription lifecycle

Supported chains

Key differences from Recurr

Choosing between the two models

See also