nick-doc/08 - Operations/Handoff - Request Network Confirmation Repair - 2026-05-28.md

---
title: Handoff - Request Network Confirmation Repair - 2026-05-28
tags: [handoff, operations, payments, request-network, webhook]
created: 2026-05-28
---

# Handoff - Request Network Confirmation Repair - 2026-05-28

## Scope

This handoff covers the Request Network dev payment probe where the buyer callback stayed stuck on "processing payment", plus the local confirmation repair work and the documentation/roadmap updates that followed.

Primary user-reported issue:

- A real BSC Request Network test payment completed on-chain, but Amanat never showed confirmation on `https://dev.amn.gg/payment/callback/?paymentId=6a17e08f1485c1de0ff3cd15`.

## Current Answer

Do **not** run another paid payment test against dev until the local `2.6.26` changes are deployed and the webhook smoke test passes against the deployed stack.

After deploy:

- The original webhook `404` correlation bug should be fixed.
- If Request Network includes a transaction hash and the safety checks pass, the payment should complete.
- If Request Network omits the transaction hash, the webhook should be captured but the payment will remain `transactionSafety.pending` instead of being falsely credited.

## Repositories Touched

Backend:

- `backend/src/services/payment/requestNetwork/requestNetworkRoutes.ts`
- `backend/src/services/payment/requestNetwork/signature.ts`
- `backend/src/services/payment/adapters/requestNetworkAdapter.ts`
- `backend/src/services/payment/reconciliation/requestNetworkReconciliationService.ts`
- `backend/src/services/payment/decentralizedPaymentService.ts`
- `backend/src/services/payment/safety/transactionSafetyProvider.ts`
- `backend/src/models/Payment.ts`
- `backend/scripts/smoke/rn-webhook.sh`
- Request Network webhook/reconciliation tests
- `backend/.env.example`
- `backend/package.json`, `backend/package-lock.json`

Frontend:

- `frontend/src/app/payment/callback/page.tsx`
- Frontend version/env files and Dockerfile

Deployment:

- `deployment/docker-compose.yml`

Docs / Taskmaster:

- `nick-doc/PRD - Request Network In-House Checkout.md`
- `nick-doc/.taskmaster/docs/prd-request-network-in-house-checkout.md`
- `nick-doc/01 - Architecture/Request Network Integration Constraints.md`
- `nick-doc/PRD - Request Network Migration and Funds Management.md`
- `nick-doc/07 - Development/Environment Variables.md`
- `nick-doc/02 - Data Models/Payment.md`
- `nick-doc/08 - Operations/Incident Response.md`
- `nick-doc/08 - Operations/Monitoring.md`
- `nick-doc/README.md`
- Taskmaster subtask `3.13` for durable RN webhook ingress and transaction safety
- Taskmaster subtask `6.1` for deploying confirmation repair before the next paid probe

## Evidence From Dev

Test transaction:

```text
0x3a23febd9abd43d7e0851c1ea86c4ceaf08c11098852cb0425fa074e9c88350b
```

Payment document:

```text
paymentId: 6a17e08f1485c1de0ff3cd15
providerPaymentId: rq-af2d092e18cb41bb39ce4b0c
metadata.requestNetworkRequestId: 011ae38f7b99ef135514b987c9629b520b08e7a740f60d92d682f2f06466993a3f
metadata.requestNetworkPaymentReference: rq-af2d092e18cb41bb39ce4b0c
status before repair: pending
```

Nginx/backend evidence:

```text
POST /api/payment/request-network/webhook -> 404
source IP: 34.34.233.192
observed deliveries: four retries on 2026-05-28
```

Conclusion:

- Request Network did call Amanat.
- The payment succeeded on-chain.
- Amanat failed local confirmation because the webhook handler looked up the wrong reference shape and returned `404`.
- The frontend then kept polling too aggressively and eventually hit `429`.

## Implemented Locally

### Backend confirmation repair

- Webhook lookup now searches all known Request Network correlation keys:
  - `providerPaymentId`
  - `metadata.requestNetworkRequestId`
  - `metadata.requestNetworkPaymentReference`
  - nested `metadata.requestNetworkData.requestId`
  - nested `metadata.requestNetworkData.paymentReference`
- Test webhook bypass is no longer enabled by default.
- New `REQUEST_NETWORK_ALLOW_TEST_WEBHOOKS` env flag controls explicit test-mode acceptance.
- Request Network adapter uses the same test-mode rule.

### Transaction Safety Provider

Added `TransactionSafetyProvider` as the gate between provider event and escrow credit.

Initial checks:

- transaction hash required by default,
- minimum confirmations required by default,
- transfer recipient/token/amount match required by default,
- AML provider placeholder defaults to `none`; non-`none` values block until implemented.

Webhook and reconciliation completion paths both run through the same safety gate.

### Frontend callback repair

- Callback page now unwraps the backend `{ data: { payment } }` shape.
- Socket events handle both `requestId` and `purchaseRequestId`.
- Polling backs off from 3 seconds to 10 seconds.
- Polling stops after terminal states.
- `429`, `401`, and `403` no longer trap the page in misleading behavior.
- Dashboard redirect paths were corrected.

### Deployment/env

New env vars added to backend/deployment docs:

```text
REQUEST_NETWORK_ALLOW_TEST_WEBHOOKS=false
TRANSACTION_SAFETY_ENABLED=true
TRANSACTION_SAFETY_REQUIRE_TX_HASH=true
TRANSACTION_SAFETY_REQUIRE_TRANSFER_MATCH=true
TRANSACTION_SAFETY_MIN_CONFIRMATIONS=12
TRANSACTION_SAFETY_AML_PROVIDER=none
```

Versions were bumped together:

```text
frontend: 2.6.26
backend: 2.6.26
```

## Verification Already Run

Backend:

```bash
npm test -- __tests__/request-network-webhook.test.ts __tests__/request-network-adapter.test.ts __tests__/payment-reconciliation.service.test.ts --runInBand
npm run typecheck
REQUEST_NETWORK_ALLOW_TEST_WEBHOOKS=true BASE_URL=https://dev.amn.gg ./scripts/smoke/rn-webhook.sh
git diff --check
```

Frontend:

```bash
npx eslint src/app/payment/callback/page.tsx
npx tsc --noEmit -p tsconfig.json
git diff --check
```

Deployment/docs:

```bash
git diff --check
```

Important note: the smoke test against `dev.amn.gg` used `REQUEST_NETWORK_ALLOW_TEST_WEBHOOKS=true` because the currently deployed dev stack is still old and unsafe. After deploy, rerun without that override and expect unsigned/test callbacks to be rejected.

## Deploy Gate

Before another paid payment:

1. Commit/push/deploy backend, frontend, and deployment changes.
2. Set the new env vars in Arcane/dev deployment.
3. Confirm backend and frontend report `2.6.26`.
4. Run the RN webhook smoke test against dev without test bypass.
5. Tail nginx and backend logs during the next probe.
6. Inspect `Payment.metadata.transactionSafety` if the callback still waits.

## Recommended Next Work

1. Deploy and verify the confirmation repair.
2. Repeat one small dev BSC payment.
3. If it lands in `transactionSafety.pending` due missing transaction hash, add Request Network status/search enrichment so safety can resolve the tx hash.
4. Build the Cloudflare Worker durable webhook ingress:
   - receive raw RN payload and headers,
   - durably store delivery evidence,
   - forward to backend,
   - replay by delivery id/time window/payment reference.
5. Pick the first AML/sanctions provider and wire it behind `TRANSACTION_SAFETY_AML_PROVIDER`.

## Operational Rule

For Request Network incidents:

- Real provider webhook returning `404`: stop paid testing; fix correlation/config.
- Webhook returning `202` with `transactionSafety.pending`: evidence was captured, but payment is not safe to credit yet.
- Webhook returning `200`/completed with safety approved: proceed to normal marketplace state checks.