Skip to content

docs: add production payment binding guidance #107

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
TateLyman wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add production payment binding guidance #107

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fdb3195
docs: add production payment binding guidance
TateLyman May 16, 2026
5587b6f
docs: clarify payment binding requirements
TateLyman May 16, 2026
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
10 changes: 6 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@ This repository contains the specification, core libraries, and example implemen
```
x402-a2a/
├── spec/
│ └── v0.1/
│ └── spec.md # The official x402 extension specification
│ ├── v0.1/
│ │ └── spec.md # v0.1 x402 extension specification
│ └── v0.2/
│ └── spec.md # Current x402 extension specification
│
├── schemes/ # Directory contains experimental x402 payment schemes drafted by partners and other contributors
│
Expand Down Expand Up @@ -52,7 +54,7 @@ This design provides both flexibility and ease of use, allowing developers to ei

## 📚 **Learn More**

* **[Specification](spec/v0.1/spec.md)**: The complete technical specification for the x402 extension.
* **[Specification](spec/v0.2/spec.md)**: The current technical specification for the x402 extension.
* **[Python Library](python/x402_a2a/README.md)**: The documentation for the Python implementation of the x402 extension.
* **[Python Examples](python/examples/)**: The directory containing demonstration applications for the Python implementation.
* **[A2A Protocol](https://github.com/a2aproject/a2a-python)**: The core agent-to-agent protocol.
Expand All @@ -61,4 +63,4 @@ This design provides both flexibility and ease of use, allowing developers to ei

## 🤝 **Contributing**

Contributions are welcome! Please read the [specification](spec/v0.1/spec.md) and the existing code to understand the project's design and goals. Then, feel free to open a pull request with your changes.
Contributions are welcome! Please read the [specification](spec/v0.2/spec.md) and the existing code to understand the project's design and goals. Then, feel free to open a pull request with your changes.
11 changes: 11 additions & 0 deletions spec/v0.2/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -479,6 +479,17 @@ If a payment fails, the server MUST set the x402.payment.status to payment-faile
* **Replay Protection**: Servers MUST track used nonces to prevent replay attacks.
* **Transport Security**: All A2A communication MUST use a secure transport layer like HTTPS/TLS.

### **10.1. Production Payment Binding Requirements**

Implementations that grant paid service results, mutate account state, or trigger downstream commerce workflows MUST bind payment verification to the exact task and paid resource being fulfilled:

* **Task and requirement binding**: Merchant Agents MUST validate that the submitted `PaymentPayload` matches a `PaymentRequirements` option that was previously issued for the same `taskId`. If the accepted requirements include a `resource` field, the Merchant Agent MUST compare it exactly before settlement. If the flow is embedded in a higher-level protocol, the implementation MUST also verify that the enclosing order or mandate identity matches the task being fulfilled.

@gemini-code-assist gemini-code-assist Bot May 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

The requirement to "compare it exactly" is slightly ambiguous. It should specify what the resource field is being compared against (e.g., the identifier of the resource the client is attempting to access). Consider clarifying this to ensure developers understand the binding target.

Suggested change:

  • Task and requirement binding: Merchant Agents MUST validate that the submitted PaymentPayload matches a PaymentRequirements option that was previously issued for the same taskId. If the accepted requirements include a resource field, the Merchant Agent MUST compare it exactly against the resource identifier being fulfilled before settlement. If the flow is embedded in a higher-level protocol, the implementation MUST also verify that the enclosing order or mandate identity matches the task being fulfilled.

* **Atomic claim before grant**: Merchant Agents MUST atomically record the accepted payment claim, such as the nonce, transaction authorization, or scheme-specific payment identifier, before returning paid artifacts or performing paid side effects. Duplicate submissions for an already claimed payment MUST NOT produce another paid result; implementations SHOULD return the existing receipt or fail with `DUPLICATE_NONCE`.

@gemini-code-assist gemini-code-assist Bot May 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

This section describes idempotency. Explicitly mentioning that the implementation should be idempotent for a given payment claim would improve clarity for developers familiar with this pattern.

Suggested change:

  • Atomic claim before grant: Merchant Agents MUST atomically record the accepted payment claim, such as the nonce, transaction authorization, or scheme-specific payment identifier, before returning paid artifacts or performing paid side effects. To ensure idempotency, duplicate submissions for an already claimed payment MUST NOT produce another paid result; implementations SHOULD return the existing receipt or fail with DUPLICATE_NONCE.

* **Settlement and finality**: Merchant Agents MUST NOT set `x402.payment.status` to `"payment-completed"` or release final paid artifacts until the settlement response satisfies the implementation's finality policy. The `"payment-verified"` status MAY be used after signature verification but before settlement is final.
* **Receipt history**: `x402.payment.receipts` MUST append every settlement attempt, including failures, and MUST NOT replace earlier receipt entries for the same task.
* **Scheme field checks**: When the payment scheme or facilitator exposes payer, recipient, network, asset, amount, or resource fields, Merchant Agents MUST compare those values against the issued `PaymentRequirements` and reject mismatches before granting service.
* **HTTP transport handling**: Implementations that expose A2A payment messages over HTTP SHOULD mark payment-required and paid-task responses with cache controls such as `Cache-Control: no-store, private`. Gateways and middleware MUST reject ambiguous duplicate payment metadata or payment headers instead of silently choosing one.

## **11\. References**

* [**A2A Protocol Specification**](https://a2a-protocol.org/latest/specification)
Expand Down
Loading