Payments API¶

Record payments received against a managed invoice. Payments are nested under a document (invoice): you record them against an invoice by ID, and each payment's currency is inherited from that invoice.

Record Payment¶

POST /api/v1/documents/{document_id}/payments

Request:

{
  "amount": "53.10",
  "paid_at": "2026-07-17T18:30:00Z",
  "method": "bank_transfer",
  "reference": "BANK-REF-10291",
  "notes": "Partial payment received"
}

Field	Required	Description
`amount`	Yes	Payment amount as a decimal string. The currency is inherited from the invoice.
`paid_at`	Yes	When the payment was received (ISO 8601 timestamp)
`method`	No	Payment method (e.g. `bank_transfer`, `card`, `cash`)
`reference`	No	External reference such as a bank or transaction ID
`notes`	No	Free-form note about the payment

Response 200 OK:

{
  "data": {
    "id": "pay_01XYZ",
    "invoice_id": "doc_01ABC",
    "amount": {
      "amount": "53.10",
      "currency": "USD"
    },
    "paid_at": "2026-07-17T18:30:00Z",
    "method": "bank_transfer",
    "reference": "BANK-REF-10291",
    "notes": "Partial payment received",
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Note

Payments cannot be recorded against a draft invoice. Attempting to do so returns 409 Conflict with error code conflict.

Try it

List Payments¶

GET /api/v1/documents/{document_id}/payments?limit=50

Response:

{
  "data": [
    {
      "id": "pay_01XYZ",
      "invoice_id": "doc_01ABC",
      "amount": {
        "amount": "53.10",
        "currency": "USD"
      },
      "paid_at": "2026-07-17T18:30:00Z",
      "method": "bank_transfer",
      "reference": "BANK-REF-10291",
      "notes": "Partial payment received",
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Try it

Get Payment¶

GET /api/v1/payments/{payment_id}

Fetch a single payment by its pay_* ID. The amount carries the currency inherited from the invoice. Returns 404 not_found if the payment doesn't exist.

Response:

{
  "data": {
    "id": "pay_01XYZ",
    "invoice_id": "doc_01ABC",
    "amount": { "amount": "53.10", "currency": "USD" },
    "paid_at": "2026-07-17T18:30:00Z",
    "method": "bank_transfer",
    "reference": "BANK-REF-10291",
    "notes": "Partial payment received",
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Try it

Update Payment¶

PATCH /api/v1/payments/{payment_id}

Only include the fields you want to change:

{
  "amount": "60.00",
  "reference": "BANK-REF-10292"
}

Field	Required	Description
`amount`	No	Payment amount as a decimal string
`paid_at`	No	When the payment was received (ISO 8601 timestamp)
`method`	No	Payment method
`reference`	No	External reference
`notes`	No	Free-form note about the payment

Try it

Delete Payment¶

DELETE /api/v1/payments/{payment_id}

Response:

{
  "data": {
    "deleted": true
  }
}

Try it