Create Invoice Payment
POST /api/v1/invoices/{invoice_id}/payments
Record a payment against an invoice. This reduces the invoice balance accordingly.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
invoice_id |
integer | Yes | The unique ID of the invoice. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
payment[amount] |
decimal | Yes | Payment amount (must not exceed balance). |
payment[reference] |
string | No | Payment reference or transaction ID. |
payment[channel] |
string | No | Payment method (e.g., cash, card, bank_transfer). |
payment[paid_at] |
string (ISO 8601) | No | Payment date (default: now). |
Request Example
{ "payment": { "amount": "340", "reference": "Payment 343", "channel": "cash", "paid_at": "2025-10-13T00:00:00.000Z" } }
POST /api/v1/invoices/123/payments HTTP/1.1
Host: koteshen.com
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json
{request_body}
Response
Status Codes:
201 Created- Payment recorded.401 Unauthorized- Invalid or missing token.404 Not Found- Invoice not found.422 Unprocessable Entity- Amount exceeds balance or invalid data.
Success Response (201)
Same structure as List Invoice Payments individual item. The invoice’s balance is automatically updated.