Developers

Payments

A Payment is money received against one document, in that document’s currency. On this page: the fields of a Payment and of its Receipt, how to record a Payment and get its Receipt, how to amend and reverse one — held to the same rules as Add Payment in Essentio — and how to list them and download a Receipt’s PDF.

Which document takes a Payment

Only an issued Invoice or Proforma Invoice takes a Payment, and only while something is due on it. A Payment is in the document’s currency, above zero, and never above its Amount due. Recording one moves the document to partially_paid, or to paid once its Amount due is zero, and issues its Receipt in the same step.

A document says whether it takes one now: its still_takes_payment, and actions.record_payment for your key’s Role.

  • A Credit Note, a Quote, a Draft and a Cancelled document take none.
  • A Proforma Invoice converted into an Invoice takes none: the Invoice carries the debt, and counts the Proforma’s Payments as its Prepaid. Recording on it is refused with the remedy record_on_its_invoice, and invoice names the Invoice to record it on — while that Invoice still takes a Payment.

Recording on a converted Proforma Invoice: 422

{
  "error": {
    "type": "refusal",
    "code": "payment_goes_to_its_invoice",
    "message": "This Proforma Invoice was converted into INV-0042: record the payment there.",
    "remedy": "record_on_its_invoice",
    "invoice": { "id": 131, "document_number": "INV-0042" }
  }
}

Refusals

A Payment the document cannot take answers 422 with the error type refusal, a message in Essentio’s words and a Refusal code, as a document’s Actions do. Nothing was written: no Payment, no Receipt, no receipt number.

  • Name
    type_takes_no_payments
    Refused by
    Record, Amend
    Description

    A Credit Note or a Quote takes no Payments; message says why.

  • Name
    draft_takes_no_payments
    Refused by
    Record, Amend
    Description

    A Draft is issued first.

  • Name
    cancelled_takes_no_payments
    Refused by
    Record, Amend
    Description

    A Cancelled document takes none.

  • Name
    nothing_due
    Refused by
    Record
    Description

    The document’s Amount due is zero.

  • Name
    payment_goes_to_its_invoice
    Refused by
    Record
    Description

    The Proforma Invoice was converted into an Invoice, which takes the Payment: remedy record_on_its_invoice and invoice, while that Invoice still takes one.

  • Name
    payment_exceeds_amount_due
    Refused by
    Record, Amend
    Description

    The amount is above what is due. An amended Payment’s own amount is given back first.

  • Name
    payment_currency_mismatch
    Refused by
    Record, Amend
    Description

    currency was sent, and it is not the document’s.

  • Name
    payment_reversed
    Refused by
    Amend, Reverse
    Description

    The Payment was reversed already.

  • Name
    numbering_at_its_end
    Refused by
    Record
    Description

    The Receipt's next number is the largest the numbering holds, which it never takes, because it cannot count past it; message names it. Nothing is written, and nobody types a Receipt's number, so there is no way out to send.

A key whose Role may not record Payments — a Viewer’s — is answered 403 permission. A field the rules refuse is 422 invalid_request, with errors naming it in the form’s words. They are asked in that order, and before the document: a body the rules refuse is invalid_request even on a document that takes no Payment, and a Refusal answers only a body they accept.

Reversing, not deleting

A recorded Payment is never deleted. Reversing it marks it voided: it stays in the document’s history and counts in no figure, and its Receipt stays too, keeping its number, with the moment it was voided (voided_at) — so the receipt numbers have no hole. The document’s status follows: a Paid Invoice whose Payment is reversed is owed that amount again.

The Payment model

A Payment as the API answers it. Every amount is an exact decimal string at its currency’s scale — "100.00", never a number.

Properties

  • Name
    id
    Type
    integer
    Description

    The Payment’s identifier.

  • Name
    document_id
    Type
    integer
    Description

    The document it was recorded against.

  • Name
    status
    Type
    string
    Description

    completed, or voided once reversed. Only a completed Payment counts. (pending and failed are held only by older data, and count nowhere.) Another value may be added within v1: keep one you do not know.

  • Name
    amount
    Type
    string
    Description

    The money received: "100.00".

  • Name
    currency
    Type
    string
    Description

    The document’s, as an ISO 4217 code.

  • Name
    payment_date
    Type
    date
    Description

    The day the money was received.

  • Name
    payment_method
    Type
    string
    Description

    bank_transfer, cash, check, credit_card, debit_card or other. Another value may be added within v1: keep one you do not know.

  • Name
    bank_account_id
    Type
    integer or null
    Description

    The Business’s bank account a bank transfer reached. null for any other method.

  • Name
    reference
    Type
    string or null
    Description

    The payer’s or the bank’s reference.

  • Name
    notes
    Type
    string or null
    Description

    The Business’s own note.

  • Name
    recorded_by, amended_by
    Type
    object or null
    Description

    The API key or Connected app that recorded the Payment, and that last amended it: {"type": "api_key", "name": "Bank sync"} — type is api_key or connected_app (another may be added within v1), name the key’s name or the OAuth app’s, as it stood then, kept when the key is revoked or the app deleted. null for a Payment recorded (or last amended) in Essentio, where its User is not named. Essentio’s Payment History shows the same.

  • Name
    receipt
    Type
    Receipt or null
    Description

    The Receipt issued with it. null only for a Payment recorded before Receipts existed.

  • Name
    created_at, updated_at
    Type
    timestamp
    Description

    When the Payment was recorded, and when it last changed, in UTC.

The Receipt model

The numbered record of one Payment: a snapshot of it, amended with it.

Properties

  • Name
    id
    Type
    integer
    Description

    The Receipt’s identifier.

  • Name
    receipt_number
    Type
    string
    Description

    Taken from the Business’s receipt numbering when the Payment was recorded: R-0001.

  • Name
    payment_id, document_id
    Type
    integer
    Description

    Its Payment, and the document the Payment was recorded against.

  • Name
    amount, currency, payment_date, payment_method, reference
    Type
    string
    Description

    What its Payment says.

  • Name
    issue_date
    Type
    date
    Description

    The day the Receipt was issued: the day its Payment was recorded.

  • Name
    voided_at
    Type
    timestamp or null
    Description

    When its Payment was reversed. null while it stands.

  • Name
    voided_by
    Type
    object or null
    Description

    The API key or Connected app that reversed its Payment, as recorded_by names one. null while it stands, or when it was reversed in Essentio.

  • Name
    created_at, updated_at
    Type
    timestamp
    Description

    In UTC.

POST/v1/documents/{document}/payments

Record a Payment

Records money received against an issued Invoice or Proforma Invoice, and issues its Receipt in the same step. An Admin’s or Member’s key may record; a Viewer’s may not.

Send an Idempotency-Key — your bank line’s or order’s id — so a retry after a lost connection answers the first Payment and records nothing again. Without one, the same body sent twice is two Payments.

Body

  • Name
    amount
    Type
    string
    Description

    Required. A decimal string above zero and not above the document’s Amount due: "100.00". It has no more decimals than its currency has — "10.005" in EUR is refused under amount, never rounded. A JSON number is refused — send a string.

  • Name
    payment_date
    Type
    date
    Description

    Required. The day the money was received, YYYY-MM-DD.

  • Name
    payment_method
    Type
    string
    Description

    Required. bank_transfer, cash, check, credit_card, debit_card or other.

  • Name
    bank_account_id
    Type
    integer
    Description

    Required for a bank_transfer: the Business’s bank account the money reached, from its setup.

  • Name
    reference
    Type
    string
    Description

    Optional, up to 255 characters. Printed on the Receipt.

  • Name
    notes
    Type
    string
    Description

    Optional.

  • Name
    currency
    Type
    string
    Description

    Not needed: a Payment is always in its document’s currency. Sent, it must be that currency.

Answers

  • Name
    201
    Type
    Payment
    Description

    The Payment, with its Receipt.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no document with this id.

  • Name
    409
    Type
    Error
    Description

    The first request under this Idempotency-Key is still being performed.

  • Name
    422
    Type
    Error
    Description

    A refusal (see Refusals), or a field the rules refused (invalid_request).

Request

POST/v1/documents/118/payments
curl https://api.essentio.pro/v1/documents/118/payments \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: bank-line-881" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "payment_date": "2026-09-25", "payment_method": "bank_transfer", "bank_account_id": 3, "reference": "SEPA 881"}'

Response

{
  "id": 57,
  "document_id": 118,
  "status": "completed",
  "amount": "100.00",
  "currency": "EUR",
  "payment_date": "2026-09-25",
  "payment_method": "bank_transfer",
  "bank_account_id": 3,
  "reference": "SEPA 881",
  "notes": null,
  "recorded_by": {"type": "api_key", "name": "Bank sync"},
  "amended_by": null,
  "receipt": {
    "id": 41,
    "receipt_number": "R-0041",
    "payment_id": 57,
    "document_id": 118,
    "amount": "100.00",
    "currency": "EUR",
    "payment_date": "2026-09-25",
    "payment_method": "bank_transfer",
    "reference": "SEPA 881",
    "issue_date": "2026-09-27",
    "voided_at": null,
    "voided_by": null,
    "created_at": "2026-09-27T10:00:00+00:00",
    "updated_at": "2026-09-27T10:00:00+00:00"
  },
  "created_at": "2026-09-27T10:00:00+00:00",
  "updated_at": "2026-09-27T10:00:00+00:00"
}
GET/v1/payments

List Payments

Lists the Business’s Payments a page at a time, oldest first, reversed ones included, each with its Receipt. Every Role may read them. Page through them as through every list (Pagination).

Query parameters

  • Name
    limit
    Type
    integer
    Description

    How many Payments a page holds: 1 to 100. Not sent: 25.

  • Name
    cursor
    Type
    string
    Description

    The next_cursor of the page before. Not sent: the first page.

  • Name
    document_id
    Type
    integer
    Description

    Only the Payments recorded against this document. Send it with every page.

Answers

  • Name
    200
    Type
    PaymentList
    Description

    data: the page’s Payments. next_cursor: where the next page starts, or null on the last.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    422
    Type
    Error
    Description

    A limit out of range, or a cursor this API did not give.

Request

GET/v1/payments
curl -G https://api.essentio.pro/v1/payments \
  -H "Authorization: Bearer ess_your_api_key" \
  -d document_id=118
GET/v1/payments/{payment}

Retrieve a Payment

One Payment of the Business, with its Receipt. Every Role may read it. A Payment of another Business is not found.

Answers

  • Name
    200
    Type
    Payment
    Description

    The Payment.

  • Name
    404
    Type
    Error
    Description

    The Business has no Payment with this id.

Request

GET/v1/payments/57
curl https://api.essentio.pro/v1/payments/57 \
  -H "Authorization: Bearer ess_your_api_key"
PATCH/v1/payments/{payment}

Amend a Payment

Corrects a recorded Payment, as Edit on a Payment in Essentio does. The fields sent change and nothing else; its Receipt keeps its number and says what the Payment now says; the document’s status follows. Moving to a method other than a bank transfer drops the bank account. An Admin’s or Member’s key may amend; a Viewer’s may not.

Body

The fields of a record, each optional — but at least one: a body that sends none of them is 422 invalid_request, errors.payment saying there is nothing to change, and nothing is written.

Answers

  • Name
    200
    Type
    Payment
    Description

    The Payment as it now stands, with its Receipt.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no Payment with this id.

  • Name
    422
    Type
    Error
    Description

    A refusal — payment_reversed, payment_exceeds_amount_due, … — or a field the rules refused, or a body that sends no field (errors.payment).

Request

PATCH/v1/payments/57
curl -X PATCH https://api.essentio.pro/v1/payments/57 \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": "75.00"}'
POST/v1/payments/{payment}/reverse

Reverse a Payment

Reverses a Payment, as Reverse in Essentio does: it becomes voided, and its Receipt stays with its number and a voided_at (Reversing, not deleting). Any Payment may be reversed, once. An Admin’s or Member’s key may reverse; a Viewer’s may not.

Answers

  • Name
    200
    Type
    Payment
    Description

    The Payment, voided, with its voided Receipt.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no Payment with this id.

  • Name
    409
    Type
    Error
    Description

    The first request under this Idempotency-Key is still being performed.

  • Name
    422
    Type
    Error
    Description

    A refusal: payment_reversed.

Request

POST/v1/payments/57/reverse
curl -X POST https://api.essentio.pro/v1/payments/57/reverse \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: reverse-57"
GET/v1/receipts

List Receipts

Lists the Business’s Receipts a page at a time, oldest first, voided ones included. Every Role may read them.

Query parameters

  • Name
    limit, cursor
    Type
    integer, string
    Description

    As for Payments.

  • Name
    document_id
    Type
    integer
    Description

    Only the Receipts of Payments recorded against this document.

Answers

  • Name
    200
    Type
    ReceiptList
    Description

    data: the page’s Receipts. next_cursor: where the next page starts, or null on the last.

Request

GET/v1/receipts
curl -G https://api.essentio.pro/v1/receipts \
  -H "Authorization: Bearer ess_your_api_key" \
  -d document_id=118
GET/v1/receipts/{receipt}

Retrieve a Receipt

One Receipt of the Business. Every Role may read it.

Answers

  • Name
    200
    Type
    Receipt
    Description

    The Receipt.

  • Name
    404
    Type
    Error
    Description

    The Business has no Receipt with this id.

Request

GET/v1/receipts/41
curl https://api.essentio.pro/v1/receipts/41 \
  -H "Authorization: Bearer ess_your_api_key"
GET/v1/receipts/{receipt}/pdf

Download a Receipt’s PDF

The Receipt’s PDF — the same file the Receipts screen in Essentio downloads, with the Business’s Branding. It reads “Paid in full” only when the Payments up to this one reached the document’s Total, and a voided Receipt’s says it is void. Every Role may download it.

Answers

  • Name
    200
    Type
    application/pdf
    Description

    The PDF, as an attachment named after the Receipt.

  • Name
    404
    Type
    Error
    Description

    The Business has no Receipt with this id.

Request

GET/v1/receipts/41/pdf
curl https://api.essentio.pro/v1/receipts/41/pdf \
  -H "Authorization: Bearer ess_your_api_key" \
  -o receipt.pdf