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

title, tags, created

title	tags	created
Handoff - Request Network Confirmation Repair - 2026-05-28	handoff operations payments request-network webhook	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:

0x3a23febd9abd43d7e0851c1ea86c4ceaf08c11098852cb0425fa074e9c88350b

Payment document:

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

Nginx/backend evidence:

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:

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:

frontend: 2.6.26
backend: 2.6.26

Verification Already Run

Backend:

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:

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

Deployment/docs:

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.