docs(api): document payer EOA address in payment reconciliation#105
docs(api): document payer EOA address in payment reconciliation#105aimen74 wants to merge 1 commit into
Conversation
Document payerEoaAddress alongside payerAddress across Request API request status and payment webhook documentation. - Add payerEoaAddress to payment.confirmed and payment.partial webhook payload examples. - Explain that payerAddress is the address used to make the payment, while payerEoaAddress is the payer's connected wallet address. - Clarify that the addresses may differ when a smart account is used and that either value can be null when unavailable. - Update the Webhooks & Events overview, Query Requests guide, and existing reconciliation release note. Validation: - Parsed all webhook JSON examples. - Ran mint broken-links. - Ran git diff --check.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Greptile SummaryThis PR documents the new
Confidence Score: 4/5Safe to merge after clarifying the The
Important Files Changed
Sequence Diagram%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Payer as Payer (EOA)
participant SA as Smart Account (ERC-4337 / Safe)
participant Chain as Blockchain
participant API as Request Network API
participant Dev as Integrator Webhook
Payer->>SA: Initiate payment
SA->>Chain: "Submit on-chain transaction (sender = contract address)"
Chain-->>API: Payment detected
Note over API: payerAddress = SA contract address<br/>payerEoaAddress = Payer EOA address
API->>Dev: payment.confirmed webhook
Dev-->>Dev: Reconcile using payerEoaAddress for human-controlled wallet identity
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Payer as Payer (EOA)
participant SA as Smart Account (ERC-4337 / Safe)
participant Chain as Blockchain
participant API as Request Network API
participant Dev as Integrator Webhook
Payer->>SA: Initiate payment
SA->>Chain: "Submit on-chain transaction (sender = contract address)"
Chain-->>API: Payment detected
Note over API: payerAddress = SA contract address<br/>payerEoaAddress = Payer EOA address
API->>Dev: payment.confirmed webhook
Dev-->>Dev: Reconcile using payerEoaAddress for human-controlled wallet identity
Reviews (1): Last reviewed commit: "docs(api): document payer EOA address in..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| @@ -199,6 +199,7 @@ All payment events include an `explorer` field linking to [Request Scan](https:/ | |||
| - `timestamp`: ISO 8601 formatted event timestamp | |||
| - `paymentProcessor`: Either `request-network` (crypto) or `request-tech` (fiat) | |||
| - `payerAddress`: Resolved payer wallet — the on-chain sender for plain direct payments, or the resolved payer for recurring and intent-based flows (Secure Payment Page, LiFi, Safe, ERC-4337, multicall). `null` when it cannot be determined. Included on `payment.confirmed` and `payment.partial` events (and their `.client_id` / `.checkout` variants). | |||
There was a problem hiding this comment.
payerAddress description contradicts new payerEoaAddress semantics for ERC-4337/Safe flows
The existing payerAddress description states it is the resolved payer for "Safe, ERC-4337, multicall" flows. If it is already resolved to the human-controlled address in those flows, payerEoaAddress would always equal payerAddress for those cases — defeating the field's purpose. The PR description and webhooks-events.mdx instead say payerAddress is the on-chain sender (which is a smart contract for ERC-4337/Safe), and payerEoaAddress provides the connected EOA. The phrase "or the resolved payer for recurring and intent-based flows (Secure Payment Page, LiFi, Safe, ERC-4337, multicall)" should be clarified to reflect that payerAddress is the contract address for smart-account flows and resolution to EOA is what payerEoaAddress provides.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| - `payerAddress` — the resolved payer wallet address for the payment (`null` when it can't be determined, e.g. for some contract-mediated flows) | ||
| - `payerEoaAddress` — the payer's connected wallet address (`null` when unavailable). It can differ from `payerAddress` when a smart account is used. |
There was a problem hiding this comment.
payerAddress and payerEoaAddress use different wording ("it can't be determined" vs "unavailable"), which is inconsistent given the PR description states both return null under the same condition. The AGENTS.md style guide requires consistent terminology throughout documentation.
| - `payerAddress` — the resolved payer wallet address for the payment (`null` when it can't be determined, e.g. for some contract-mediated flows) | |
| - `payerEoaAddress` — the payer's connected wallet address (`null` when unavailable). It can differ from `payerAddress` when a smart account is used. | |
| - `payerAddress` — the resolved payer wallet address for the payment (`null` when it cannot be determined, e.g. for some contract-mediated flows) | |
| - `payerEoaAddress` — the payer's connected wallet address (`null` when it cannot be determined). It can differ from `payerAddress` when a smart account is used. |
Context Used: AGENTS.md (source)
2 participants
TL;DR
Added documentation for the new
payerEoaAddressfield across API responses and webhook payloads.What changed?
A new
payerEoaAddressfield is now documented in the query requests reference, webhooks events overview, webhooks reference (including payload examples), and release notes. This field exposes the payer's connected wallet (EOA) address and is distinct frompayerAddress, which reflects the on-chain sender. The two values can differ when a smart account is used to make a payment. Both fields returnnullwhen the respective address cannot be determined.The release notes entry for payer wallet reconciliation was also updated to reflect that both
payerAddressandpayerEoaAddressare now included, replacing the previous description that only mentionedpayerAddress.How to test?
payment.confirmedorpayment.partialwebhook payload contains bothpayerAddress(the smart contract address) andpayerEoaAddress(the connected EOA).payerEoaAddressappears in the response fields alongsidepayerAddress.Why make this change?
Smart account usage means the on-chain sender (
payerAddress) is often a contract rather than the user's actual wallet. ExposingpayerEoaAddressgives integrators a reliable way to identify the human-controlled wallet behind a payment, which is important for reconciliation, compliance, and customer identification workflows.