From c83663f48c406e368e15653b356d0faa8f91a79c Mon Sep 17 00:00:00 2001 From: EfeDurmaz16 Date: Fri, 15 May 2026 19:16:43 +0300 Subject: [PATCH 1/2] docs: add MPP and x402 interop guide --- docs/ack-pay/mpp-x402-interop.mdx | 143 ++++++++++++++++++++++++++++++ docs/docs.json | 1 + 2 files changed, 144 insertions(+) create mode 100644 docs/ack-pay/mpp-x402-interop.mdx diff --git a/docs/ack-pay/mpp-x402-interop.mdx b/docs/ack-pay/mpp-x402-interop.mdx new file mode 100644 index 0000000..08d28c8 --- /dev/null +++ b/docs/ack-pay/mpp-x402-interop.mdx @@ -0,0 +1,143 @@ +--- +title: "MPP and x402 Interoperability" +description: "How ACK-Pay concepts relate to MPP and x402 payment flows." +--- + +ACK-Pay is designed as a payment pattern for agent commerce rather than a +single settlement rail. That makes it complementary to HTTP 402 payment +protocols such as [MPP](https://mpp.dev/overview) and +[x402](https://docs.x402.org/introduction), both of which define concrete +ways for clients and agents to satisfy payment requirements. + +This page describes how ACK-Pay concepts can map to MPP and x402 without +requiring ACK implementations to adopt either protocol as their only payment +transport. + +## Concept Mapping + +| ACK-Pay concept | MPP equivalent | x402 equivalent | Notes | +| ----------------------- | ---------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Payment Request | Challenge | `402 Payment Required` response with payment requirements | ACK keeps the request transport-agnostic. MPP and x402 commonly deliver it through HTTP 402, and MPP also defines MCP and WebSocket transports. | +| Payment Option | Payment method inside a Challenge | Accepted scheme/network requirement | ACK can list multiple options for different rails, currencies, or Payment Services. | +| Payment Service | MPP server/payment method implementation, or gateway | Facilitator or server-side verifier/settler | The Payment Service can execute directly on a rail, delegate to an x402 facilitator, or verify an MPP credential. | +| Payment execution proof | Credential | Payment payload | This is the client-side proof submitted after selecting an acceptable payment option. | +| ACK Receipt | Receipt | Payment response, signed receipt, or settlement proof | ACK Receipts use Verifiable Credentials, so they can wrap or reference protocol-specific receipts. | +| Receipt Service | Receipt issuer/verifier | Facilitator/server receipt issuer | ACK separates receipt issuance from the original seller or server when useful for trust and auditability. | + +## HTTP 402 Flow + +An ACK-Pay server-initiated flow can be exposed over HTTP 402 while preserving +ACK's higher-level receipt and identity semantics. + + + + The Server Agent returns a `402 Payment Required` response. The response can + include an MPP Challenge, an x402 payment requirement, or an ACK Payment + Request payload that references one or more compatible payment options. + + + The Client Agent chooses a payment option and applies its local policy + checks before signing, authorizing, or submitting any payment credential. + + + The Payment Service verifies the request, executes settlement directly or + through an MPP/x402-compatible endpoint, and records the protocol-specific + settlement evidence. + + + The Receipt Service issues an ACK Receipt that includes the ACK payment + fields and can reference the MPP Receipt, x402 payment response, facilitator + settlement result, or transaction identifier. + + + The Client Agent presents the receipt or protocol credential back to the + Server Agent. The Server verifies the receipt, request binding, recipient, + amount, expiry, and issuer trust before delivering the service. + + + +## MCP Tool Payments + +MPP defines an MCP transport for paid tool calls. ACK-Pay can use the same +pattern while preserving ACK-ID identity and ACK Receipt verification: + +1. The MCP server returns a payment-required result for a tool call. +2. The response includes an ACK Payment Request or a reference to an MPP + Challenge/x402 payment requirement. +3. The client checks user, agent, merchant, amount, and tool-call policy before + signing or authorizing payment. +4. The client submits the selected credential through the relevant protocol. +5. The MCP server returns the tool result with an ACK Receipt or a receipt + reference that can be verified later. + +This keeps the payment transport specific enough for interoperable clients +while allowing ACK systems to retain stronger identity, receipt, and audit +semantics. + +## Policy Before Signing + +For agent payments, the critical integration boundary is before the agent signs +or submits a payment credential. + +ACK implementations that bridge to MPP or x402 should ensure that local policy +checks can evaluate at least: + +- requested amount, currency, decimals, and recipient +- selected rail, network, facilitator, or Payment Service +- merchant or Server Agent identity +- original request identifier and expiry +- tool call, API endpoint, or service being purchased +- replay and idempotency binding + +If a policy check fails, the client should decline before producing an MPP +Credential, x402 payment payload, wallet signature, card authorization, or any +other executable payment artifact. + +## Receipt Evidence + +ACK Receipts can carry protocol-specific evidence without replacing the +underlying protocol receipt. A receipt subject can include stable references +such as: + +```json +{ + "paymentOptionId": "x402-usdc-base", + "metadata": { + "settlementProtocol": "x402", + "settlementNetwork": "eip155:8453", + "settlementReference": "0x...", + "paymentService": "https://payments.example.com/x402", + "facilitator": "https://facilitator.example.com", + "policyRef": "did:web:client.example.com#spend-policy-v3", + "policySnapshotHash": "sha256:..." + } +} +``` + +The exact fields can vary by rail. The important requirement is that the ACK +Receipt remains bound to the original `paymentRequestToken`, selected +`paymentOptionId`, recipient, amount, and trusted issuer. + +## Implementation Guidance + +- Treat MPP and x402 as transport/settlement integrations, not replacements for + ACK-ID or ACK Receipt verification. +- Keep ACK Payment Request and Receipt fields stable even when the underlying + payment protocol evolves. +- Prefer explicit request identifiers, expiry timestamps, body digests, and + idempotency keys for replay resistance. +- Preserve protocol-specific receipts as evidence references instead of copying + opaque payloads into application logs. +- Avoid exposing private wallet keys, card credentials, facilitator secrets, or + Payment Service credentials in agent-visible prompts or traces. + +## Future Work + +Potential follow-up work includes: + +- typed examples for an ACK Payment Service that verifies an x402 payment + response +- an ACK Receipt profile for MPP Receipts and Credentials +- a paid MCP tool demo that returns ACK Receipts +- conformance tests for request binding, expiry, idempotency, and receipt + verification across ACK-Pay, MPP, and x402 flows diff --git a/docs/docs.json b/docs/docs.json index 2f6da92..13dfa23 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -67,6 +67,7 @@ "ack-pay/payment-service", "ack-pay/payment-request-payload", "ack-pay/receipt-verification", + "ack-pay/mpp-x402-interop", "ack-pay/hitl", "ack-pay/operational-considerations", "ack-pay/summary" From 4bfdef24d8c657b8c8136c5db932d3e308fc837a Mon Sep 17 00:00:00 2001 From: EfeDurmaz16 Date: Sat, 16 May 2026 01:09:37 +0300 Subject: [PATCH 2/2] docs: include payment signature mapping Signed-off-by: EfeDurmaz16 --- docs/ack-pay/mpp-x402-interop.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ack-pay/mpp-x402-interop.mdx b/docs/ack-pay/mpp-x402-interop.mdx index 08d28c8..ff289af 100644 --- a/docs/ack-pay/mpp-x402-interop.mdx +++ b/docs/ack-pay/mpp-x402-interop.mdx @@ -20,7 +20,7 @@ transport. | Payment Request | Challenge | `402 Payment Required` response with payment requirements | ACK keeps the request transport-agnostic. MPP and x402 commonly deliver it through HTTP 402, and MPP also defines MCP and WebSocket transports. | | Payment Option | Payment method inside a Challenge | Accepted scheme/network requirement | ACK can list multiple options for different rails, currencies, or Payment Services. | | Payment Service | MPP server/payment method implementation, or gateway | Facilitator or server-side verifier/settler | The Payment Service can execute directly on a rail, delegate to an x402 facilitator, or verify an MPP credential. | -| Payment execution proof | Credential | Payment payload | This is the client-side proof submitted after selecting an acceptable payment option. | +| Payment execution proof | Credential | Payment payload / Payment-Signature | This is the client-side proof submitted after selecting an acceptable payment option. | | ACK Receipt | Receipt | Payment response, signed receipt, or settlement proof | ACK Receipts use Verifiable Credentials, so they can wrap or reference protocol-specific receipts. | | Receipt Service | Receipt issuer/verifier | Facilitator/server receipt issuer | ACK separates receipt issuance from the original seller or server when useful for trust and auditability. |