Partner Payments API

API endpoints for the Partner Payments module. All endpoints require JWT authentication (token_admin) and are prefixed with /partner-payments.

Authentication

All endpoints require a valid admin JWT:

Authorization: Bearer <token>

Access is restricted by permission (see Auth column per endpoint).

Endpoints Summary

Method	Path	Description	Auth
GET	/partner-payments	List partner payments with filters and pagination	view-partner-payments
GET	/partner-payments/{payment}/details	Get payment detail rows (e.g. by shipment)	view-partner-payments
PUT	/partner-payments/{id}/pay	Execute commission payment (EcartPay)	pay-partners-payments
PUT	/partner-payments/{id}/reject	Reject commission payment	pay-partners-payments
GET	/partner-payments/{paymentId}/documents	Get documents for a payment	view-partner-payments
PATCH	/partner-payments/{paymentId}/documents/{documentId}/approve	Approve a document	view-partner-payments
PATCH	/partner-payments/{paymentId}/documents/{documentId}/reject	Reject a document	pay-partners-payments
PATCH	/partner-payments/{id}/mark-as-paid	Mark payment as paid with date	partners-payments-mark-as-a-paid
PATCH	/partner-payments/{id}/send-to-internal-review	Send payment to internal review	pay-partners-payments

Payment Status Values

Valid payment_status values used in filters and responses:

• generated
• payment_requested
• documents_rejected
• approved_for_payment
• under_review
• payment_rejected
• paid
• manually-paid

GET /partner-payments

List partner payments with optional filters and pagination. Response shape is determined by the backend (typically paginated list with payment and partner fields).

Query Parameters

Param	Type	Required	Description
start	number	No	Pagination offset (default: 0)
length	number	No	Page size (default: 100)
sortBy	string	No	Sort field
sortType	string	No	asc or desc
report	boolean	No	If true, stream full dataset (start=0, length=1000)
partner_id	number	No	Filter by partner ID
startDate	string	No	Filter by period start
endDate	string	No	Filter by period end
id	number	No	Filter by payment ID
status	string	No	Filter by status
payment_status	string	No	One of the payment status values above
reference	string	No	Filter by reference
company_id	number	No	Filter by company ID
userId	number	No	Filter by user ID
name	string	No	Filter by user name (LIKE)

Response (200)

Structure is backend-defined; typically includes data (array of payment objects with partner/user/company fields), pagination/draw fields, and optional streaming when report=true.

Errors

Code	Description
400	Validation failed (query params)
401	Missing or invalid JWT
403	Insufficient permissions

---

GET /partner-payments/{payment}/details

Returns detail rows for a given payment (e.g. shipment-level breakdown).

Path Parameters

Param	Type	Description
payment	number	Payment ID

Query Parameters

Param	Type	Required	Description
start	number	No	Pagination offset
length	number	No	Page size
sortBy	string	No	Sort field
sortType	string	No	Sort direction
report	boolean	No	If true, stream full dataset
partner_id	number	No	Filter by partner ID
carrier	string	No	Filter by carrier (LIKE)
id	number	No	Filter by detail ID

Response (200)

Backend-defined; typically an array of detail records (e.g. shipments, amounts) for the payment.

---

PUT /partner-payments/{id}/pay

Executes the commission payment flow (EcartPay) for a payment in approved_for_payment status. Required documents must be approved.

Path Parameters

Param	Type	Description
id	number	Payment ID

Request Body

{}

Or with optional field:

{
    "comments": "Optional (reserved / future use)"
}

Field	Type	Required	Description
comments	string	No	Optional string

Response (200)

{ "success": true } on success.

Errors

Code	Description
400	Invalid payload or state
401	Missing or invalid JWT
403	Insufficient permissions
404	Payment not found

---

PUT /partner-payments/{id}/reject

Rejects the commission payment after approved_for_payment. Sets payment_status to documents_rejected, clears approved_for_payment_at, stores comments, and resets all partner_payment_documents rows for that payment that were approved or rejected back to pending (clears rejection_reason, reviewed_by, reviewed_at) so the document validation flow can run again. Same eligibility rules as pay (approved_for_payment, partner account, cutoff date).

Path Parameters

Param	Type	Description
id	number	Payment ID

Request Body

{
    "comments": "Optional rejection comments"
}

Field	Type	Required	Description
comments	string	No	Shown to the partner

Response (200)

{ "success": true } on success. A Slack message is sent to SLACK_ALERT_CHANNEL (same block layout as “approved for payment”, plus rejection reason); mentions use SLACK_PARTNER_PAYMENT_MENTIONS.commissionPaymentRejected per environment (backend/constants/partnerPayments.js).

Errors

Code	Description
400	Invalid payload or state
401	Missing or invalid JWT
403	Insufficient permissions
404	Payment not found

---

GET /partner-payments/{paymentId}/documents

Get the list of documents associated with a partner payment.

Path Parameters

Param	Type	Description
paymentId	number	Payment ID (integer)

Response (200)

Backend-defined list of document records (e.g. id, type, status, file reference).

---

PATCH /partner-payments/{paymentId}/documents/{documentId}/approve

Approve a document for the given payment.

Allowed only when the payment’s payment_status is one of: payment_requested, documents_rejected, under_review, payment_rejected.

Path Parameters

Param	Type	Description
paymentId	number	Payment ID (integer)
documentId	number	Document ID (integer)

Response (200)

Backend-defined success payload. Slack notification may be sent when the payment reaches an approved state.

---

PATCH /partner-payments/{paymentId}/documents/{documentId}/reject

Reject a document. Requires a rejection reason. Same allowed payment_status values as document approve (including payment_rejected).

Path Parameters

Param	Type	Description
paymentId	number	Payment ID (integer)
documentId	number	Document ID (integer)

Request Body

{
    "rejection_reason": "Required reason text"
}

Field	Type	Required	Description
rejection_reason	string	Yes	Reason for rejection

Response (200)

Backend-defined success payload. An email is sent to the partner user (default template) with the document type name and rejection_reason. Translation keys: partners.mail.documentRejected.* (see documentation/translations/partner-mail-document-rejected-keys.md).

Errors

Code	Description
400	Missing or invalid rejection_reason
401	Missing or invalid JWT
403	Insufficient permissions
404	Payment or document not found

---

PATCH /partner-payments/{id}/mark-as-paid

Mark a partner payment as paid and set the paid date. Used when payment was made outside the system.

Path Parameters

Param	Type	Description
id	number	Payment ID (integer)

Request Body

{
    "paid_at": "2026-03-15T12:00:00Z"
}

Field	Type	Required	Description
paid_at	string	Yes	ISO date/time when the payment was made

Response (200)

Backend-defined success payload. A Slack “commissions paid” notification may be sent.

Errors

Code	Description
400	Invalid or missing paid_at
401	Missing or invalid JWT
403	Insufficient permissions
404	Payment not found

---

PATCH /partner-payments/{id}/send-to-internal-review

Send a payment to internal review. Requires comments.

Path Parameters

Param	Type	Description
id	number	Payment ID (integer)

Request Body

{
    "comments": "Reason or notes for internal review"
}

Field	Type	Required	Description
comments	string	Yes	Comments for the internal review

Response (200)

Backend-defined success payload.

Errors

Code	Description
400	Missing or invalid comments
401	Missing or invalid JWT
403	Insufficient permissions
404	Payment not found

---

Common Error Responses

Errors follow the Boom format:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Descriptive error message"
}

Status	When
400	Validation failed (Joi) or business rule
401	Missing or invalid JWT
403	User lacks required permission
404	Payment or document not found