nick-doc/.taskmaster/docs/prd-request-network-migration-and-funds-management.md

# PRD - Request Network Migration and Funds Management

Date: 2026-05-24
Status: Draft for architecture review
Owner: Platform / Payments
Codebase reviewed: `/Users/manwe/CascadeProjects/escrow`

## Executive Summary

Replacing SHKeeper with Request Network is not a provider swap. SHKeeper currently acts like a deposit-wallet and payout-task provider: the backend creates a payment intent, receives a generated wallet address, watches SHKeeper webhooks and BSC wallet balances, then optionally creates an outgoing payout task.

Request Network is request/payment-reference based. The platform creates a Request Network payment request or secure payment page, the payer pays through Request Network contracts or hosted flow, and reconciliation happens through Request Network payment events. Payouts are API-created payment requests/calldata that still require wallet execution. This means Amanat needs a first-class funds ledger and a release/refund orchestration layer, not just renamed `/payment/shkeeper/*` endpoints.

Primary recommendation: run a phased migration behind a provider adapter. Introduce Request Network for new pay-ins first using Secure Payment Pages, keep SHKeeper read-only for existing payments, then add funds ledger, release/refund gates, and Request Network payout flows.

## Source Findings

Current code:

- Backend mounts SHKeeper at `/api/payment/shkeeper` through `backend/src/services/payment/shkeeper/shkeeperRoutes.ts` and `shkeeperPayoutRoutes.ts`.
- Frontend calls SHKeeper through `frontend/src/actions/payment.ts`, `frontend/src/web3/components/shkeeper-payment.tsx`, `shkeeper-widget.tsx`, and `shkeeper-payout.tsx`.
- `Payment.provider` only allows `shkeeper` or `other`; SHKeeper-specific fields live directly under `Payment.metadata`.
- Pay-in completion is accepted from SHKeeper webhook, manual confirmation, or wallet monitor, all coordinated through `PaymentCoordinator`.
- Current payout paths mix SHKeeper payout tasks, simulated marketplace release, and direct admin wallet payout.
- There is no durable internal funds ledger that tracks available, held, releasable, disputed, released, refunded, and fee amounts per purchase request.

Request Network documentation checked:

- API v2 supports programmatic request creation, secure payment pages, payouts, webhooks, payment search, platform fees, and payee destinations: <https://docs.request.network/llms.txt>
- Secure Payment Pages are hosted payment URLs returned by `POST /v2/secure-payments`, returning `requestIds`, `token`, and `securePaymentUrl`: <https://beta.docs.request.network/api-features/secure-payment-pages>
- Secure Payment Pages validate official Request Network contracts before payer signing: <https://beta.docs.request.network/api-features/secure-payment-pages>
- Webhooks are scoped by Client ID and include `x-request-network-signature`, delivery ID, retry count, and optional test header: <https://requestnetwork.mintlify.app/api-reference/webhooks>
- Request Network webhooks retry failed deliveries up to 3 retries with short backoff windows: <https://requestnetwork.mintlify.app/api-reference/webhooks>
- Payout endpoints return unsigned transaction data that the platform/wallet must execute: <https://docs.request.network/request-network-api/recurring-payments>
- Batch payouts can return approval and batch payment transactions; the application sends those wallet transactions: <https://docs.request.network/request-network-api/batch-payments>
- Request Network protocol fee is 5 bps with stablecoin caps, and platform fees can be included through `feePercentage` and `feeAddress`: <https://docs.request.network/request-network-api/fees>
- Payment networks use payment references for detection, rather than unique deposit wallets per invoice: <https://docs.request.network/advanced/protocol-overview/how-payment-networks-work>

## Target Architecture

### Payment Provider Adapter

Create a provider-neutral payment interface:

- `createPayInIntent`
- `getPayInStatus`
- `handleProviderWebhook`
- `createHostedPaymentLink`
- `createReleaseInstruction`
- `createRefundInstruction`
- `getPayoutStatus`
- `searchProviderPayments`

Implement:

- `ShkeeperProvider` for legacy compatibility.
- `RequestNetworkProvider` for new flows.

### Funds Ledger

Add an internal ledger separate from provider metadata:

- `fundsAccount`: one per purchase request or order.
- `ledgerEntry`: immutable entries for authorization, payment detected, platform fee, provider fee, hold, release, refund, chargeback/dispute hold, adjustment.
- `fundsBalance`: derived or cached view containing `expected`, `paid`, `held`, `releasable`, `released`, `refunded`, `disputed`, `fees`, and `available`.

Ledger invariants:

- Seller payout cannot exceed paid amount minus refunds, fees, and active dispute holds.
- Release requires payment status `completed`, escrow state `releasable`, no open dispute, and a verified seller destination.
- Refund requires available held balance and must mark the purchase request/payment state consistently.
- Provider webhooks never directly mark funds as released; they create/reconcile ledger entries.

### Payment Flow

Pay-in:

1. Buyer accepts seller offer.
2. Backend creates internal payment + funds account.
3. Backend calls Request Network `POST /v2/secure-payments` or `POST /v2/request`.
4. Frontend redirects to `securePaymentUrl` or executes returned calldata in wallet.
5. Request Network webhook confirms payment.
6. Backend verifies signature, idempotency, amount, request ID, payment reference, currency, and merchant reference.
7. Ledger moves from `expected` to `held`.
8. Purchase request enters `payment` or `processing`.

Release:

1. Buyer delivery confirmation or admin release marks funds `releasable`.
2. Backend creates Request Network payout/release instruction, or admin wallet transaction instruction.
3. Admin/operator wallet signs and broadcasts transaction.
4. Backend records transaction hash as `release_pending`.
5. Webhook/search confirms settlement.
6. Ledger moves `held -> released`.

Refund:

1. Refund request validates available held balance.
2. Backend creates refund transaction instruction.
3. Admin/operator wallet executes.
4. Confirmation updates ledger `held -> refunded`.

## PRD 1 - Provider-Neutral Payment Adapter

Priority: P0

Goal: decouple checkout, webhook, and payout flows from SHKeeper-specific routes and metadata.

Scope:

- Add `paymentProvider` abstraction in backend.
- Add `provider: 'shkeeper' | 'request_network' | 'manual' | 'admin_wallet'` to payment model.
- Keep `/api/payment/shkeeper/*` operational for legacy records.
- Add `/api/payment/providers/request-network/*` or `/api/payment/request-network/*` for new Request Network flows.
- Add a feature flag: `PAYMENT_PROVIDER=request_network|shkeeper`.

Acceptance Criteria:

- New checkout can create a Request Network payment link without touching SHKeeper service code.
- Existing SHKeeper payments remain readable and can still process late webhooks.
- Frontend does not import provider-specific action names outside provider-specific components.
- Provider metadata is namespaced under `metadata.providers.requestNetwork` or a dedicated provider table.

Risk Assessment:

- Impact: High. Payment creation is core revenue flow.
- Likelihood: Medium. Existing code has many direct `shkeeper` references.
- Main risks: broken checkout, duplicate payment records, orphaned webhooks, mixed provider states.
- Mitigation: use provider feature flag, preserve SHKeeper routes, add idempotency keys, run Request Network only for new payments during rollout.
- Rollback: set `PAYMENT_PROVIDER=shkeeper`; keep Request Network records read-only.

## PRD 2 - Request Network Pay-In Integration

Priority: P0

Goal: replace generated SHKeeper wallet addresses with Request Network request/payment-reference based payment collection.

Scope:

- Store Request Network `requestId`, `paymentReference`, `securePaymentUrl`, `token`, `merchantReference`, `network`, `invoiceCurrency`, and `paymentCurrency`.
- Use Secure Payment Pages for first launch to reduce frontend wallet/calldata complexity.
- Include Amanat purchase request ID and payment ID as merchant reference or metadata.
- Validate supported networks/currencies before creating payment links.
- Remove frontend dependence on SHKeeper-generated `walletAddress` for new provider flow.

Acceptance Criteria:

- Buyer can start payment and receive a Request Network hosted payment URL.
- Backend records internal payment as `pending` with Request Network identifiers.
- Webhook `payment.confirmed` reconciles only the matching internal payment.
- Amount, currency, provider request ID, and merchant reference are verified before setting `escrowState='funded'`.
- Late or duplicate webhook deliveries are idempotent.

Risk Assessment:

- Impact: High.
- Likelihood: Medium.
- Main risks: currency/network mismatch, hosted redirect UX breakage, buyer pays wrong amount, missing webhook.
- Mitigation: backend-only creation, strict metadata correlation, periodic fallback reconciliation using Request Network payment search, idempotency by delivery ID and request ID.
- Rollback: disable Request Network provider for new payments; keep pending Request Network payments visible with manual support workflow.

## PRD 3 - Funds Ledger and Escrow State Machine

Priority: P0

Goal: introduce internal funds management so payment, hold, release, refund, dispute, and fee states are auditable and provider-independent.

Scope:

- Add `FundsAccount` model keyed by purchase request/payment.
- Add immutable `LedgerEntry` model with provider references and actor/source.
- Add derived `FundsBalance` query/service.
- Define state transitions: `expected -> held -> releasable -> releasing -> released`, plus `refunded`, `partially_refunded`, `disputed`, `failed`.
- Prevent release/refund from reading raw `Payment.status` alone.

Acceptance Criteria:

- Every successful pay-in creates a ledger entry for gross paid amount.
- Platform fee, Request Network protocol fee, and net seller amount are represented explicitly.
- Release API checks ledger invariants before creating payout/refund instructions.
- Dispute hold blocks payout until resolved.
- Admin UI/payment detail view can show gross paid, fees, held, releasable, released, refunded.

Risk Assessment:

- Impact: Very High.
- Likelihood: Medium.
- Main risks: double-release, incorrect fee accounting, drift between Payment and ledger state.
- Mitigation: immutable entries, unique idempotency keys, transaction/session writes where Mongo supports them, reconciliation job, read-only migration report before enforcing ledger.
- Rollback: keep old payment fields as source of truth until ledger backfill passes; feature flag release enforcement.

## PRD 4 - Request Network Webhook and Reconciliation Service

Priority: P1

Goal: replace SHKeeper webhook and wallet monitor semantics with signed Request Network event processing and periodic reconciliation.

Scope:

- Add `/api/payment/request-network/webhook`.
- Verify raw body using `x-request-network-signature`.
- Store delivery ID, retry count, event type, request ID, payment reference, payload hash, and processed status.
- Support test webhooks via `x-request-network-test`.
- Add scheduled reconciliation using Request Network payment search/status APIs.
- Retire SHKeeper wallet monitor for new Request Network payments.

Acceptance Criteria:

- Invalid signatures are rejected in all environments except explicit local test mode.
- Duplicate delivery IDs are acknowledged without duplicating ledger entries.
- `payment.confirmed` and partial/over/failed states map to internal status consistently.
- Reconciliation job can repair missed webhook state without relying on buyer/frontend callbacks.

Risk Assessment:

- Impact: High.
- Likelihood: Medium.
- Main risks: raw body parsing mismatch, webhook downtime, event mapping mistakes.
- Mitigation: raw-body middleware scoped to webhook route, event fixture tests, dead-letter queue/table, operator replay endpoint.
- Rollback: pause webhook processor and rely on manual/admin reconciliation for Request Network records.

## PRD 5 - Release, Refund, and Payout Orchestration

Priority: P1

Goal: replace SHKeeper payout tasks and simulated marketplace release with auditable transaction instruction and confirmation flows.

Scope:

- Define release/refund service that consumes ledger balances, not raw request status.
- Generate Request Network payout instructions or direct admin wallet transaction instructions.
- Store unsigned transaction payloads, signer, submitted tx hash, confirmation status, and provider status.
- Add batch payout support as a later optimization after single release is stable.
- Require admin/operator authorization and dispute checks before instruction creation.

Acceptance Criteria:

- Seller payout requires verified seller wallet/payee destination.
- Release cannot occur if funds are unpaid, already released, refunded, or disputed.
- Transaction hash confirmation updates ledger only once.
- Admin can see pending release instructions and retry/cancel safely.
- Existing `/purchase-requests/:id/release-payment` simulated path is removed or hidden behind dev-only mode.

Risk Assessment:

- Impact: Very High.
- Likelihood: High.
- Main risks: Request Network payouts are not custodial magic; operator wallet still signs transactions, so process failure can leave funds pending.
- Mitigation: explicit release queue, two-step admin approval, signer audit trail, reconciliation against tx hash/provider status.
- Rollback: keep direct admin wallet payout as emergency fallback with mandatory ledger entry and reason code.

## PRD 6 - Frontend Checkout and Admin Migration

Priority: P1

Goal: update buyer payment, admin release, seller payout, and payment details UI for Request Network flows.

Scope:

- Replace `ShkeeperPayment` with provider-neutral `CryptoPayment`.
- Add `RequestNetworkPayment` redirect flow for secure payment pages.
- Keep `ShkeeperPayment` available only for legacy/unpaid SHKeeper records if needed.
- Replace `ShkeeperPayout` with release queue/admin payout UI.
- Payment detail page shows provider, request ID, payment reference, hosted link, transaction hashes, ledger balances, webhook/reconciliation status.

Acceptance Criteria:

- Buyer checkout no longer expects provider-generated `walletAddress` for Request Network payments.
- Admin release UI displays available/releasable funds and blocks unsafe release states.
- Seller payout status comes from internal release instruction/ledger, not SHKeeper task polling.
- Legacy SHKeeper labels are not shown for Request Network payments.

Risk Assessment:

- Impact: Medium-High.
- Likelihood: Medium.
- Main risks: confusing redirect UX, old Persian labels referencing SHKeeper, admin accidentally using old payout button.
- Mitigation: provider-specific copy, feature flag UI sections, legacy badge, clear payment detail diagnostics.
- Rollback: route checkout back to SHKeeper component via provider flag.

## PRD 7 - Data Migration and Legacy Decommission

Priority: P2

Goal: safely migrate historical SHKeeper payment records and phase out provider-specific code.

Scope:

- Backfill provider metadata namespace for existing SHKeeper payments.
- Create ledger entries for completed SHKeeper payments from trusted records.
- Mark historical records as `legacyProvider='shkeeper'`.
- Keep SHKeeper webhook active during webhook tail period.
- Remove SHKeeper wallet monitor, simple auto webhook, test callback routes, and payout routes after cutoff.

Acceptance Criteria:

- Migration produces counts for total, migrated, skipped, ambiguous, and failed records.
- No historical completed payment loses transaction hash/provider invoice/task metadata.
- Legacy SHKeeper webhook can still reconcile existing pending records until cutoff date.
- Decommission checklist includes env vars, docs, frontend labels, backend routes, and runbooks.

Risk Assessment:

- Impact: Medium.
- Likelihood: Medium.
- Main risks: ambiguous historical records, template checkout string IDs, mixed status meanings.
- Mitigation: dry-run migration, manual review bucket, no destructive migration, keep original metadata.
- Rollback: ledger backfill is additive; old records remain intact.

## Implementation Sequence

1. Add provider adapter and Request Network config without changing default provider.
2. Add funds ledger models/services and dry-run backfill report.
3. Implement Request Network secure pay-in flow behind feature flag.
4. Implement signed webhook receiver and reconciliation job.
5. Enable Request Network for limited new checkout cohort.
6. Add release/refund orchestration using ledger gates.
7. Migrate admin/frontend views.
8. Backfill legacy records.
9. Decommission SHKeeper once no active records depend on it.

## Open Decisions

- Use Request Network Secure Payment Pages first, or execute Request Network calldata directly in the existing wallet modal?
- Keep funds in a platform-controlled escrow wallet, pay sellers via admin/operator release, or route pay-ins directly to seller with only platform fee collection?
- Which chains/currencies are required for launch: BSC USDT parity with today, or Request Network supported stablecoin routes first?
- Should platform fee be paid by buyer, seller, or absorbed by Amanat?
- Does Amanat need crypto-to-fiat/offramp later, which adds KYC/payment detail requirements?

## Recommendation

Start with Secure Payment Pages and a platform escrow/payee destination controlled by Amanat. This best matches the current escrow mental model while reducing frontend transaction-building risk. Do not route pay-ins directly to sellers until dispute handling, refund logic, and service fee economics are fully redesigned.