Payment Gateway

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 Payment Gateway is the canonical public API entry point for all payment protocol traffic on the platform. Every payment verification request, checkout link creation, protocol handshake, and discovery query passes through this service. It is the outward-facing surface of a production multi-chain stablecoin payment infrastructure that settles directly wallet-to-wallet — AlgoVoi never holds, custodies, or pools merchant funds. The gateway runs at api.algovoi.co.uk and exposes 123 or more routes across seven distinct protocol namespaces. Compliance enforcement — sanctions screening, audit chain insertion, Object Lock archival, signed webhook delivery — is applied synchronously on every payment, without exception.

---

​

Overview

The gateway is deployed on a hardened compute node behind TLS termination, WAF, DDoS mitigation, and authenticated origin pull. The gateway and control plane operate on distinct router trees with separate authentication pipelines.

---

​

Payment verification flow

The core payment primitive is a verification request that confirms whether a given on-chain transaction constitutes valid settlement of a checkout. The flow proceeds in six steps. Step 1 — Customer pays on-chain. The customer sends a stablecoin (or accepted native asset) transfer from their wallet to the merchant’s receiving wallet on the relevant chain. The transaction produces a chain-native transaction identifier. Step 2 — Client submits to /v1/verify. The merchant’s integration layer (browser SDK, server webhook, or MCP tool) submits a POST /v1/verify request carrying the transaction ID, checkout token, chain identifier, and optionally the declared sender address. Step 3 — Gateway dispatches to facilitator cluster. The gateway forwards a verification sub-request to the stateless facilitator cluster. The sub-request carries: tx_id, chain, asset_id, expected_amount_microunits, expected_receiver, and network_id. The gateway holds no chain RPC keys itself — all on-chain queries are delegated to the facilitator. Step 4 — Facilitator returns a verdict. The facilitator queries the appropriate RPC endpoint or indexer for the given chain, extracts the transaction’s actual settled amount, asset, sender, and receiver, compares them against expected values, and returns a structured verdict containing: settled (boolean), amount_microunits, asset_id, sender_address, block_height, and finality_status. Step 5 — Gateway executes the compliance and audit pipeline. On a positive verdict (settled: true), the gateway runs four synchronous operations before responding to the caller:

• Payer wallet screened against OFSI, OFAC SDN, and EU Consolidated lists (daily refresh cadence). If a hit is recorded, the payment is blocked, the hit is appended to the screening_hits hash chain, and the tenant receives a compliance notification.
• Payment row inserted into the payment_ledger hash chain. Each row carries chain_position, content_hash, and prev_hash to form a tamper-evident append-only ledger.
• Audit row shipped to Backblaze B2 Object Lock bucket in COMPLIANCE mode, 7-year retention horizon.
• Signed webhook dispatched to the tenant’s registered endpoint. Signature uses HMAC-SHA256 with the tenant’s webhook secret; the X-AlgoVoi-Signature header carries the algvw_ prefixed value.

Step 6 — Verification response returned. The gateway returns a verification response to the original caller. The response mirrors the facilitator verdict and includes additional gateway-level metadata: compliance_cleared, audit_chain_position, webhook_dispatched, and verified_at.

---

​

Verification request schema

POST /v1/verify

​

Verification response schema

---

​

Hosted checkout

The hosted checkout system allows merchants to create multi-chain payment links without building any frontend. A link is created via a single API call; the resulting token resolves to a hosted page at dash.algovoi.co.uk/pay/{token} where the customer selects a chain, sees the correct wallet address, and submits their transaction ID for verification.

​

Creating a checkout link

POST /v1/payment-links

​

Checkout response

​

Status lifecycle

Once a checkout reaches paid status it is immutable. Subsequent verify calls against a paid token return the original verification response with a duplicate: true flag.

​

Checkout retrieval

GET /v1/payment-links/{token} returns the full checkout object in its current state. GET /v1/payment-links returns a paginated list of all checkouts for the authenticated tenant, sortable by created_at or status.

---

​

Protocol handlers

The gateway handles seven distinct payment and discovery protocols from a single base URL. Each protocol occupies its own endpoint namespace.

​

x402 handler

The x402 handler implements the HTTP 402 facilitator role as specified in the x402 v1 standard. When an x402-protected resource is accessed without payment proof, the gateway issues a 402 Payment Required response with a structured X-Payment-Required header. Upon receiving payment proof in X-Payment headers, the gateway verifies the proof, runs the compliance pipeline, and returns a 200 OK with an X-Payment-Receipt header containing a signed compliance receipt under the urn:x402:canonicalisation:jcs-rfc8785-v1 canonicalisation pin.

​

MPP handler

The MPP handler implements the Merchant Payment Protocol as defined at paymentauth.org/mpp. It issues WWW-Authenticate: Payment challenges, verifies mandate signatures, and emits MPP subscription receipts. Subscription mandates are stored in the control plane and evaluated at each pull cycle by the Recurr service. The gateway exposes a subscription demo fixture at /mpp/sub/demo/mpp-sub-test-daily-base for integration testing without tenant credentials.

​

AP2 handler

The AP2 handler implements Google’s Agent Payment Protocol v0.1. It generates PaymentMandate objects with structured capability declarations, verifies mandate signatures against on-chain wallet proofs, and anchors open_mandate_hash values for cross-implementation validation. AP2 #265 is the upstream issue tracking the open_mandate_hash extension proposal authored by AlgoVoi.

​

A2A handler

The A2A handler implements the Google Agent-to-Agent v1.0 protocol. The /.well-known/agent.json endpoint publishes the AlgoVoi agent card declaring three skills: verify-payment, create-checkout, and check-status. The /message:send endpoint accepts A2A task envelopes and returns task results. Autonomous agents that trigger a 402 during A2A skill invocation receive a payment-required envelope and can retry with proof attached — the gateway handles the pay-and-retry loop transparently.

​

Solana Actions handler

The Solana Actions handler follows the Solana Actions and Blinks standard. GET /actions/checkout/{token} returns action metadata including label, description, icon URL, and a links.actions array with the POST endpoint. POST /actions/checkout/{token} accepts a { account } body carrying the payer public key and returns a serialised, unsigned transaction for the Blinks wallet UI to present for signing. The checkout token is embedded in the transaction memo field to enable automatic post-sign verification.

​

xChain handler

The xChain handler routes cross-chain payments from a source chain (any EVM or Solana) to any AlgoVoi-supported destination chain. It co-ordinates with Allbridge for non-CCTP routes and with Circle CCTP V2 for Circle-native USDC bridging (approximately 50-second finality on Solana). A private key never leaves the browser extension; the handler receives a signed intent and returns bridge calldata for the extension to submit. Bridge state is tracked on dedicated cross-chain bridge infrastructure.

---

​

Bazaar and discovery

The Bazaar integration makes AlgoVoi the first compliance-aware Bazaar facilitator. Every payable resource published through the gateway carries embedded compliance metadata — tenant risk tier, KYC status flag, and a compliance_posture summary — so that Bazaar consumers can make admission decisions before initiating payment.

​

Public endpoints

GET /discovery/resources returns the public Bazaar catalog. No authentication is required. The response is a paginated list of resource objects, each containing:

​

Publishing a resource

POST /v1/resources registers a new payable resource. The tenant must be mainnet-active (KYC approved). The endpoint URL is screened against SSRF guards and threat-intel feeds at registration time.

---

​

Compliance enforcement

Compliance runs synchronously on every payment. The pipeline cannot be bypassed, deferred, or disabled at the tenant level. It consists of five sequential operations. Sanctions screening. The payer wallet address is matched against three consolidated sanctions lists maintained on the gateway: OFSI (UK), OFAC SDN (US), and EU Consolidated List. List data is refreshed daily from authoritative sources. Matching uses both exact-address and fuzzy-address normalisation to catch checksummed variants. Verdicts are returned in SAMLA 2018 s.20 compliant form — generic outcome categories only, never naming the specific list that produced a hit. Hit recording. If a sanctions hit is found, the payment is blocked unconditionally. The hit is appended to the screening_hits hash chain with payer_address, list_code (a generic category, not the list name), outcome (BLOCKED or CLEAR), and screened_at. The tenant receives a payment.blocked.compliance webhook event carrying only the generic outcome. Audit chain insertion. Every payment that clears sanctions is inserted into the payment_ledger hash chain. Each row carries: The hash chain is tamper-evident: any modification to a historical row breaks the chain from that position forward. Object Lock archival. Every audit row is also shipped to a Backblaze B2 bucket configured with Object Lock in COMPLIANCE mode and a 7-year retention period (to 2033). No software path — including AlgoVoi operators — can delete or modify objects within their retention window. This property supports FCA / EMR audit obligations. Webhook delivery. A signed payment.verified webhook is dispatched to the tenant’s registered endpoint. The HMAC-SHA256 signature is computed over the raw request body using the tenant’s webhook secret. The X-AlgoVoi-Signature header carries the signature prefixed with algvw_.

​

Pre-payment screening endpoint

POST /compliance/screen is a public endpoint that accepts a wallet address and returns a SAMLA-compliant screening result without creating a payment. This allows merchants to pre-screen payers before generating a checkout link. No authentication is required on this endpoint.

​

Compliance attestation endpoint

GET /compliance/attestation is a public endpoint returning the operator’s current compliance posture. It carries: The attestation endpoint also returns a Composite Trust Query (CTQ) shaped response compatible with the draft-hopley-x402-composite-trust-query Internet-Draft, enabling downstream verifier consumers to parse the attestation in a protocol-standard form.

---

​

MCP integration

The gateway exposes a Model Context Protocol surface at /mcp/*, mirroring the 28-tool inventory of the algovoi-mcp server available on PyPI as algovoi-mcp and on npm as @algovoi/mcp-server. AI agents and LLM tool-use integrations can call these tools directly over MCP without managing API keys in prompt context.

​

Tool inventory (28 tools)

The same tool surface is available through the MCP Registry at mcp.algovoi.co.uk for discovery by compliant MCP clients.

---

​

Authentication

All authenticated endpoints require two headers: API keys use the prefix algv_ (standard), algv_admin_ (admin, 14 scopes), or algv_ro_ (read-only). Keys are never stored in plaintext; only a SHA-256 hash is retained after creation. Multi-key rotation is supported: an old key remains valid during the transition window while a new key is active. The Idempotency-Key header is supported on all POST endpoints that create resources. Idempotency windows are 24 hours. Duplicate requests within the window return the original response with an X-Idempotency-Replay: true header.

---

​

Public endpoints (no authentication required)

---

​

Chain and asset support

Price oracle. When native-asset payments are accepted, the gateway converts ALGO, VOI, HBAR, XLM, ETH, and SOL to USD cents at settlement time. The oracle queries multiple price feeds and applies median outlier rejection before accepting a price. If the oracle is unavailable, native-asset payments are queued and settled when the oracle recovers; stablecoin payments are unaffected.

---

​

Rate limits and error codes

The gateway enforces a rate limit of 300 requests per minute per API key, with a burst allowance of 60 requests. Exceeding the limit returns 429 Too Many Requests with a Retry-After header indicating the earliest retry time. All error responses carry a structured JSON body with error_code (snake_case string), message (human-readable), and an optional field_errors array for validation failures.

---

​

Webhook events

The gateway delivers signed webhook events to tenant-registered endpoints for all significant payment and compliance lifecycle events. Webhook requests carry X-AlgoVoi-Signature, X-AlgoVoi-Event, X-AlgoVoi-Delivery (unique delivery ID), and X-AlgoVoi-Timestamp headers. The delivery ID is stable across retries; the timestamp is the original dispatch time.