Partner Payments

Management of partner commission payments: listing, approval workflow, document validation, mark as paid, and internal review. Integrates with Slack for notifications when payments are approved or paid.

Overview

The Partner Payments module allows administrators to view partner payment records, validate supporting documents (approve/reject), advance payments through statuses (e.g. send to internal review, mark as paid), and trigger Slack notifications for approved and paid commissions. It supports filtering by partner, date range, payment status, and reference.

Key Concepts

Concept	Description
Partner payment	A payment record for a partner's commissions for a given period (month/year), with status and optional paid date
Payment status	Lifecycle state: generated, payment_requested, documents_rejected, approved_for_payment, under_review, payment_rejected, paid, manually-paid
Document validation	Workflow to approve or reject documents attached to a payment before it can be paid
Internal review	Status used when a payment is sent for internal review; requires comments
Mark as paid	Manual recording of payment date when the commission was paid outside the system

Data Flow

Main Flow: List and Filter Partner Payments

Flow: Document Validation (Approve / Reject)

Flow: Mark as Paid / Send to Internal Review

Backend Structure

Route File

backend/routes/
└── partnerPayments.routes.js   # All partner payment endpoints

Controller and Library

• Controller: backend/controllers/partnerPayments.controller.js — delegates to the partnerPayments util.
• Library: backend/libraries/partnerPayments.util.js — business logic for listing, details, pay, document approve/reject, mark as paid, send to internal review. Uses Slack util for notifications.

Permissions

Permission name	Use
view-partner-payments	List payments, view details, get documents, approve documents
pay-partners-payments	Reject documents, send to internal review
partners-payments-mark-as-a-paid	Mark payment as paid (with date)

Database

Tables (relevant to this module)

Table	Purpose
partner_payments	Payment headers: partner, period (month/year), status, payment_status, reference, paid_at, etc.
partner_payments_details	Line items per payment (e.g. shipment-level details)
partners	Partner entity (user_id, locale_id, etc.)
users	User data for partner
companies	Company linked to partner user

Key Fields (partner_payments)

Column	Description
payment_status	One of: generated, payment_requested, documents_rejected, approved_for_payment, under_review, payment_rejected, paid, manually-paid
paid_at	When the payment was marked as paid (nullable)
reference	Optional reference identifier
partner_id	FK to partners
month, year	Billing period

Key Decisions

Decision	Reasoning	Alternatives Considered
Centralized partnerPayments util	All payment and document logic in one place; controller stays thin and testable.	Logic in controller (harder to reuse and test)
Slack notifications on approve and paid	Keeps finance/ops informed without polling.	Email only (less real-time), no notification (manual tracking)
Separate permissions for view vs pay vs mark-as-paid	Fine-grained access: some roles can only view or approve documents; others can mark as paid.	Single permission (less secure)
Document approve/reject via PATCH with path params	RESTful and clear: payment and document IDs in path, optional body for reject reason.	Single “update document” endpoint with action in body (more ambiguous)

Dependencies

• Internal: Partners module (partner and user data), Auth (JWT, permissions), Slack util and templates for notifications.
• External: Slack API for approval and “commissions paid” messages.

Related Documentation

• API Endpoints — Endpoint reference for partner payments and documents
• UI Screens & Flows — Frontend screens and components
• User Guide — How to use partner payments in the app