Agentic Payment Mandates (APM)

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.

​

Customer portal — recurr.algovoi.co.uk/mandate

• Current balance and currency (GBP pence resolution)
• Status (active / suspended / revoked)
• The mandate JWT (copyable — paste into your agent’s env)
• Last 10 charges (amount, chain, tx id, timestamp)
• Top up via PayPal button (initiates PayPal Orders v2 flow, captures on return)

https://recurr.algovoi.co.uk/mandate?id=<MANDATE_UUID>

​

How it works

[1] Operator registers human as a mandate account holder
[2] Operator issues a mandate (cap, period, merchant whitelist) → returns JWT
[3] Human tops up balance via PayPal (or operator credits via SQL/API)
[4] Human pastes the JWT into their agent's env vars / system prompt
[5] Agent calls POST /mandate/pay with the JWT for each resource purchase
[6] AlgoVoi: decrements balance → pays merchant on-chain → returns access token
[7] Agent uses access token to retrieve the gated resource

​

Token format

{
  "jti": "<mandate-row-uuid>",
  "sub": "<account-uuid>",
  "typ_claim": "mandate_v1",
  "iat": 1778775645,
  "exp": 1778779245
}

• jti — UUID stored on the mandates row (pre-allocated at issue time, primary index for fast revocation lookup)
• sub — the mandate_accounts.id of the human who owns it
• typ_claim — token type marker; the verifier rejects anything other than mandate_v1
• exp — optional expiry; if omitted, the token is non-expiring (caps + balance still enforce limits)

​

Spending the mandate — agent integration

curl -X POST https://api.algovoi.co.uk/mandate/pay \
  -H "Authorization: Bearer $ALGOVOI_MANDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "96eb0225-dd47-4bc3-be10-143d6e6d7bd1",
    "resource_id": "a52aa0a9-db9a-4212-85f3-e91647c399b9",
    "max_amount_minor": 200,
    "description": "Research API call"
  }'

{
  "charge_id": "1d8e3...",
  "amount_minor": 80,
  "currency": "GBP",
  "tx_id": "ALGO_TX_ID_HERE",
  "chain": "algorand_mainnet",
  "remaining_balance_minor": 1420,
  "access_token": "eyJhbGciOiJI..."
}

​

Per-call guards

• max_amount_minor — agent self-cap. If the resolved resource costs more than this, the call returns 402 and no charge occurs.
• Mandate balance — if amount_minor > balance_minor, returns 402.
• Period cap (daily/weekly/monthly) — if this charge would push period_spent_minor over the cap, returns 402.
• Merchant whitelist — if merchant_whitelist is non-null and tenant_id is not in it, returns 403.

​

Response codes

​

Operator workflow — internal API

​

1. Register a human account holder

curl -X POST https://api.algovoi.co.uk/internal/mandate-accounts/register \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent-owner@example.com",
    "display_name": "Acme Co — research bot"
  }'

​

2. Issue a mandate

curl -X POST https://api.algovoi.co.uk/internal/mandates \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "<ACCOUNT_UUID>",
    "display_name": "Acme research bot — Q2 budget",
    "period": "monthly",
    "period_cap_minor": 10000,
    "ttl_secs": 2592000,
    "merchant_whitelist": ["96eb0225-..."]
  }'

​

3. Top up balance

curl -X POST https://api.algovoi.co.uk/internal/mandates/<MANDATE_ID>/topup \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_minor": 50000 }'

​

4. List, view charges, revoke

# List all mandates for an account
curl -H "Authorization: Bearer $ADMIN_API_KEY" \
  "https://api.algovoi.co.uk/internal/mandates?account_id=<ACCOUNT_UUID>"

# View charges
curl -H "Authorization: Bearer $ADMIN_API_KEY" \
  "https://api.algovoi.co.uk/internal/mandates/<MANDATE_ID>/charges"

# Revoke (idempotent — JWT immediately invalidated)
curl -X DELETE -H "Authorization: Bearer $ADMIN_API_KEY" \
  "https://api.algovoi.co.uk/internal/mandates/<MANDATE_ID>"

​

Period semantics

​

Custody

​

Where the money sits at each stage

[1] PayPal top-up        →  Funds settle from PayPal to AlgoVoi's UK business
                            bank account (segregated client-money account, not
                            AlgoVoi operating capital).
[2] balance_minor row    →  Postgres column on the mandate.  Source of truth
                            for "how much the user has left to spend."
[3] Agent calls /pay     →  balance_minor decremented within a single transaction
                            that also writes the mandate_charges ledger row.
[4] Merchant payout      →  AlgoVoi's custodial hot wallet on the target chain
                            sends the equivalent crypto amount to the merchant's
                            configured payout address.  On-chain settlement is
                            final — there is no reversal once tx_id confirms.
[5] Treasury rebalance   →  Off-cycle, AlgoVoi sells GBP → stablecoin to keep
                            the hot wallet floats topped up.  Users do not see
                            this; the user-visible flow is GBP in, GBP out.

​

Custody model vs the other AlgoVoi products

​

Safeguarding

• UK: holding pre-paid customer balances triggers EMR 2011 safeguarding obligations under regulations 20-21 (the funds-received and segregation rules), with PSR 2017 reg 23 covering any non-e-money payment-transaction funds (via EMR 20(6)). This is the EMR/PSR regime — NOT the CASS 7 client-money regime which governs investment business. AlgoVoi is in the process of obtaining the relevant authorisation (status: in preparation — see Compliance).
• EU: equivalent treatment under PSD2 / EMD2 if offering APM cross-border to EU residents.
• US: state money-transmitter licensing if APM is offered to US residents; not currently available in the US.

• Per-mandate balance cap (default £100): enforced at issuance, admin top-up, PayPal initiate, and PayPal capture — every code path that increases balance_minor. Config: MANDATE_MAX_BALANCE_MINOR.
• Per-account aggregate balance cap (default £300): sum of balance_minor across all active mandates owned by the same human; same enforcement points. Config: MANDATE_MAX_ACCOUNT_BALANCE_MINOR.
• Per-account mandate-count cap (default 3): enforced at issuance only — an account holding 3 active (non-revoked) mandates cannot issue a fourth. Config: MANDATE_MAX_PER_ACCOUNT.

​

Hot-wallet security

• Hot wallet float per chain, not per user. The £15 mandate has no specific crypto reserved against it — the wallet holds enough liquidity in aggregate to settle expected daily volume, with overnight cold-storage sweeps for the excess.
• HSM-backed signing for high-value chains (Base, Algorand mainnet, Stellar); software signing with key-encryption-at-rest for testnets and low-value chains.
• Rate limits at the facilitator prevent a compromised gateway from draining the float — per-chain daily cap and per-tx maximum.
• No user keys held. APM never asks the user for, generates, or stores any private key on the user’s behalf. The user’s relationship with AlgoVoi is purely fiat-balance-based.

​

Evidence the FCA will look for

1. Designated safeguarding account at the bank with a letter from the bank confirming designation per EMR 21(3)(a). Internal labelling is not sufficient; the account name or accompanying bank letter must make the safeguarding purpose obvious.
2. Chain-by-chain reconciliation from the mandate ledger (balance_minor aggregated) through mandate_charges.tx_id to the on-chain wallet balance — performed and recorded daily, with discrepancies investigated within one business day.
3. Key-management governance — who can sign, signing thresholds (m-of-n for HSM-protected wallets), key rotation cadence, incident response.
4. Sweep and float-management policy — when excess float moves to cold storage, who authorises, how reconciliations follow the funds.
5. Wind-down plan showing how every active mandate would be made whole if AlgoVoi ceased operations or the wallet stack failed (refund route, communication, timeline).
6. Books and records per EMR 21(5) — ledger entries that identify each user’s safeguarded balance, retained per the FCA’s record-keeping rules.

​

What this means for users

• You don’t need a crypto wallet to use APM. That’s the value proposition.
• You give up custody of your fiat balance during the period it sits with AlgoVoi.
• Unspent balance is refundable on mandate closure (subject to identity verification) — EMR 2011 reg 39 redemption rights apply.
• Spent balance is refundable for at-fault failures — if AlgoVoi delivers the wrong payout, the merchant doesn’t deliver the resource, or a double-charge occurs, you get a refund of the GBP amount from AlgoVoi’s reserves. The on-chain payout to the merchant cannot be reversed, but you the user are made whole. This is required under CRA 2015 fairness rules; “non-refundable once spent” as a blanket term is not enforceable in UK consumer law.
• Choose your cap deliberately. A £100 mandate exposes £100 of custody risk; a £10 mandate exposes £10. For untrusted agents, start small.

​

What this means for operators

1. Disclosure — your terms must tell the end-user that funds are custodied by AlgoVoi, not by you. Standard template clause available on request.
2. Float planning — APM revenue lands in AlgoVoi’s account, not yours. Settlements to you happen on-chain when the agent buys your resources. Tax and accounting follow standard crypto-settlement rules for your jurisdiction.
3. Refund routing — if your customer asks for a refund, you process it through your own payment rails (or via AlgoVoi if AlgoVoi is the merchant of record for the resource). The mandate balance does not flow back automatically — it’s already been spent on-chain.

​

Security model

• Unspent balance — refundable on mandate closure subject to identity verification (EMR 2011 reg 39 redemption rights).
• At-fault failures (wrong merchant settled, resource not delivered, double-charge) — refundable from AlgoVoi reserves via POST /internal/mandate-charges/{id}/refund. The on-chain payout to the merchant is irreversible, but AlgoVoi credits the user back in GBP and treasury reconciles. Required under CRA 2015 — blanket “non-refundable” terms are unenforceable.
• Successful purchases where the customer changes their mind — no automatic refund (the merchant has been paid, the resource was delivered). The customer’s recourse is with the merchant.

​

See also

• Architecture — payment protocols overview for how APM relates to x402, MPP, AP2, A2A
• Recurring payments for the Recurr (human-paid) and MPP-subscription models