Skip to content

docs(ack-pay): map ACK-Pay concepts to MPP and x402 #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
milogiren wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(ack-pay): map ACK-Pay concepts to MPP and x402 #142

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/ack-pay/interoperability.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# ACK-Pay Interoperability: MPP and x402

> **Status:** Non-normative. This page describes conceptual mappings only and does not add
> required fields to the `PaymentReceiptCredential` schema or change verifier semantics.

ACK-Pay already models the core primitives needed for agent commerce: a server-issued
payment request, client/payment-service execution, and a verifiable receipt. Two emerging
protocols — MPP and x402 — model similar flows around HTTP 402. This page maps ACK-Pay
concepts to both, so implementers can compose ACK with either without forcing
protocol-specific fields into the ACK core schema.

## 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 / signed receipt extension |
| Receipt issuer | Server / payment verifier | facilitator / resource server |
Comment on lines +19 to +20

@coderabbitai coderabbitai Bot Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- target documentation files ---'
fd -t f -i 'interoperability|receipt-verification' docs

printf '%s\n' '--- interoperability.mdx ---'
target=$(fd -t f -i 'interoperability' docs | head -n 1)
cat -n "$target" | sed -n '1,110p'

printf '%s\n' '--- receipt-verification.mdx ---'
receipt=$(fd -t f -i 'receipt-verification' docs | head -n 1)
cat -n "$receipt" | sed -n '1,115p'

printf '%s\n' '--- relevant ACK-Pay and x402 terminology ---'
rg -n -i -C 3 'receiptService|SettlementResponse|signed receipt|offer-receipt|payment-response|payment verifier|receipt issuer|facilitator|resource server|credentialSubject|metadata' docs

Repository: agentcommercekit/ack

Length of output: 26076

🌐 Web query:

x402 official documentation PAYMENT-RESPONSE SettlementResponse optional signed receipt offer-receipt extension facilitator resource server

💡 Result:

In the x402 protocol, the PAYMENT-RESPONSE header is a standardized HTTP header used by the resource server to communicate the outcome of a payment settlement to the client [1][2]. It contains a Base64-encoded SettlementResponse object [1][3][2]. The SettlementResponse schema includes the following fields: success (boolean), transaction (string; blockchain transaction hash), network (string; CAIP-2 format), errorReason (optional string), payer (optional string), amount (optional string), and extensions (optional object) [3][4]. The optional signed receipt is provided through the "offer-receipt" extension [5][6]. When this extension is active: 1. On 200 OK responses, the server signs a receipt confirming service delivery and payment receipt [5][6]. 2. This receipt is included in the extensions field of the SettlementResponse object, which is then transmitted via the PAYMENT-RESPONSE header [5][6][7]. 3. The receipt includes fields such as resourceUrl, payer, network, issuedAt, and an optional txHash [5][6][7]. A facilitator is an optional service that assists the resource server in verifying payment payloads and settling transactions on the blockchain [8][9]. The resource server may interact with a facilitator server by sending the payment payload and details to the facilitator's /verify or /settle endpoints [8]. The facilitator then performs the requested action (such as broadcasting the transaction) and returns a response, which the resource server uses to finalize the settlement and populate the PAYMENT-RESPONSE header [10][8]. Alternatively, servers may use in-process "self-facilitation" to perform these tasks locally [8][11].

Citations:

🌐 Web query:

site:docs.x402.org/extensions/offer-receipt x402 receipt issuer resource server signed receipt

💡 Result:

The x402 protocol uses a specialized extension to handle signed offers and receipts, providing cryptographic proof of interaction between a resource server and a client [1]. In this workflow, the resource server's role regarding receipts is as follows: 1. Signed Offers (402 Responses): When the resource server returns a 402 Payment Required response, the Offer & Receipt extension signs an offer for each accepted payment scheme [1]. This offer commits to specific payment terms, including the network, amount, payment destination, and a validity timestamp [1]. 2. Signed Receipts (200 Responses): After a client completes the payment, the resource server issues a signed receipt upon returning a 200 OK response [1]. This receipt acts as confirmation of service delivery and includes details such as the resource URL, the payer's address, the network, and an issuance timestamp [1]. These receipts are included in the extensions field of the PAYMENT-RESPONSE header [1]. The extension supports verification via EIP-712 or JWS signatures, allowing clients to programmatically verify that the receipt was issued by the trusted resource server [1]. Implementation involves registering the offer-receipt extension with the x402ResourceServer instance on the backend [1].

Citations:

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- ACK role definitions ---'
for f in $(fd -t f -i 'components-roles|server-initiated-sequence|payment-service' docs); do
  printf '\n--- %s ---\n' "$f"
  rg -n -C 5 -i 'Receipt Service|receiptService|Payment Service|facilitator|settlement|issuer|verif' "$f"
done

printf '%s\n' '--- all x402 references in documentation ---'
rg -n -C 4 -i 'x402|SettlementResponse|PAYMENT-RESPONSE|offer-receipt|signed receipt' docs

Repository: agentcommercekit/ack

Length of output: 28856

Separate receipt, settlement, and verification roles.

  • PAYMENT-RESPONSE carries a SettlementResponse; only the optional offer-receipt extension adds a signed receipt. Map the x402 receipt issuer to the resource server and the settlement actor to the facilitator. Map the ACK receipt issuer to Receipt Service, not the server or payment verifier.
  • Move evidence under credentialSubject.metadata in the example to match the documented receipt schema.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ack-pay/interoperability.mdx` around lines 19 - 20, Update the
interoperability mapping table to distinguish settlement and receipt roles: map
x402’s receipt issuer to the resource server, settlement actor to the
facilitator, and ACK receipt issuer to Receipt Service. In the receipt example,
move evidence under credentialSubject.metadata to match the documented schema.

Source: MCP tools

| Human oversight / policy | client/payment-service policy | client/facilitator policy layer |

## Where ACK adds value

- **Rail-neutral core.** ACK-Pay does not depend on MPP or x402; either can sit underneath
an ACK-Pay flow as the execution rail.
- **Verifiable receipts.** ACK receipts are portable, signed credentials rather than a
protocol-specific response object.
- **Composable metadata.** Protocol-specific references (e.g. an x402 payment response
hash, or an MPP session id) can be carried as opaque extension metadata on the receipt
without changing the required schema fields.

## Example: carrying an execution reference in receipt metadata

```json
{
"type": ["VerifiableCredential", "PaymentReceiptCredential"],
"credentialSubject": {
"paymentRequestToken": "...",
"paymentOptionId": "...",
"evidence": {
"executionRef": "x402:0xabc123...",
"settlementNetwork": "base"
}
}
Comment on lines +38 to +45

@coderabbitai coderabbitai Bot Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Place protocol-specific data under credentialSubject.metadata.

The existing receipt contract defines credentialSubject.metadata as the optional extension point. This example places evidence directly under credentialSubject, so implementations that copy it will use a different field path.

Proposed fix 
   "credentialSubject": {
     "paymentRequestToken": "...",
     "paymentOptionId": "...",
-    "evidence": {
-      "executionRef": "x402:0xabc123...",
-      "settlementNetwork": "base"
+    "metadata": {
+      "evidence": {
+        "executionRef": "x402:0xabc123...",
+        "settlementNetwork": "base"
+      }
     }
   }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"credentialSubject": {
"paymentRequestToken": "...",
"paymentOptionId": "...",
"evidence": {
"executionRef": "x402:0xabc123...",
"settlementNetwork": "base"
}
}
"credentialSubject": {
"paymentRequestToken": "...",
"paymentOptionId": "...",
"metadata": {
"evidence": {
"executionRef": "x402:0xabc123...",
"settlementNetwork": "base"
}
}
}
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ack-pay/interoperability.mdx` around lines 38 - 45, Update the
interoperability receipt example so the protocol-specific evidence object is
nested under credentialSubject.metadata, while keeping paymentRequestToken and
paymentOptionId directly under credentialSubject. Ensure executionRef and
settlementNetwork remain within evidence at the new metadata path.

}