diff --git a/docs/ack-pay/interoperability.mdx b/docs/ack-pay/interoperability.mdx new file mode 100644 index 00000000..7ab8a99b --- /dev/null +++ b/docs/ack-pay/interoperability.mdx @@ -0,0 +1,107 @@ +--- +title: "Interoperability with MPP and x402" +description: "Non-normative mapping between ACK-Pay concepts and emerging HTTP 402 payment protocols." +--- + +ACK-Pay is rail-neutral: it defines payment requests, execution evidence, and +verifiable receipts without requiring a specific settlement network or transport. +[MPP](https://mpp.dev) and [x402](https://x402.org) are both evolving quickly +around HTTP 402 flows. This page maps ACK-Pay primitives to those protocols so +builders can compose them without coupling ACK to either one. + + + This mapping is **non-normative**. It explains where ACK can compose with + MPP/x402 and what ACK adds beyond rail-specific payment execution. Field names + and wire formats may change as those protocols evolve. + + +## Concept mapping + +| ACK-Pay | MPP | x402 | +| --- | --- | --- | +| Payment Request | Challenge | `PaymentRequired` / `PaymentRequirements` | +| Payment option | Payment method / payment request | `scheme` + `network` + requirements | +| Payment execution proof | Credential | `PaymentPayload` / `PAYMENT-SIGNATURE` | +| Payment receipt VC | Receipt | `PAYMENT-RESPONSE` settlement result; optional signed-receipt extension | +| Receipt issuer | Server / payment verifier | Facilitator and/or resource server | +| Human oversight / policy | Client / payment-service policy | Client / facilitator policy layer | + +## What ACK adds + +ACK-Pay keeps the **receipt** layer stable regardless of how funds move: + +- **Verifiable Credentials** — receipts are signed VCs that any relying party can + verify with standard DID resolution, not just the original HTTP server. +- **Transport-agnostic requests** — the same payment request shape works over + HTTP 402, MCP, WebSockets, or A2A; MPP and x402 today focus primarily on HTTP. +- **Policy and HITL hooks** — spend limits, approvals, and compliance metadata + live in ACK's payment-service layer and can wrap MPP/x402 execution underneath. + +MPP and x402 remain the right choice when you need rail-specific execution +(exact stablecoin transfer, facilitator verification, MCP tool billing). ACK +sits above or beside them as the **audit and identity layer**. + +## Composition pattern + +A typical stack: + +1. **Server** issues an HTTP 402 response whose JSON body is an ACK-Pay + **Payment Request payload**. That payload includes a signed + `paymentRequestToken` JWT — clients must handle the full JSON body, not a bare + token alone. +2. **Client** pays via an x402 facilitator or MPP credential exchange. +3. **Receipt Service** issues an ACK Receipt VC whose `credentialSubject.metadata` + carries opaque references to the rail-specific proof — settlement hash, + facilitator receipt ID, MPP session ID, etc. +4. **Server** verifies the ACK Receipt with the full trust checks: signature, + trusted issuer, revocation status, payment-request binding, and matching + payment option/details. Rail-specific `metadata` fields remain optional and + policy-specific. + +The core VC shape does not change when the settlement rail changes; only +`metadata` extensions differ. + +### Example metadata extensions + +```json +{ + "credentialSubject": { + "paymentRequestToken": "", + "paymentOptionId": "usdc-base-sepolia", + "metadata": { + "settlementNetwork": "eip155:8453", + "settlementReference": "0xabc123...", + "x402": { + "scheme": "exact", + "paymentSignature": "" + }, + "mpp": { + "sessionId": "mpp-session-abc", + "credentialId": "cred-xyz" + } + } + } +} +``` + +Servers should treat `x402` and `mpp` blocks as **opaque extension metadata**: +ACK-Pay verification covers signature, issuer trust, revocation, and +payment-request binding; applications decide which extension fields are required +for their policy. + +## When to use which layer + +| Need | Start with | +| --- | --- | +| HTTP 402 paywall on a single API | x402 or MPP transport + ACK receipt for audit | +| Multi-rail options (card + stablecoin) | ACK Payment Request with multiple `paymentOptions` | +| Agent-to-agent commerce with DID identity | ACK-ID + ACK-Pay end-to-end | +| MCP tool billing | MPP challenge flow; ACK receipt for cross-service proof | + +## Related reading + +- [Receipt Verification](/ack-pay/receipt-verification) — ACK Receipt format and + metadata extension points +- [Payment Service](/ack-pay/payment-service) — bridging to other protocols +- [Future Directions](/overview/future-directions) — planned x402 interop work + \ No newline at end of file diff --git a/docs/ack-pay/receipt-verification.mdx b/docs/ack-pay/receipt-verification.mdx index ec449e4c..cc234f7b 100644 --- a/docs/ack-pay/receipt-verification.mdx +++ b/docs/ack-pay/receipt-verification.mdx @@ -77,6 +77,9 @@ raw payment credentials, or sensitive customer data in receipt metadata. For agent-commerce flows that compose ACK-Pay with MPP, x402, AP2, or a policy engine, a receipt can carry references like: +See [Interoperability with MPP and x402](/ack-pay/interoperability) for a +concept mapping and composition patterns. + ```json { "credentialSubject": { diff --git a/docs/docs.json b/docs/docs.json index 2f6da923..0837c899 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -69,6 +69,7 @@ "ack-pay/receipt-verification", "ack-pay/hitl", "ack-pay/operational-considerations", + "ack-pay/interoperability", "ack-pay/summary" ] },