> ## Documentation Index > Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # Recurring payments > Three recurring payment models on AlgoVoi: invoice subscriptions (Recurr), agent native standing authority (MPP), and fiat funded agent mandates (APM). AlgoVoi supports three recurring-style models. Choose based on who pays and how they fund. | | Recurr | MPP subscriptions | [Mandates (APM)](/concepts/mandates) | | --------------- | ------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------- | | 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](https://mpp.dev) `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 1. Merchant creates a customer (wallet address) and a subscription (amount, chain, cadence) 2. Each cycle, Recurr generates a standard payment link and emails it to the customer 3. Customer clicks the link and pays on-chain — same flow as any AlgoVoi checkout 4. 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 ```bash theme={null} 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 ```bash theme={null} 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](https://mpp.dev) with `intent="subscription"`, meaning the full lifecycle — authorisation, activation, and periodic pulls — happens without human intervention. ### How it works 1. **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" ... ``` 2. **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). 3. **Credential post** — the agent re-submits the request with `Authorization: Payment` containing the authority tx ID and signed proof. 4. **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. 5. **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](https://github.com/tempoxyz/mpp-specs/pull/230)). ### Resource setup Mark a resource as a subscription when creating or updating it via the API: ```bash theme={null} 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 theme={null} 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](https://github.com/tempoxyz/mpp-specs/pull/230). 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](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/): * 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](https://github.com/tempoxyz/mpp-specs/pull/230)). 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 ## See also * [MPP protocol](/protocols/mpp) — the full MPP wire protocol and discovery spec * [Payment links](/concepts/payment-links) — how Recurr invoices work under the hood * [Outbound webhooks](/integrations/outbound-webhooks) — event payload schema