> For the complete documentation index, see [llms.txt](https://peoplescourt.ai/llms.txt). This page is also available as Markdown.

Guides

# How to handle x402 payment disputes

When an AI agent pays through x402 and the service fails to deliver, first find out whether the payment settled and who controls the funds. Preserve the agreed terms, payment receipt, and evidence of delivery or failure. People’s Court’s open-source x402 dispute extension links the accepted terms to the payment and packages the evidence for neutral arbitration when the parties agree to use the forum.

## An agent paid, but the API returned an error

Suppose a buyer’s agent pays for a report and the seller’s API returns an error instead. The error alone does not say whether the payment settled, and a settlement receipt does not say whether the promised report was delivered. Before paying again, match the request and payment identifiers to the seller’s logs and the facilitator’s result. Ask the seller to check the same request and confirm whether it can deliver or refund.

## What should you keep for an agent payment dispute?

- **Offer and acceptance:** the resource, price, delivery promise, dispute terms, and the record showing which version each side accepted.
- **Authority:** the buyer and seller behind the agents and what each agent was authorized to do.
- **Payment:** the payment identifier, amount, network, and verification or settlement receipt.
- **Performance:** the request identifier, timestamps, status or response, delivery logs, and any refund or retry record. Leave secrets and unrelated payloads out of the dispute packet.

## Who can issue an x402 refund?

For an ordinary settled x402 payment, identify the merchant or other party with the ability to send a refund. People’s Court’s x402 dispute extension preserves a verifiable transaction packet while the existing payment flow stays in place. Verify each agent’s authority separately.

For a payment set up under a separate escrow or refundable-payment protocol such as x402r, check that transaction’s referral, refund, and execution terms. Those terms determine which funds, if any, remain available and who can act. An arbitration Award decides the parties’ obligations; a refund or transfer still needs an authorized payment mechanism.

## Design the dispute path before the next payment

Tell both sides what counts as delivery, how to record acceptance of the terms, how long they have to raise a dispute, who decides it, and who can carry out a refund. For a People’s Court integration, start with the agent-to-agent model clause and theAI agent dispute resolution workflow. The [x402 protocol documentation](https://docs.x402.org/introduction) explains the payment layer, and thePeople’s Court integration page covers the dispute packet and current x402r intake status.

## Build dispute resolution into your x402 integration

Explore the open-source extensionDiscuss an integration