POST
Deposit a cheque at the bank (company)
Company space Accounting module For: Accountant, Manager · Permission: cheques.deposit Conditions
  • The organization’s plan must include the accounting module; otherwise the call is refused before anything else.
  • The cheque must be in status received and owned by the book in the URL (the company in the company space).
  • Each request needs an event_id. Sending the same event_id again with the same payload returns the cheque unchanged without posting again; the same event_id with a different payload for the same kind of step is refused.
  • business_at must not be earlier than the business time of the latest step recorded on the cheque.
  • The accounting_date must fall in an open fiscal period of every book written to, and the fiscal year currency must match the entry currency.
  • When money_account_id is sent (or, failing that, when the payment has a money account) it must be a money account open to the company for incoming flows, active, linked to an accounting account and accepting cheques; when neither exists, the payment route the cheque was received on must be allowed for incoming flows.
  • A money account without a linked accounting account, or an inactive one, refuses the call.
What else happens
  • Posts one entry in the company book in the bank journal: debit the ‘cheques in collection’ account, credit the ‘cheques received’ account. No money moves yet.
  • Changes the cheque status from received to in_collection and sets its physical holder to the bank.
  • Records a deposit step on the cheque history, with the money account when one was used, and updates the payment source status to in_collection.
  • Increments the cheque version.
Part of Handle cheques.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

cheque
string
required

Identifier of the cheque (27-character KSUID).

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, company_id, organization_id, customer, customer_id, identity, financial_status, status, recovery_status, accounting_owner, physical_holder, version, source_type, source_id, amount, currency_code, currency_exponent, original_amount, original_currency_code, original_currency_exponent, reference, received_at, accounting_status, settlement_id, cheque_transfer_id, order.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: operations.

Body

application/json
event_id
string
required

Required, except when undoing a step (reverse), where it is optional and ignored for replay. Unique key chosen by the caller for this step on this cheque, up to 120 characters. Sending it again for the same kind of step with the same payload returns the cheque without recording the step again; reusing it for the same kind of step with a different payload is refused.

Maximum string length: 120
accounting_date
string<date-time>
required

Date (ISO 8601) the accounting entries are posted on. It must fall in an open fiscal period. When undoing a step, it is the date of the reversing entries; if the original period is closed they go to the first day of the next open period.

business_at
string<date-time>
required

Date and time (ISO 8601) the step really happened. Required on every call. For steps other than undo it must not be earlier than the latest step already recorded on the cheque.

external_reference
string | null

Free reference for the step (for example a bank slip number), up to 255 characters. Kept on the step and on the entries it posts.

Maximum string length: 255
reason
string | null

Why the step is taken, up to 1000 characters. Required for reject, return-to-company, return-to-customer, write-off and undoing a step; optional otherwise.

Maximum string length: 1000
money_account_id
string | null

Identifier of the money account (27-character KSUID) involved. Used by deposit (where the cheque is deposited), settle (where the money arrives) and reject when a bank fee is sent (account charged with the fee); ignored by other steps. On settle, and on reject with a fee, the account recorded by the deposit is used when there is one, and a different money_account_id is refused; otherwise, if omitted, the payment's money account is used. It must be active and linked to an accounting account.

Required string length: 27
bank_reference
string | null

Reference given by the bank for this step, up to 255 characters, kept in the metadata of the posted entries.

Maximum string length: 255
bank_fee_amount
integer | null

Bank fee in minor units of the organization currency. Used by settle (deducted from the money received, must be less than the cheque amount) and reject (a fee entry is posted and a money account is required). No accounting effect on other steps. Default 0.

Required range: x >= 0
company_bank_fee_amount
integer | null

The same bank fee in minor units of the company currency. Defaults to bank_fee_amount; required when the cheque is owned by a company, a fee is sent and the company and organization currencies differ.

Required range: x >= 0
provision_amount
integer | null

Write-off only: part of the written-off debt, in minor units of the company currency, booked to the bad-debt provision instead of the loss. Cannot exceed the cheque amount. Default 0. Ignored by other steps.

Required range: x >= 0
physical_holder_type
enum<string> | null

Reject only: who holds the paper cheque after the bank refused it. company, organization, bank, customer or none. Default: the type of the book that owned the cheque. Ignored by other steps, which set the holder themselves.

Available options:
company,
organization,
bank,
customer,
none
physical_holder_id
string | null

Reject only: identifier (27-character KSUID) of the holder named by physical_holder_type. Default: the identifier of the book that owned the cheque.

Required string length: 27

Response

Resource (only with response=resource).

id

Identifier of the cheque (27-character KSUID).

source_type

Type of the payment this cheque came from, for example order_payment (a sale) or customer_credit_payment (a payment on a customer's debt).

source_id

Identifier of that originating payment (27-character KSUID).

company_id

Identifier of the company the record belongs to.

organization_id

Identifier of the organization the record belongs to.

customer
object

The customer who gave the cheque, as an object with the customer's id and name (name as recorded on the payment).

customer_id

Identifier of the customer who gave the cheque (27-character KSUID).

order
object

The order the cheque paid, as an object with id and number; both are null when the cheque is not linked to an order.

amount
integer

Cheque amount in minor units of currency_code (divide by 10 to the power currency_exponent). It is the amount in the company's functional currency.

currency_code

ISO 4217 code of the currency of amount.

currency_exponent
integer

Number of decimal places of the currency (0 for XOF). An amount in minor units divided by 10 to this power gives the amount in the currency.

original_amount
integer

Amount as tendered, in minor units of original_currency_code.

original_currency_code

ISO 4217 code of the currency the customer paid in.

original_currency_exponent
integer

Number of decimal places of the original currency; divide original_amount by 10 to this power.

reference

Reference recorded on the originating payment.

received_at

Date and time the payment was received (ISO 8601).

accounting_status

Status of the payment source for accounting. It starts as not_initiated, follows the cheque's financial status after each step (received, in_collection, settled, unpaid, returned), becomes resolved or written_off after recovery, and shows transferred or reversed for the older cheque-transfer flow.

settlement_id

Identifier of the settlement that moved this payment into a money account, when one exists.

cheque_transfer_id

Identifier of the older cheque transfer made for this payment, when one exists.

identity
object

What is written on the cheque, as an object: series, number, issuing_bank_name, issuing_bank_code, drawer_name, drawer_account_reference, issue_date and due_date (dates as YYYY-MM-DD), beneficiary_name. Each is null when unknown.

financial_status

Where the cheque is in its life: received (held, not yet deposited), in_collection (deposited at the bank), settled (the bank paid it), unpaid (the bank refused it), returned (given back to the customer).

status

Same value as financial_status.

recovery_status

Follow-up of an unpaid or returned cheque: open (the debt is still to be recovered), resolved (a replacement payment was recorded), written_off (the debt was written off). Null while no recovery applies.

accounting_owner
object

Book that currently holds the cheque, as an object: type (company or organization) and id.

physical_holder
object

Who physically holds the paper cheque, as an object: type (company, organization, bank, customer or none) and id (null for bank and none).

version
integer

Counter increased by one at each change of the cheque; use it to detect that the cheque moved.

operations
array

Step history of the cheque in time order (deposit, settlement, rejection and so on, with reversals). Present only when requested with ?include=operations.