Skip to main content
POST
Record Payment

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

invoice_id
string<uuid>
required

Body

application/json

Records a payment receipt against an invoice.

Endpoint: POST /api/v1/invoices/{invoice_id}/payments Required role: finance:confirm_payment

Multiple payments can be recorded against the same invoice to support installment/partial payment workflows.

amount_paid
required

Amount received in this payment. Must be greater than zero.

Required range: x > 0
payment_method
enum<string>
required

Channel used: RTGS, EFT, MPESA, CHEQUE, INTERNAL_LEDGER, or OTHER.

Available options:
RTGS,
EFT,
MPESA,
CHEQUE,
INTERNAL_LEDGER,
OTHER
payment_reference
string
required

Bank reference, M-PESA transaction ID, or cheque number for audit trail.

payment_date
string<date>
required

Date funds were received, e.g. '2026-05-31'.

document_id
string<uuid> | null

ID of the payment receipt uploaded to document-service (bank advice, M-PESA confirmation, cheque scan, etc.). Upload to document-service first, then pass the ID here.

notes
string | null

Optional internal notes for the finance team.

Response

Successful Response