API reference

Payments

Money received from customers and paid to vendors, applied across invoices and bills, with what is left unapplied.

GET/v1/paymentsList payments
POST/v1/paymentsRecord a payment received or made
POST/v1/payments/sendWrite a payment to send
GET/v1/payments/{payment_id}Get a payment
PATCH/v1/payments/{payment_id}Change a payment not yet released
POST/v1/payments/{payment_id}/applyApply a payment to invoices or bills
POST/v1/payments/{payment_id}/cancelCancel a payment not yet released
POST/v1/payments/{payment_id}/releaseRelease an approved payment to be sent
POST/v1/payments/{payment_id}/request_approvalAsk for a payment's approval
POST/v1/payments/{payment_id}/voidVoid a recorded payment

Guides: Record payments and apply them

List payments

GET/v1/payments

client.payments.list()

The payments of these books, the newest first, each with what it is applied to and what is left unapplied.

Parameters

Name	Type	Description
`direction`Query	string or null	Only `in` or `out` payments.
`kind`Query	string or null	Only `customer` or `vendor` payments.
`party_id`Query	string or null	An id that starts with `party_`.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200PaymentPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/payments" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Record a payment received or made

POST/v1/payments· Idempotent

client.payments.record()

Record a payment that happened: money in from a customer, or out to a vendor, through a bank, cash or card account. It is posted on its day and applied to the invoices or bills listed (or the oldest first); whatever is not applied stays open as unapplied cash.

Request body

PaymentRecord

Response

201PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"…","amount":0,"direction":"…","effective_on":"2026-09-30","kind":"…","party_id":"…"}'

Write a payment to send

POST/v1/payments/send· Idempotent

client.payments.createToSend()

Write a payment to a vendor that LedgerIt will send, to one of the vendor's destinations. It is created: nothing is sent and nothing is on the books. It leaves created only once a person who may approve money has approved it as it then is, and its destination is verified.

Request body

PaymentSend

Response

201PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/send" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"…","amount":0,"destination_id":"…","effective_on":"2026-09-30","party_id":"…"}'

Get a payment

GET/v1/payments/{payment_id}

client.payments.get()

One payment, what it is applied to and what is left unapplied.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/payments/{payment_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Change a payment not yet released

PATCH/v1/payments/{payment_id}· Idempotent

client.payments.update()

Change a payment not yet released: its amount, day, account, destination, reference or memo. Any approval of it stops standing, since it approved something else: ask again. Refused with conflict once it is released, and for a recorded payment.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Request body

PaymentChange

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/payments/{payment_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Apply a payment to invoices or bills

POST/v1/payments/{payment_id}/apply· Idempotent

client.payments.apply()

Apply what is left of a payment to invoices or bills of the same party: those listed, for the amounts given, or the oldest first.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Request body

PaymentApply

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/{payment_id}/apply" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Cancel a payment not yet released

POST/v1/payments/{payment_id}/cancel· Idempotent

client.payments.cancel()

Give up a payment not yet released. It stays listed as cancelled.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/{payment_id}/cancel" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Release an approved payment to be sent

POST/v1/payments/{payment_id}/release· Idempotent

client.payments.release()

Release a payment to be sent: out of created, refused with conflict unless an approval of exactly what it now is stands and has not expired, and its destination is verified. A released payment due by today is sent through the provider of the account it is paid from, once; one due later is sent on its day.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/{payment_id}/release" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Ask for a payment's approval

POST/v1/payments/{payment_id}/request_approval· Idempotent

client.payments.requestApproval()

Ask for approval of the payment as it now is. A person with money.approve decides it at /v1/approvals/{id}/decide; it expires after the hours given (72 by default).

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Request body

ApprovalAsk

Response

200AskedOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/{payment_id}/request_approval" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Void a recorded payment

POST/v1/payments/{payment_id}/void· Idempotent

client.payments.void()

Take a payment off the books by reversing its entry. Refused with conflict while any of it is applied: undo those allocations first.

Parameters

Name	Type	Description
`payment_id`Path · Required	string	An id that starts with `pay_`.

Request body

PaymentVoid

Response

200PaymentOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/payments/{payment_id}/void" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

The objects these operations take and return.

PaymentPage

Name	Type	Description
`data`Required	array of PaymentOut
`has_more`Required	boolean
`next_cursor`Required	string or null

PaymentRecord

Name	Type	Description
`account_id`Required	string	The bank or cash account it moved through, or a card for money out.
`amount`Required	number \| string
`applications`	array of ApplicationIn	The invoices or bills it pays, and how much of each.
`direction`Required	string	`in` from a customer, or `out` to a vendor.
`effective_on`Required	string (date)	The day the money moved.
`kind`Required	string	`customer` (money in) or `vendor` (money out).
`memo`	string or null
`oldest_first`	boolean	Apply it to the party's open invoices or bills, the earliest due first, until it runs out. Default false
`party_id`Required	string	The customer or vendor: a counterparty of these books.
`reference`	string or null	The bank's reference, a check number.

PaymentOut

Name	Type	Description
`account_id`Required	string	An id that starts with `gla_`.
`amount`Required	string
`applied_to`Required	array of AppliedOut
`approved`Required	boolean	For a payment not yet sent: an approval of it as it now is stands.
`created_at`Required	string (date-time)
`currency`Required	string
`destination_id`Required	string or null	An id that starts with `dest_`.
`direction`Required	string
`effective_on`Required	string (date)
`entry_id`Required	string or null	An id that starts with `je_`.
`id`Required	string	An id that starts with `pay_`.
`kind`Required	string
`memo`Required	string or null
`party_id`Required	string	An id that starts with `party_`.
`reference`Required	string or null
`status`Required	string	A recorded payment is `settled` once on the books and `void` once reversed. One LedgerIt sends is `created`, `approved` once released, `submitted` once sent to its provider, `failed` when the provider says nothing was sent, or `cancelled`.
`submission`Required	SubmissionOut or null	How it was sent, for a payment LedgerIt sent.
`unapplied`Required	string	What is not yet applied to an invoice or bill; 0 for a void payment.
`void_entry_id`Required	string or null	An id that starts with `je_`.
`voided_at`Required	string (date-time) or null

PaymentSend

Name	Type	Description
`account_id`Required	string	The bank or cash account it is paid from.
`amount`Required	number \| string
`destination_id`Required	string	Where it goes: one of the vendor's payment destinations.
`effective_on`Required	string (date)	The day it is to be paid.
`memo`	string or null
`party_id`Required	string	The vendor: a counterparty of these books.
`reference`	string or null

PaymentChange

Name	Type	Description
`account_id`	string or null	An id that starts with `gla_`.
`amount`	number \| string or null
`destination_id`	string or null	An id that starts with `dest_`.
`effective_on`	string (date) or null
`memo`	string or null
`reference`	string or null

PaymentApply

Name	Type	Description
`applications`	array of ApplicationIn
`oldest_first`	boolean	Apply what is left to the oldest open invoices or bills. Default false

ApprovalAsk

Name	Type	Description
`expires_in_hours`	integer or null	How long the approval stands once given; 72 hours when left out.

AskedOut

Name	Type	Description
`approval_id`Required	string	An id that starts with `appr_`.
`expires_at`Required	string (date-time) or null
`status`Required	string

PaymentVoid

Name	Type	Description
`reason`	string or null	Why it is voided; written on the reversal.

ApplicationIn

Name	Type	Description
`amount`Required	number \| string	How much of the payment goes to it.
`document_id`Required	string	An issued invoice (money in) or approved bill (money out) of the same party.

AppliedOut

Name	Type	Description
`amount`Required	string
`document`Required	string	`invoice` or `bill`.
`document_id`Required	string	An id. Which resource it names is given by the field beside it.
`number`Required	string	The invoice's number, or the vendor's number for the bill.

SubmissionOut

How a payment LedgerIt sends went to its provider.

Name	Type	Description
`answered_at`Required	string (date-time) or null
`checks`Required	integer	How many times the provider was asked whether it holds the payment.
`external_id`Required	string or null	The provider's id for the payment, once it holds it.
`failure`Required	string or null	Why the provider refused it, in its words.
`provider`Required	string	The provider it was sent through.
`status`Required	string	`sending`, then the provider's answer: `accepted` (it holds the payment), `rejected` (it refused it), `uncertain` (no answer yet: it is asked, never sent again) or `absent` (asked, it holds no such payment).
`submitted_at`Required	string (date-time)