Docs / API reference

Payments

Invoa API payments endpoints: list payments and record money received against an invoice, which updates its balance and issues a receipt.

A payment is money received against an invoice. Recording one through the API confirms it straight away, updates the invoice to partially_paid or paid, and issues an official receipt.

Method	Path	Scope
`GET`	`/payments`	`documents:read`
`POST`	`/payments`	`payments:write`

Payments made online through CHIP, and "I have paid" claims you confirm in the app, are recorded by Invoa itself and appear in the same list. See Payments and receipts.

The payment object

json

{
  "id": "9a700000-0000-4000-8000-000000000018",
  "tenantId": "7e0a0000-0000-4000-8000-000000000001",
  "documentId": "d0c00000-0000-4000-8000-000000000042",
  "method": "bank_transfer",
  "amount": 135000,
  "receivedAt": "2026-10-20",
  "reference": "MBB 20OCT 884512",
  "status": "confirmed",
  "source": "manual",
  "note": null,
  "proofFileId": null,
  "receiptDocumentId": "d0c00000-0000-4000-8000-000000000043",
  "chipPurchaseId": null,
  "createdBy": null,
  "createdAt": "2026-10-20T06:31:12.000Z",
  "updatedAt": "2026-10-20T06:31:12.000Z"
}

Field	Type	Description
`id`	string	Payment ID (UUID).
`documentId`	string	The invoice this payment is for.
`method`	string	`chip`, `bank_transfer`, `cash`, `cheque` or `other`.
`amount`	integer	Amount received, in sen.
`receivedAt`	date	The date the money arrived.
`reference`	string or null	Bank or payment reference.
`status`	string	`pending`, `confirmed`, `failed` or `refunded`. Payments recorded through the API are `confirmed`.
`source`	string	How the payment reached Invoa: `manual`, `claim` (a confirmed customer claim) or `webhook` (CHIP).
`note`	string or null	Internal note.
`receiptDocumentId`	string or null	The receipt issued for this payment.
`chipPurchaseId`	string or null	Set for CHIP payments.

List payments

http

GET /api/v1/payments

Returns payments with the most recent receivedAt first. Each item adds documentNumber, contactName and receiptNumber.

Query parameter	Type	Description
`documentId`	string	Only payments for this invoice.
`from`, `to`	date	`receivedAt` range, inclusive.
`status`	string	`pending`, `confirmed`, `failed` or `refunded`.
`limit`, `offset`	integer	See Pagination.

bash

curl "https://app.invoa.io/api/v1/payments?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $INVOA_API_KEY"

json

{
  "data": [
    {
      "id": "9a700000-0000-4000-8000-000000000018",
      "documentId": "d0c00000-0000-4000-8000-000000000042",
      "method": "bank_transfer",
      "amount": 135000,
      "receivedAt": "2026-10-20",
      "reference": "MBB 20OCT 884512",
      "status": "confirmed",
      "source": "manual",
      "receiptDocumentId": "d0c00000-0000-4000-8000-000000000043",
      "documentNumber": "INV-26-0042",
      "contactName": "Aina Rahman",
      "receiptNumber": "RC-26-0018"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false }
}

Record a payment

http

POST /api/v1/payments

Field	Type	Required	Description
`documentId`	string	Yes	An issued invoice, self-billed invoice or consolidated invoice that is not void or fully paid.
`method`	string	Yes	`chip`, `bank_transfer`, `cash`, `cheque` or `other`.
`amount`	integer	Yes	Amount received in sen, more than 0.
`receivedAt`	date	Yes	The date the money arrived, `YYYY-MM-DD`.
`reference`	string	No	Bank or payment reference, up to 100 characters.
`note`	string	No	Internal note, up to 2,000 characters.
`issueReceipt`	boolean	No	Issue a receipt for this payment. Default `true`. No receipt is issued for a self-billed invoice.
`source`	string	No	Where the payment came from: `manual` (default) or `webhook` for payments your system records from its own payment gateway.

When a receipt is issued, Invoa also emails it to the contact (if they have an email address) with the PDF attached. The receipt takes the next number in your receipt series, for example RC-26-0018.

bash

curl https://app.invoa.io/api/v1/payments \
  -H "Authorization: Bearer $INVOA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "documentId": "d0c00000-0000-4000-8000-000000000042",
    "method": "bank_transfer",
    "amount": 135000,
    "receivedAt": "2026-10-20",
    "reference": "MBB 20OCT 884512"
  }'

json

{
  "data": {
    "payment": {
      "id": "9a700000-0000-4000-8000-000000000018",
      "documentId": "d0c00000-0000-4000-8000-000000000042",
      "method": "bank_transfer",
      "amount": 135000,
      "receivedAt": "2026-10-20",
      "status": "confirmed",
      "receiptDocumentId": "d0c00000-0000-4000-8000-000000000043"
    },
    "receipt": {
      "id": "d0c00000-0000-4000-8000-000000000043",
      "type": "receipt",
      "status": "issued",
      "number": "RC-26-0018",
      "issueDate": "2026-10-20",
      "total": 135000
    },
    "document": {
      "id": "d0c00000-0000-4000-8000-000000000042",
      "status": "paid",
      "number": "INV-26-0042",
      "total": 135000,
      "paidAmount": 135000,
      "balance": 0
    }
  }
}

The response is 201 Created. payment is the payment object, receipt is the receipt's document record (without lines) or null, and document is the full document object for the invoice after the payment. All three are shortened above. Invoa sends the payment.confirmed webhook.

Important: Recording a payment is not idempotent. A retry records a second payment and issues a second receipt. If a request times out, check GET /payments?documentId=… before you try again.

Errors:

400 validation, for example a decimal amount or a missing receivedAt.
404 not_found if the invoice is not in this company.
422 invalid_state if the document is not an invoice, is a draft, void or already paid, or receivedAt falls in a period your accountant has locked.

Something unclear or out of date? Tell us at hello@invoa.io and we'll fix the page.

Payments

#The payment object

#List payments

#Record a payment

#Related

The payment object

List payments

Record a payment

Related