Recurring Payment Engine

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.

The AlgoVoi recurring payment engine is the subsystem responsible for scheduled, pre-authorised payments across all seven supported chains. It supports two distinct recurring payment models — MPP subscription protocol (Tier 1) and standing authorities (Tier 2) — and is accessible at recurr.algovoi.co.uk. Both models share a common pull executor, a common mandate data model, and common integration with the five audit chains. All pull transactions are settled on-chain with full receipt-format emission, making every recurring charge auditable, cancellable, and refundable under the same PSD2-aligned framework as one-off payments.

---

​

Architecture Overview

The pull executor runs as a scheduled in-process job. It evaluates next_due_at across all active mandates and standing authorities on a sub-minute cadence and submits pull transactions when due.

---

​

Mandate Data Model

Every recurring arrangement — whether a Tier 1 MPP subscription or a Tier 2 standing authority — is represented as a mandate record. The mandate record is the single source of truth for scheduling, cap enforcement, and state management.

​

Mandate Fields

​

Sealed Audit Fields

The following fields are sealed at insert into the payment_ledger audit chain on every pull and cannot be altered retrospectively: tenant_id, resource_id, tx_id (per pull), chain, asset_id, amount_microunits (per pull), payer_address, verified_at, status, protocol (recurr)

---

​

Platform Safeguards

The following limits are enforced at the control plane level for all mandate types. They are not configurable at tenant level. These limits are aligned with EMR 2011 Regulations 20–21 safeguarding requirements for payment institutions holding funds on behalf of customers. PSD2-aligned behaviour: when a mandate is cancelled with cancel_reason = user_requested, a cancellation receipt is emitted automatically per draft-hopley-x402-cancellation-receipt. This satisfies PSD2 Article 64 requirements for the customer’s right to revoke a payment authorisation.

---

​

Mandate Lifecycle State Machine

Mandates move through states according to the following transitions. No transition is possible outside this defined state machine.

​

States

​

Transitions

---

​

Tier 1: MPP Subscription Protocol

The Merchant Payment Protocol (MPP) subscription model is the standard recurring payment flow for merchants integrating with payer applications, AI agents, and wallets that support the paymentauth.org/mpp method string.

​

Resource Registration

A subscription resource is registered by the merchant at a deterministic URL: POST /mpp/sub// Where tenant_short_id is the merchant’s short identifier (visible in the dashboard) and resource_id is the merchant’s internal identifier for the subscription offering (e.g. a plan ID or product slug).

​

Subscription Intent Flow

1. An agent or payer issues a GET or POST to the subscription resource URL.
2. The Recurr service responds with HTTP 402 Payment Required and a subscription intent body.
3. The payer application reads the intent body and presents the subscription offer to the end user.
4. The payer signs a standing authority credential on-chain for the requested resource.
5. The facilitator confirms the on-chain signature to the control plane.
6. The mandate transitions from pending to active.
7. The pull executor charges the payer at each due date by constructing and submitting the on-chain pull transaction through the facilitator.

​

Subscription Intent Body Fields

​

MPP Subscription Status Fields

​

MPP Webhook Events

---

​

Tier 2: Standing Authorities

Tier 2 standing authorities are a higher-autonomy variant for AI-agent payment scenarios. A customer authorises a spending cap once. The agent or automated system then pulls payments on schedule against that cap without requesting re-authorisation for each individual pull.

​

Additional Fields (Tier 2 Only)

​

Manual Pull Endpoint

POST /v1/recurring//pull Triggers an immediate on-demand pull against a standing authority with pull_mode = on_demand. The pull is subject to per_cycle_microunits and the remaining lifetime cap. The request accepts an optional amount_microunits override (must be less than or equal to per_cycle_microunits). Response fields:

​

Tier 2 Chain Support

Tier 2 standing authorities are available on chains where the on-chain signature mechanism supports the required pre-authorisation credential format:

---

​

Pull Executor

The pull executor is the in-process scheduler that drives all recurring charges. It runs on the recurring payment engine.

​

Scheduling

The executor runs on a sub-minute cadence. On each tick it queries for all active mandates (both Tier 1 and Tier 2 scheduled) where next_due_at is in the past and status is active. Each due mandate is processed in order of next_due_at ascending.

​

Per-Pull Execution Steps

For each due mandate, the executor performs the following steps in order:

1. Validate mandate state: confirm status is still active (it may have been revoked between ticks).
2. Check safeguards: confirm that the pull amount does not exceed cap_microunits. For Tier 2 authorities, also confirm that the pull would not exceed lifetime_cap_microunits.
3. Construct pull transaction: build the chain-appropriate pull transaction. The transaction construction is delegated to the chain-specific facilitator module. The constructed transaction includes the on-chain reference to the standing authority credential.
4. Submit to facilitator: POST the raw transaction to the facilitator (active-passive cluster; standby instance used if primary is unreachable). The facilitator signs and broadcasts to the chain RPC.
5. Await confirmation: poll for on-chain confirmation up to the chain-specific timeout.
6. On success:
   • Update last_pull_at and last_pull_tx_id on the mandate record
   • Increment total_pulled_microunits
   • Calculate and store the new next_due_at
   • Write a payment_ledger audit chain row
   • Write a negotiation_trace_events row with event_type = mandate_activated (for first pull) or subscription_charged
   • Emit mandate.charged or mpp_subscription.charged webhook event
   • Emit a settlement_attestation receipt (per draft-hopley-x402-settlement-attestation)
7. On confirmation failure (chain timeout or RPC error):
   • Record the failed attempt with failure_reason and attempt_count
   • Schedule a retry per the pull-retry schedule (see below)
8. On final failure (all retries exhausted):
   • Set pull_failed_at and pull_failure_reason on the mandate record
   • Emit mandate.charge_failed or mpp_subscription.charge_failed webhook event
   • next_due_at is advanced to the next period (the missed period is not retried indefinitely)
   • Write a negotiation_trace_events row with event_type = rejected and outcome_reason = pull_failure

​

Pull-Retry Schedule

After six failed attempts, the pull is marked as permanently failed for that period. The mandate remains active; the next period’s pull will be attempted at next_due_at.

​

Failover

The pull executor submits through the facilitator API. If the primary facilitator is unreachable, the executor retries against the standby instance.

---

​

Receipt Chain Integration

Every mandate pull emits a full receipt suite. Receipts are formatted per the AlgoVoi IETF Internet-Draft suite, canonicalised via RFC 8785 JCS, and written to the appropriate audit chains.

​

Receipts Emitted Per Pull

​

Audit Chain Rows Per Pull

All rows are hash-chained and shipped to off-VM COMPLIANCE-mode Object Lock storage within approximately five minutes of write.

---

​

API Endpoints

​

Mandate Management

​

Standing Authorities (Tier 2)

​

MPP Subscription (Tier 1)

​

Live Demo Resource

A live MPP subscription fixture is available at: GET /mpp/sub/demo/mpp-sub-test-daily-base This resource is permanently maintained and can be used by integration partners to test MPP subscription flows against the live Recurr service without creating a tenant account. It uses Base chain USDC. Do not delete this resource.

---

​

Chain Coverage

Algorand, VOI, Base, and Solana have the richest recurring support because their on-chain authorisation credential formats support the pre-authorisation capability required for Tier 2 pull semantics. Hedera, Stellar, and Tempo support Tier 1 and basic mandates via a challenge-response model per pull.

---

​

Integration with Broader Protocol Suite

The Recurr engine participates in the AlgoVoi multi-protocol payment stack alongside x402, AP2, A2A, and hosted checkout. All five protocols share:

• The same payment_ledger audit chain (every confirmed payment from any protocol appears in the same chain)
• The same receipt-format suite (settlement attestation, compliance receipt, cancellation receipt, refund receipt)
• The same compliance engine (every payer address screened on every mandate activation and every pull)
• The same facilitator architecture (pull transactions submitted through the active-passive facilitator cluster)

Protocol field in payment_ledger rows distinguishes recurr payments from checkout, x402, mpp, ap2, and a2a payments. All protocol rows are hash-chained together in a single payment_ledger chain, not in separate per-protocol chains.

---

​

Regulatory Alignment