nick-doc/.taskmaster/docs/prd-request-network-in-house-checkout.md

PRD: Request Network In-House Checkout

Status: Draft — updated after 2026-05-28 dev webhook probe Date: 2026-05-27 Related: 01 - Architecture/Request Network Integration Constraints.md §1; PRD - Request Network Migration and Funds Management.md Owner: Backend payments + Frontend

---

1. Problem

Buyers paying through Request Network (RN) are redirected from Amanat to RN's hosted page at pay.request.network/?token=…. That page has three concrete problems:

1. Rabby is not supported. A meaningful portion of our user base pays from Rabby. The hosted page does not detect it (no EIP-6963 enumeration, hard-coded MetaMask/WalletConnect/Coinbase). For those users, checkout fails before a transaction is even attempted.
2. The page is brand-divergent. Buyers leave the Amanat domain mid-flow, which is a trust and conversion cost we can avoid.
3. The page relies on RN's choice of infrastructure. Observed in our own probe: their UI wraps the payment in Safe smart accounts + ERC-4337 + a Pimlico paymaster, hitting public BSC RPCs that already rate-limited us once ("RPC endpoint returned too many errors"). We have no control to fix that.

The core RN protocol is sound. The hosted UI on top of it is the problem.

2026-05-28 reality update

The first dev BSC probe did not fail because RN stayed silent. It failed because Amanat dropped the provider callback:

• Test transaction: 0x3a23febd9abd43d7e0851c1ea86c4ceaf08c11098852cb0425fa074e9c88350b.
• On-chain result: successful BSC USDC transfer to Amanat's configured destination wallet.
• RN webhook result: RN called POST /api/payment/request-network/webhook on dev.amn.gg four times from 34.34.233.192.
• Backend result: nginx/backend returned 404 because the handler did not correlate all Request Network identifiers stored on the Payment record.
• Frontend result: the callback page stayed on the processing state and later hit 429 from 3-second polling.

The pre-implementation gate therefore changes from "prove RN calls us" to "deploy and smoke-test the webhook correlation repair, callback polling repair, and transaction-safety gate before another paid probe".

2. Goal

Replace the redirect to RN's hosted page with an Amanat-rendered checkout that:

• Connects any EVM wallet (Rabby, MetaMask, OKX, Trust, WalletConnect — anything wagmi's injected() connector enumerates).
• Builds and submits the exact same on-chain calls RN's hosted page makes, so RN's existing webhook fires unchanged.
• Stays on dev.amn.gg (or prod equivalent) for the entire flow.
• Falls back gracefully to the hosted page for buyers who explicitly request it.

Settlement, webhook handling, and the backend Payment lifecycle do not change. Only the buyer-facing checkout surface changes.

Webhook delivery alone is not a sufficient trust signal. Amanat must run a Transaction Safety Provider gate before marking escrow funded. The initial provider checks: transaction hash present, configured confirmation depth, transfer recipient/token/amount match on-chain evidence, and future AML/sanctions provider approval.

3. Non-goals

• Per-seller multi-chain configuration (covered in Request Network Integration Constraints.md §2 — separate PRD).
• Per-(buyer, merchant) ephemeral wallets / wallet abstraction layer (§3 — separate PRD).
• Replacing RN entirely with our own chain watcher (§4 — depends on this PRD's outcome).
• Gasless / sponsored transactions for the buyer. Buyer pays own gas via their EOA. We can revisit paymaster integration in a follow-up.

4. Background: what RN's protocol actually requires

Cold-inspected from a real $12 BSC payment on RN's hosted page:

Item	Value
Proxy contract (BSC, and same address on most EVMs via deterministic CREATE2)	0x0DfbEe143b42B41eFC5A6F87bFD1fFC78c2f0aC9
Function	transferFromWithReferenceAndFee(address token, address to, uint256 amount, bytes reference, uint256 feeAmount, address feeAddress)
Selector	0xc219a14d
Emitted event	TransferWithReferenceAndFee(token, to, amount, reference, feeAmount, feeAddress)
paymentReference derivation	last8Bytes(keccak256(lowercase(requestId + salt + destinationAddress)))
Fee config seen on RN's UI	feeAmount = 0, feeAddress = 0x…dEaD

RN's webhook listens for TransferWithReferenceAndFee. If we emit it ourselves with the correct paymentReference, the webhook fires. The hosted UI is a UI-only convenience — not a settlement requirement.

5. Proposed flow (buyer perspective)

1. Buyer clicks "Pay with Request Network" on the request page.
2. Frontend calls existing POST /payment/request-network/intents (unchanged endpoint, expanded response — see §6).
3. Frontend navigates to new in-house page: /checkout/request-network/:paymentId.
4. Page shows: amount, token, chain, recipient (truncated, copyable), countdown timer.
5. "Connect wallet" — wagmi injected() + metaMask() (already configured). Rabby works automatically via EIP-6963.
6. Once connected, page checks the buyer's wallet is on the correct chain. If not, prompts switchChain (wagmi).
7. Page also checks current allowance. If allowance(buyer, RN_PROXY) >= amount, skip approve.
8. Buyer signs transaction 1: USDC.approve(RN_PROXY, amount). UI shows "Approving…" → "Approved".
9. Buyer signs transaction 2: RN_PROXY.transferFromWithReferenceAndFee(token, dest, amount, ref, 0, 0x…dEaD). UI shows "Submitting payment…" → "Confirmed on-chain".
10. Page waits for backend payment-confirmed socket event (already emitted on RN webhook → Payment.status='paid'). Shows success state.
11. Redirect to existing payment-success route.

Escape hatches surfaced as secondary links on the page:

• "Continue on Request Network's hosted page" → falls through to securePaymentUrl (unchanged behavior).
• "Copy payment details" → exposes destination, amount, token, chain, paymentReference for manual entry into any wallet.

6. Backend changes

6.1 Intent response payload

Expand PayInIntentResult for RN. Today it returns paymentUrl, paymentId, providerPaymentId, amount, config.networks, config.allowedTokens, raw. Add:

inHouseCheckout: {
  destination: '0x05E280d7f3cA954f37afA8B1E4d2a51D167c573e',
  tokenAddress: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
  tokenSymbol: 'USDC',
  decimals: 18,                  // BSC USDC quirk; varies per token+chain
  chainId: 56,
  proxyAddress: '0x0DfbEe143b42B41eFC5A6F87bFD1fFC78c2f0aC9',
  paymentReference: '0xa826e248f5de5463',  // 8-byte hex, computed from RN's requestId + salt
  feeAmount: '0',
  feeAddress: '0x000000000000000000000000000000000000dEaD',
  amountWei: '12000000000000000000',  // pre-multiplied by decimals, frontend doesn't compute
}

6.2 Sources for each field

Field	Source
destination, tokenAddress, chainId	Parse REQUEST_NETWORK_MERCHANT_REFERENCE env (address@eip155:chainId#ref:tokenAddr). Today done once at startup; extract into a helper.
decimals	Token registry lookup. Hardcode the few we care about (USDC/USDT × BSC/ETH/Arb/Polygon) in a constant map; fall back to on-chain decimals() if missing.
proxyAddress	Constant per chain. Use canonical 0x0DfbEe14…0aC9 for all EVMs unless RN deploys a non-canonical address (open question — see §10).
paymentReference	Computed from RN's /v2/secure-payments response. salt is in their raw payload. Use keccak256 + slice-to-8-bytes.
feeAmount, feeAddress	Constants matching what RN's hosted UI submits. Verify via cold inspection on each new chain we enable.
amountWei	BigInt(amount) * 10n ** BigInt(decimals). Done backend-side to avoid frontend rounding bugs.

6.3 Files touched

• backend/src/services/payment/requestNetwork/contract.ts — extend PayInIntentResult (or a new inHouseCheckout sub-object).
• backend/src/services/payment/requestNetwork/requestNetworkPayInService.ts — populate the new fields.
• backend/src/services/payment/requestNetwork/merchantReference.ts (new) — parser for the address@chain#ref:token format. Currently this is implicit in env lookups; promote to a named helper.
• backend/src/services/payment/requestNetwork/tokens.ts (new) — { chainId, tokenAddr } → { symbol, decimals } lookup.
• backend/src/services/payment/requestNetwork/paymentReference.ts (new) — computePaymentReference(requestId, salt, destination).
• Unit tests for each new helper.

6.4 Webhook handler

The route remains /api/payment/request-network/webhook, but the handler must be hardened before more paid probes:

• Correlate against every RN identifier we persist: providerPaymentId, metadata.requestNetworkRequestId, metadata.requestNetworkPaymentReference, and nested metadata.requestNetworkData ids/references.
• Reject unsigned or test-header callbacks unless explicit test mode is enabled.
• Store raw webhook evidence on the Payment record for support/replay.
• Call the Transaction Safety Provider before marking Payment.status='completed' / escrowState='funded'.
• Return a successful pending response when safety is not yet satisfied, so the delivery is not lost but escrow is not credited.

7. Frontend changes

7.1 New page

frontend/src/pages/checkout/request-network/[paymentId].tsx (or whatever the router convention is).

State machine (one component, reducer or zustand):

idle
  → connecting (wallet not connected)
  → wrong-chain (connected, chain mismatch)
  → ready (correct chain, allowance unknown)
  → checking-allowance
  → needs-approve     → approving → approve-confirming → ready-to-pay
  → ready-to-pay
  → paying → pay-confirming → confirmed
  → error (with retry)
  → expired (timer ran out)

7.2 Reusable parts from SHKeeper

frontend/src/web3/components/manual-payment.tsx already implements: address-with-QR, copy-to-clipboard, countdown timer, localStorage persistence per request, socket-driven status update. Reuse the layout chrome. The wallet-interaction half is new.

7.3 Wagmi calls

Two contracts. The ERC-20 ABI is already in viem/wagmi. RN proxy ABI is a single function — define it inline.

const RN_PROXY_ABI = [{
  inputs: [
    { name: 'tokenAddress', type: 'address' },
    { name: 'to',           type: 'address' },
    { name: 'amount',       type: 'uint256' },
    { name: 'paymentReference', type: 'bytes' },
    { name: 'feeAmount',    type: 'uint256' },
    { name: 'feeAddress',   type: 'address' },
  ],
  name: 'transferFromWithReferenceAndFee',
  outputs: [], stateMutability: 'nonpayable', type: 'function',
}] as const;

Hooks used:

• useAccount, useChainId, useSwitchChain
• useReadContract for allowance
• useWriteContract + useWaitForTransactionReceipt for approve and proxy call

7.4 Routing change

Today, createRequestNetworkIntent consumers do window.location = response.paymentUrl. Replace with router.push('/checkout/request-network/' + response.paymentId). Keep response.paymentUrl available so the in-house page can render the escape-hatch link.

7.5 Files touched

• frontend/src/pages/checkout/request-network/[paymentId].tsx — new page.
• frontend/src/web3/components/rn-in-house-checkout.tsx — new component holding the state machine.
• frontend/src/web3/contracts/rn-fee-proxy.ts — ABI + address-per-chain constants.
• frontend/src/sections/request/components/buyer-steps/… — change the existing RN button handler from window.location to router.push.
• Tests/Storybook for the new component.

8. Acceptance criteria

1. A buyer using Rabby can complete an RN payment end-to-end on dev.amn.gg without leaving the domain.
2. The two on-chain transactions emit a TransferWithReferenceAndFee event with the same paymentReference RN's hosted page would have produced.
3. RN's existing webhook fires on the event and the Payment doc transitions to completed / escrowState='funded' after safety approval.
4. If buyer connects on the wrong chain, they see a one-click "Switch network" CTA.
5. If buyer already has sufficient allowance, the approve step is skipped.
6. If the buyer abandons the page, returning to it restores their state from localStorage and resumes from the correct step.
7. "Continue on Request Network's hosted page" link is visible on the in-house page and works exactly like today's redirect.
8. Page handles tx failure (user reject, insufficient gas, RPC error) with a clear retry path that does not corrupt the Payment doc.
9. Existing non-RN payment flows (SHKeeper, others) are untouched.

9. Out of scope (explicit non-decisions)

• Multi-chain at checkout (BSC + Arb + ETH together) — needs the per-seller acceptedChains config; separate PRD.
• WalletConnect integration — currently disabled in web3/config.ts for SSR reasons; not regressed but not added either.
• Migration plan to remove RN entirely — kept as §4 open option in the architecture doc.
• Mobile Mini App rendering of the checkout (different surface — handled in Task 5.4).

10. Open questions for review

These are the items we should discuss with the second developer before starting implementation.

1. Proxy address universality. Is 0x0DfbEe143b42B41eFC5A6F87bFD1fFC78c2f0aC9 the RN ERC20FeeProxy address on every chain we plan to support (BSC, Arb, ETH mainnet, Polygon, Base)? We confirmed BSC + Arbitrum from RN's payments-subgraph repo. The other chains need explicit confirmation — preferably an on-chain probe per chain.
2. API pricing for hosted-UI vs API-only. RN's pricing model may assume hosted-UI usage. If we use them as a notification primitive only, are we still in their pricing terms? Worth a direct question to RN account management.
3. Approval UX. RN's hosted UI uses approve(spender, MAX_UINT256) for gas efficiency. Some Amanat users have voiced concern in past audits about unbounded approvals. Options:
   • Mirror RN: MAX_UINT256 (best UX, repeat payments don't need re-approve).
   • Exact-amount: approve(spender, amount). Slightly worse UX (every payment requires an approve), better security posture.
   • Recommend: exact-amount by default, opt-in "remember this approval" for power users. Discuss.
4. Tokens with non-standard ERC-20 behavior. USDT on Ethereum mainnet famously requires approve(0) before changing a non-zero allowance. We need to handle this if we add USDT-ETH later. Not relevant on day one (BSC config is USDC), but worth flagging now.
5. Cancel and timeout semantics. Today the Payment doc transitions on the webhook. If the buyer signs the approve but bails on the proxy call, the doc sits in pending forever. Options:
   • 30-minute TTL on the pending doc (existing partial unique index would let a re-attempt succeed).
   • "Cancel intent" button on the in-house page that calls a new backend endpoint to mark the doc cancelled.
   • Both. Discuss.
6. Manual reconciliation. If a buyer pays the correct amount to the correct destination but bypasses the proxy (e.g., raw transfer), no event fires and no webhook arrives. They'll think they paid but our system won't know. Today RN's hosted UI prevents this; our in-house UI inherits the same risk only if we add a "raw transfer" escape hatch — which we won't. But: should we proactively detect orphan transfers (chain watcher) and surface them in support? Out of scope for v1.
7. Feature flag and rollout. Ship behind a flag and A/B against the current redirect for one week of dev usage? Or hard-cut once acceptance criteria pass? Recommend A/B for at least one full release cycle.
8. Telemetry. What events do we instrument so we can prove the in-house page outperforms the redirect on conversion? Suggested: rn_checkout_opened, rn_wallet_connected, rn_approve_signed, rn_pay_signed, rn_pay_confirmed, rn_pay_failed{reason}, rn_escape_to_hosted_clicked.

11. Risks

• Webhook handling failure. RN delivered the 2026-05-28 dev webhook, but Amanat returned 404. A deployed correlation fix and smoke test are now the load-bearing gate before another paid probe.
• Webhook durability. The main app is too unstable to be the only callback landing zone. Put a Cloudflare Worker in front of Request Network webhooks to durably store raw delivery evidence, forward to the backend, and replay after outages.
• False-positive payment credit. A signed provider event must not be enough to fund escrow. Transaction Safety Provider gates completion on on-chain evidence, confirmation depth, transfer matching, and future AML/sanctions checks.
• Chain-specific divergences. RN may have deployed non-canonical proxy contracts on some chains. We mitigate by hard-coding per-chain proxy addresses and treating "unknown chain → fall back to hosted page" as the safe default.
• Wallet support drift. EIP-6963 is mature but not universal. We rely on wagmi's injected() connector enumeration; if a wallet doesn't implement EIP-6963, it falls into the generic window.ethereum slot. Acceptable.
• Buyer signs approve, then we change ABI before they sign the proxy call. Not really a risk if both txs are in the same session, but worth a smoke test on a long-lived session.

12. Implementation phases

Roughly two weeks of checkout work, now gated on confirmation reliability repair.

Phase	Work	Gate
0 — Probe	Fire one real dev BSC payment and inspect nginx/backend logs	Completed: RN webhook reached nginx/backend; app returned 404
0A — Confirmation repair	Deploy correlation fix, callback polling fix, signed-webhook smoke test, and Transaction Safety Provider	Unsigned/test callbacks rejected unless explicitly enabled; real webhook can find the Payment
1 — Backend	Expand intent response with inHouseCheckout fields; add helpers and tests	Existing RN smoke test still passes; new unit tests pass
2 — Frontend skeleton	New page + state machine + wallet-connect; no on-chain calls yet, mocked confirmations	Local clickthrough on dev.amn.gg with Rabby connected
3 — On-chain wiring	Real approve + transferFromWithReferenceAndFee calls; allowance check; chain-switch	One real end-to-end payment on dev BSC, webhook fires, Payment.status='completed', safety approved
4 — Hardening	Error handling, timer, persistence, telemetry, escape-hatch link	Acceptance criteria 1–9 demonstrably pass
5 — Durable ingress	Cloudflare Worker receives RN webhooks, stores delivery records, forwards to backend, supports replay	Backend outage no longer loses webhook evidence
6 — Rollout	Behind feature flag, A/B in dev for one cycle, then prod	Conversion telemetry; no regressions in non-RN flows

13. Durable webhook ingress roadmap

Add a Cloudflare Worker as the public Request Network webhook target:

1. Receive the raw RN webhook body, headers, request id, delivery id, source IP, and timestamp.
2. Verify the RN signature at the edge if raw-body secret handling is straightforward; otherwise store first and let the backend perform canonical verification.
3. Write an immutable delivery record to durable storage. Candidate stack: Cloudflare Queues for handoff plus D1/R2/KV for indexed replay metadata and raw payload retention.
4. Forward to the primary backend and optionally a secondary endpoint.
5. Return 2xx only after durable enqueue/store succeeds.
6. Provide operator replay by delivery id, payment reference, request id, or time window.

The Worker is only ingress/evidence buffering. The backend remains the trust boundary for signature verification, idempotency, Transaction Safety Provider checks, ledger updates, and marketplace state transitions.

14. References

• Cold-inspected transaction (real $12 BSC payment on RN hosted page): in conversation history, dated 2026-05-27.
• RN ERC20FeeProxy spec: https://github.com/RequestNetwork/requestNetwork/blob/master/packages/advanced-logic/specs/payment-network-erc20-fee-proxy-contract-0.1.0.md
• Arbitrum proxy deployment: https://github.com/RequestNetwork/payments-subgraph/blob/main/subgraph.arbitrum-one.yaml
• Architecture constraints doc: 01 - Architecture/Request Network Integration Constraints.md
• Previous RN work: PRD - Request Network Migration and Funds Management.md