ap2-iso20022: Agent-payment mandates โ wire-valid ISO 20022
Bridge AP2 (Google's Agent Payments Protocol) and x402
(Coinbase's HTTP-402) mandates into ISO 20022 pain.001 / pacs.008 records โ
with spending-cap, expiry and authorisation guardrails, and an MCP
server. These agentic-payment protocols authorise a payment; this library
turns that authorisation into the bank-rail message that actually settles it
โ the rail the card networks and stablecoins don't cover.
Latest release: v0.0.1 โ 5 MCP tools over stdio, pure-Python (only mcp),
100% branch coverage, for Python 3.10+. Output feeds straight into
pain001 / pacs008 to generate wire-valid XML.
Part of the ISO 20022 MCP suite.
Why
An agent with a signed AP2 mandate (or an x402 payment authorisation) can prove
it's allowed to pay โ but nothing in those protocols emits the pain.001 a
bank needs to move the money. ap2-iso20022 is that missing hop. And because
moving money is consequential, it only transforms and validates โ producing
the ISO record is deliberately separate from generating and sending it, so the
actual payment stays an explicit, guarded step.
Install
pip install ap2-iso20022
uvx ap2-iso20022
MCP client config (e.g. Claude Desktop):
{
"mcpServers": {
"ap2-iso20022": {
"command": "ap2-iso20022-mcp"
}
}
}
Flow: normalise โ guardrail โ convert
from ap2_iso20022 import bridge
mandate = bridge.from_ap2({
"intent_id": "AP2-CoffeeRun-7",
"payer": "Alice's Shopping Agent",
"payer_account": "DE89370400440532013000",
"merchant_name": "Blue Bottle Coffee",
"payee_account": "GB29NWBK60161331926819",
"amount": "12.50", "currency": "EUR", "memo": "oat latte",
"spending_limit": "50.00",
"signature": "eyJ...", "signature_type": "jws",
})
check = bridge.check_mandate(mandate, as_of="2026-03-02T09:00:00")
assert check["ok"]
record = bridge.to_pain001(mandate)
normalize_ap2 โ AP2 mandate payload โ canonical mandate.
normalize_x402 โ x402 payment payload โ canonical mandate.
check_mandate โ Guardrail: required fields, spending cap, expiry (with as_of), authorisation proof.
to_pain001 โ Canonical mandate โ pain.001 record (customer credit transfer).
to_pacs008 โ Canonical mandate โ pacs.008 record (FI-to-FI).
The output field names and types match what pain001 / pacs008 expect
(validated against their JSON schemas), so to_pain001(mandate) โ pain001
generate_message โ XSD-valid pain.001 with no glue.
Guardrails
check_mandate returns {ok, violations, warnings}:
- required fields โ payer/payee name + account, amount, currency
- spending cap โ
amount <= max_amount when a cap is present
- expiry โ refuses an expired mandate when you pass
as_of
- authorisation proof โ warns when no
proof_type/proof_value is present
It never moves money; it tells you whether the mandate is safe to act on.
The suite
Part of a family of vendor-neutral, Python-native ISO 20022 MCP servers:
Development
git clone https://github.com/sebastienrousseau/ap2-iso20022
cd ap2-iso20022
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest
ruff check ap2_iso20022 tests && black --check ap2_iso20022 tests && mypy ap2_iso20022
Licence
Licensed under the Apache License, Version 2.0.
mcp-name: io.github.sebastienrousseau/ap2-iso20022