Automattic / Automattic/x402-Pay
Proposal: durable, sanitized settlement evidence for companion plugins
- Dominant language
- PHP
- Stars
- 2
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
Hi.
We're building a companion accounting integration for x402 Pay and found
a crash-recovery and data-minimization gap that may affect other accounting or
analytics companions as well.
A companion can observe a successful settlement only inside the
request that settled it, through `x402_pay_payment_settled`. If PHP or the
listener crashes after the facilitator settles but before the companion commits
its own record, that observation is gone. The callback context also contains
payer- and request-derived fields (`payer_wallet`, `path`, `resource_url`) that
probably should not become a durable cross-plugin data contract.
x402 Pay could solve this once for companion plugins:
1. Give the settlement-critical payment requirements a stable sanitized
snapshot identity.
2. Persist an allowlisted successful-settlement record before announcing it
through a new durable-only action.
3. Expose a small bounded cursor API so companions can replay missed records
within a documented retention window.
Our local prototype attaches the snapshot ID only to the client response copy
of `accepts[0].extra`; the connector's original requirements are sent unchanged
to `/verify` and `/settle`. For the current exact/EIP-3009 path, the added key
does not alter the transfer authorization fields. We also have a regression test
proving the extension is not forwarded to a strict facilitator. If another
extension location is preferable, we're happy to adapt the shape.
The durable record contains only versions, stable identities, canonical
WordPress resource ID, network, asset, integer base-unit amount, pay-to,
transaction, observation time, and final state. It excludes payer/signature,
cookies, IP, user agent, headers, raw URL/path/query, page content, credentials,
and facilitator raw responses.
The existing gate, facilitator calls, grants, receipts, legacy settlement
action, and optional reporter keep their existing contracts. With no companion
consumer, the successful-settlement path adds one local idempotent insert;
storage or new-listener failures never change paid access.
We have a tested local reference implementation and can open it as a linked
draft PR if this direction is useful. The API names, storage abstraction,
retention duration, and PR split are all open for discussion. We are willing to
stay engaged with review, follow-up fixes, tests, and user-facing documentation.
Would you be open to something in this direction, and is there an API/storage
shape you would prefer us to use?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the x402_pay_payment_settled callback, the existing /verify and /settle flow, and the tested local reference implementation. Check the regression test showing the snapshot extension is not forwarded to a strict facilitator. Done means an agreed API, storage abstraction, retention policy, durable replay behavior, and tests and documentation that preserve existing payment and access contracts.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, wordpress
- Domain
- backend-api-design, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100