Automattic / Automattic/x402-Pay

Proposal: durable, sanitized settlement evidence for companion plugins

Open
#46 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.