Response body — /projects/peer-to-peer-payment-workflow-system
Peer-to-Peer Payment Workflow System
A backend system designed to facilitate secure peer-to-peer payments using a third-party payment gateway.
Response metadata
The problem
"Payment state machines that look simple in diagrams break the moment a webhook is late or a gateway returns ambiguously."
The hard part
The gateway confirmed but our webhook timed out — built a reconciliation job that closes the gap without double-charging, using idempotency keys keyed to user-intent rather than request-id.
Overview
This project involved designing and implementing a peer-to-peer payment workflow that enabled users to transfer money directly to one another through a third-party payment gateway.
The system was responsible for managing the full lifecycle of a payment—from initiation to completion—while ensuring security, correctness, and a clear separation between internal application state and external payment provider behavior.
Problem
Peer-to-peer payment systems introduce a unique set of challenges due to their dependency on external gateways and the financial sensitivity of transactions.
The primary problems to solve were:
- Safely integrating with a third-party payment provider
- Managing multiple payment states reliably
- Ensuring the system remained consistent despite external failures
- Providing clear visibility into payment outcomes for users
Constraints
- Payment processing depended on an external gateway with its own reliability characteristics
- Network failures and delayed callbacks were possible
- The system needed to avoid duplicate or inconsistent payment records
- Payment state transitions had to remain auditable and deterministic
Solution
The system was designed around a state-driven payment workflow, where each payment progressed through a well-defined lifecycle.
Key design decisions included:
- Maintaining an internal payment state machine independent of the payment gateway
- Treating the gateway as an external system of record only for transaction execution
- Using webhook callbacks to reconcile final payment outcomes
- Persisting all payment states and transitions for traceability
MongoDB was used to store payment documents, allowing flexible representation of payment states and gateway metadata.
Architecture
- Backend: Node.js with TypeScript
- Database: MongoDB
- Payment Gateway: Razorpay
- Cloud: AWS
Each payment followed a defined flow:
- Payment initiation by the sender
- Gateway order creation
- User authorization via the gateway
- Webhook-based confirmation
- Final state reconciliation and persistence
This architecture ensured the backend remained resilient to delayed or repeated gateway callbacks.
Trade-offs
- Relying on a third-party gateway introduced external failure modes
- Webhook-driven reconciliation increased system complexity
- MongoDB required careful schema discipline for financial records
These trade-offs were accepted to maintain flexibility and robustne