81625d35d2
- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT) - Add human-blocked section with 3 precise next steps for owner - Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria
5.9 KiB
title, tags
| title | tags | |||
|---|---|---|---|---|
| Dispute API |
|
Dispute API
[!note] Current implementation The Dispute module now has a Mongoose model, controller routes, dashboard routes, and release-hold helper routes mounted under
/api/disputes. Keep this page aligned with bothbackend/src/routes/disputeRoutes.tsandbackend/src/services/dispute/disputeRoutes.ts.
Endpoints live under /api/disputes/*. backend/src/routes/disputeRoutes.ts delegates to DisputeController (backend/src/controllers/disputeController.ts) for CRUD/triage. backend/src/services/dispute/disputeRoutes.ts provides lightweight release-hold endpoints (raise, resolve, status) used by escrow release gating. The routers apply authenticateToken globally — every endpoint requires Bearer JWT.
Model: Dispute. A dispute references a PurchaseRequest plus optional Payment context and is the input to the mediation workflow that can lead to refund, replacement, compensation, warning/ban, or no-action. Release/refund execution should go through the ledger-gated Payment API and Payout Flow.
Create
POST /api/disputes
Description: Open a dispute against a purchase request. Auth required: Bearer JWT (buyer or seller participant in the request) Request body:
{
purchaseRequestId: string;
reason: "not_delivered" | "wrong_item" | "damaged" | "quality" | "other";
description: string;
evidence?: string[]; // URLs from [[File API]]
paymentId?: string;
}
Response 201: { success: true, data: { dispute } }
Errors: 400 validation, 403 not a participant of the request, 409 dispute already open for this request.
Side effects:
- Notifies the counter-party via
POST /api/notifications(new-notificationsocket event). - Pauses any in-flight payout (sets a hold flag on the related Payment).
POST /api/disputes/:purchaseRequestId/raise
Description: Lightweight release-hold endpoint that marks a purchase request and related payments as disputed.
Auth required: Bearer JWT (buyer who owns the request or admin)
Request body: { reason?: string }
Response 200: { success, message, data }
GET /api/disputes/:purchaseRequestId/status
Description: Returns release-hold flags for a purchase request, including whether release is currently blocked. Auth required: Bearer JWT (buyer, preferred seller, or admin)
Read
GET /api/disputes
Description: List disputes the caller can see (their own as buyer/seller, all for admins). Auth required: Bearer JWT Query params:
status(open|under_review|resolved_buyer|resolved_seller|closed)purchaseRequestIdpage,limit,sortBy,sortOrderResponse 200:{ success, data: { disputes, pagination } }
GET /api/disputes/statistics
Description: Aggregated counts (open, by reason, average resolution time) for admin dashboards.
Auth required: Bearer JWT (admin)
Response 200: { success, data: { open, byReason, avgResolutionHours, ... } }
GET /api/disputes/:id
Description: Full dispute including evidence list, messages, assigned admin, decision (if any).
Auth required: Bearer JWT (participant or admin)
Errors: 403 not allowed, 404 not found.
Admin operations
POST /api/disputes/:id/assign
Description: Assign an admin moderator to the dispute. Sets assignedAdminId and transitions status to under_review.
Auth required: Bearer JWT (admin)
Request body: { adminId: string }
Side effects: Notifies all participants.
PATCH /api/disputes/:id/status
Description: Generic status update (e.g. close without resolution).
Auth required: Bearer JWT (admin)
Request body: { status: string; note?: string }
POST /api/disputes/:id/resolve
Description: Final adjudication. Records the decision and triggers the appropriate escrow action. Auth required: Bearer JWT (admin) Request body:
{
decision: "buyer" | "seller" | "split";
refundAmount?: number; // required when "split"
releaseAmount?: number; // required when "split"
reasoning: string;
}
Response 200: { success, data: { dispute, paymentAction } }
Side effects:
action === "refund"→ create/approve the corresponding refund instruction through the ledger-gated payment release/refund flow.action === "no_action"or seller-favorable outcome → clear hold only after release checks pass.- split outcomes require explicit partial release/refund instructions.
- Notifies both participants and updates PurchaseRequest status to
disputed_resolved.
POST /api/disputes/:purchaseRequestId/resolve
Description: Lightweight release-hold endpoint that clears the disputed hold flags on a purchase request and related payments.
Auth required: Bearer JWT (admin)
Response 200: { success, message, data }
Evidence and messages
POST /api/disputes/:id/evidence
Description: Attach additional evidence (image / document URLs from the File API) to the dispute. Either party can call. Auth required: Bearer JWT (participant or admin) Request body:
{
url: string;
description?: string;
type?: "image" | "document" | "video";
}
Response 200: { success, data: { dispute } } with the evidence appended.
Messages
Direct messages between disputants and the admin moderator are handled via a dedicated Chat created automatically when the dispute is opened (type: "dispute"). Use the Chat API endpoints (POST /api/chat/:id/messages, GET /api/chat/:id/messages) once you have the chatId from the dispute payload.
Real-time
Dispute mutations emit notifications via POST /api/notifications which delivers new-notification socket events to each participant's user-<userId> room. See Socket Events for payload shape.