Seller Withdrawal System
Relevant source files
The following files were used as context for generating this wiki page:
The Seller Withdrawal System is a core financial feature of the e-commerce platform, enabling sellers to request the transfer of their earned funds from their shop's available balance to their designated bank account. The system is designed with a two-part workflow: a request initiation by the seller and an approval process managed by the site administrator.
This system ensures a secure and traceable process for handling seller payouts. It involves dedicated frontend components for both sellers and administrators, a set of backend API endpoints for processing requests, and a specific data model to record every withdrawal transaction. The process includes email notifications to keep sellers informed about the status of their requests.
Architecture Overview
The system is comprised of frontend components built with React, a backend API powered by Node.js and Express, and a MongoDB database for persistence.
The overall flow is as follows:
- A seller adds their bank information as a withdrawal method.
- The seller initiates a withdrawal request from their dashboard.
- The system creates a withdrawal record, deducts the amount from the seller's available balance, and notifies the seller.
- An administrator reviews all pending withdrawal requests in the admin dashboard.
- The administrator approves the request, which updates the request's status and sends a final confirmation email to the seller.
This diagram illustrates the high-level lifecycle of a withdrawal request.
Data Model
The withdrawal process is centered around the Withdraw and Shop models.
Withdraw Schema
This model stores the details of each withdrawal request.
| Field | Type | Description | Default |
|---|---|---|---|
seller | mongoose.Schema.ObjectId | A reference to the Shop model of the seller making the request. | |
amount | Number | The amount of money to be withdrawn. | |
status | String | The current status of the request (e.g., "Processing"). | "Processing" |
createdAt | Date | Timestamp for when the request was created. | Date.now() |
updatedAt | Date | Timestamp for the last update. |
Sources: backend/model/withdraw.js:4-13
Shop Schema Integration
The Shop model is updated to support the withdrawal process with the following fields:
availableBalance: ANumberthat holds the seller's earnings. This is decremented when a withdrawal request is made.withdrawMethod: AnObjectstoring the seller's bank account details.transections: AnArraythat logs completed withdrawal transactions.
Sources: backend/controller/withdraw.js:43-45, backend/controller/withdraw.js:108-114, backend/controller/shop.js:283-294
Entity Relationship Diagram
The diagram below shows the relationship between the Shop and Withdraw entities.
Backend API
The backend exposes several endpoints under the /api/v2/withdraw and /api/v2/shop routes to handle withdrawal logic.
API Endpoints
| Method | Endpoint | Role Required | Description |
|---|---|---|---|
POST | /withdraw/create-withdraw-request | Seller | Creates a new withdrawal request. Deducts the amount from the seller's availableBalance and sends a processing email. |
GET | /withdraw/get-all-withdraw-request | Admin | Retrieves a list of all withdrawal requests, sorted by creation date. |
PUT | /withdraw/update-withdraw-request/:id | Admin | Updates the status of a specific withdrawal request to "succeed". Adds the transaction to the seller's history and sends a confirmation email. |
PUT | /shop/update-payment-methods | Seller | Adds or updates the seller's withdrawal bank information. |
DELETE | /shop/delete-withdraw-method | Seller | Deletes the seller's currently configured withdrawal method. |
Sources: backend/controller/withdraw.js:11-53, backend/controller/withdraw.js:57-71, backend/controller/withdraw.js:74-121, backend/controller/shop.js:283-294, backend/controller/shop.js:297-315
Frontend Components
The user interface for the withdrawal system is split between the seller's dashboard and the admin panel.
Seller: WithdrawMoney.jsx
This component allows sellers to manage their funds.
Features:
- Displays the seller's current
availableBalance. - Provides a "Withdraw Money" button, which is enabled only if the balance is sufficient (>= 50).
- A modal allows the seller to:
- Add a new withdrawal method (bank name, account number, holder name, etc.) if one is not already set. This calls the
PUT /shop/update-payment-methodsendpoint. - View and delete the existing withdrawal method. This calls the
DELETE /shop/delete-withdraw-methodendpoint. - Enter a withdrawal amount and submit the request.
- Add a new withdrawal method (bank name, account number, holder name, etc.) if one is not already set. This calls the
The withdrawHandler function validates the amount and sends a POST request to /withdraw/create-withdraw-request.
Sources: frontend/src/components/Shop/WithdrawMoney.jsx:106-115, frontend/src/components/Shop/WithdrawMoney.jsx:50-68, frontend/src/components/Shop/WithdrawMoney.jsx:70-78
Admin: AllWithdraw.jsx
This component is for administrators to manage and process withdrawal requests.
Features:
- Fetches all withdrawal requests via
GET /withdraw/get-all-withdraw-request. - Displays the requests in a
DataGridwith columns for ID, Store Name, Amount, Status, and Request Time. - An "Update" (pencil) icon is shown for requests with a "Processing" status.
- Clicking the update icon opens a modal to change the request's status.
- The admin can select "Successful" and submit, which triggers the
handleSubmitfunction. This function sends aPUTrequest to/withdraw/update-withdraw-request/:idto finalize the withdrawal.
Sources: frontend/src/components/Admin/AllWithdraw.jsx:21-29, frontend/src/components/Admin/AllWithdraw.jsx:70-75, frontend/src/components/Admin/AllWithdraw.jsx:77-90
Workflows
Withdrawal Request Sequence
This diagram shows the sequence of events when a seller requests a withdrawal.
Withdrawal Approval Sequence
This diagram shows the sequence of events when an admin approves a withdrawal.
Summary
The Seller Withdrawal System is a well-defined module that securely handles financial transactions between the platform and its sellers. It provides clear interfaces for both sellers to request their earnings and for administrators to manage these requests. The process is transparent, with status updates, email notifications, and a persistent record of all transactions, ensuring accountability and trust.