curl --request POST \
--url https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"event_id": "<string>",
"accounting_date": "2023-11-07T05:31:56Z",
"business_at": "2023-11-07T05:31:56Z",
"external_reference": "<string>",
"reason": "<string>",
"money_account_id": "<string>",
"bank_reference": "<string>",
"bank_fee_amount": 1,
"company_bank_fee_amount": 1,
"provision_amount": 1,
"physical_holder_id": "<string>"
}
'import requests
url = "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle"
payload = {
"event_id": "<string>",
"accounting_date": "2023-11-07T05:31:56Z",
"business_at": "2023-11-07T05:31:56Z",
"external_reference": "<string>",
"reason": "<string>",
"money_account_id": "<string>",
"bank_reference": "<string>",
"bank_fee_amount": 1,
"company_bank_fee_amount": 1,
"provision_amount": 1,
"physical_holder_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
event_id: '<string>',
accounting_date: '2023-11-07T05:31:56Z',
business_at: '2023-11-07T05:31:56Z',
external_reference: '<string>',
reason: '<string>',
money_account_id: '<string>',
bank_reference: '<string>',
bank_fee_amount: 1,
company_bank_fee_amount: 1,
provision_amount: 1,
physical_holder_id: '<string>'
})
};
fetch('https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event_id' => '<string>',
'accounting_date' => '2023-11-07T05:31:56Z',
'business_at' => '2023-11-07T05:31:56Z',
'external_reference' => '<string>',
'reason' => '<string>',
'money_account_id' => '<string>',
'bank_reference' => '<string>',
'bank_fee_amount' => 1,
'company_bank_fee_amount' => 1,
'provision_amount' => 1,
'physical_holder_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle"
payload := strings.NewReader("{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"source_type": "<string>",
"source_id": "<string>",
"company_id": "<string>",
"organization_id": "<string>",
"customer": {},
"customer_id": "<string>",
"order": {},
"amount": 123,
"currency_code": "<string>",
"currency_exponent": 123,
"original_amount": 123,
"original_currency_code": "<string>",
"original_currency_exponent": 123,
"reference": "<string>",
"received_at": "2023-11-07T05:31:56Z",
"accounting_status": "<string>",
"settlement_id": "<string>",
"cheque_transfer_id": "<string>",
"identity": {},
"financial_status": "<string>",
"status": "<string>",
"recovery_status": "<string>",
"accounting_owner": {},
"physical_holder": {},
"version": 123,
"operations": "<array>"
}{
"message": "<string>",
"errors": {}
}Confirm a cheque was paid
Records that the bank paid a cheque and the money reached the account (organization space).
curl --request POST \
--url https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"event_id": "<string>",
"accounting_date": "2023-11-07T05:31:56Z",
"business_at": "2023-11-07T05:31:56Z",
"external_reference": "<string>",
"reason": "<string>",
"money_account_id": "<string>",
"bank_reference": "<string>",
"bank_fee_amount": 1,
"company_bank_fee_amount": 1,
"provision_amount": 1,
"physical_holder_id": "<string>"
}
'import requests
url = "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle"
payload = {
"event_id": "<string>",
"accounting_date": "2023-11-07T05:31:56Z",
"business_at": "2023-11-07T05:31:56Z",
"external_reference": "<string>",
"reason": "<string>",
"money_account_id": "<string>",
"bank_reference": "<string>",
"bank_fee_amount": 1,
"company_bank_fee_amount": 1,
"provision_amount": 1,
"physical_holder_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
event_id: '<string>',
accounting_date: '2023-11-07T05:31:56Z',
business_at: '2023-11-07T05:31:56Z',
external_reference: '<string>',
reason: '<string>',
money_account_id: '<string>',
bank_reference: '<string>',
bank_fee_amount: 1,
company_bank_fee_amount: 1,
provision_amount: 1,
physical_holder_id: '<string>'
})
};
fetch('https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event_id' => '<string>',
'accounting_date' => '2023-11-07T05:31:56Z',
'business_at' => '2023-11-07T05:31:56Z',
'external_reference' => '<string>',
'reason' => '<string>',
'money_account_id' => '<string>',
'bank_reference' => '<string>',
'bank_fee_amount' => 1,
'company_bank_fee_amount' => 1,
'provision_amount' => 1,
'physical_holder_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle"
payload := strings.NewReader("{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.exowpee.com/v1/accounting/organization/books/{cheque}/cheques/{cheque}/settle")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event_id\": \"<string>\",\n \"accounting_date\": \"2023-11-07T05:31:56Z\",\n \"business_at\": \"2023-11-07T05:31:56Z\",\n \"external_reference\": \"<string>\",\n \"reason\": \"<string>\",\n \"money_account_id\": \"<string>\",\n \"bank_reference\": \"<string>\",\n \"bank_fee_amount\": 1,\n \"company_bank_fee_amount\": 1,\n \"provision_amount\": 1,\n \"physical_holder_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"source_type": "<string>",
"source_id": "<string>",
"company_id": "<string>",
"organization_id": "<string>",
"customer": {},
"customer_id": "<string>",
"order": {},
"amount": 123,
"currency_code": "<string>",
"currency_exponent": 123,
"original_amount": 123,
"original_currency_code": "<string>",
"original_currency_exponent": 123,
"reference": "<string>",
"received_at": "2023-11-07T05:31:56Z",
"accounting_status": "<string>",
"settlement_id": "<string>",
"cheque_transfer_id": "<string>",
"identity": {},
"financial_status": "<string>",
"status": "<string>",
"recovery_status": "<string>",
"accounting_owner": {},
"physical_holder": {},
"version": 123,
"operations": "<array>"
}{
"message": "<string>",
"errors": {}
}cheques.settle
Conditions
- The organization’s plan must include the accounting module; otherwise the call is refused before anything else.
- This action is available only in the organization space.
- The caller must have been granted access to the book in the path.
- The cheque must be in status in_collection and owned by the book in the path.
- The caller needs access to the organization book.
- 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.
- A money account is required: the one recorded by the deposit, or, when the deposit recorded none, the one in the request or else the payment’s. When the deposit recorded one and money_account_id differs, the call is refused.
- The money account must be an active organization account linked to an accounting account.
- bank_fee_amount must be less than the cheque amount; company_bank_fee_amount must be less than the company amount.
- When the cheque is owned by a company, bank_fee_amount is greater than 0 and the company and organization currencies differ, company_bank_fee_amount is required.
- Posts in the bank journal. For a cheque held by the organization: in the organization book, debit the money account for the amount minus the bank fee, debit the cheque fee expense account for the fee, and credit ‘cheques in collection’ for the full amount. For a cheque held by a company: in the company book, debit intercompany for the amount minus the company fee and the fee expense for the company fee, credit its ‘cheques in collection’ account; in the organization book, debit the money account and credit intercompany, both for the amount minus the bank fee.
- Changes the cheque to settled with no physical holder, increments its version and records a settled step.
- Updates the payment source status to settled.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Identifier of the cheque. The path has two segments named cheque: the first is the accounting book (the organization or one of its companies), the second is the cheque (27-character KSUID).
Query Parameters
Response mode. Default none; none answers 204 No Content.
none, resource 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.
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
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.
120Date (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.
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.
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.
255Why 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.
1000Identifier 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.
27Reference given by the bank for this step, up to 255 characters, kept in the metadata of the posted entries.
255Bank 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.
x >= 0The 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.
x >= 0Write-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.
x >= 0Reject 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.
company, organization, bank, customer, none Reject only: identifier (27-character KSUID) of the holder named by physical_holder_type. Default: the identifier of the book that owned the cheque.
27Response
Resource (only with response=resource).
Identifier of the cheque (27-character KSUID).
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).
Identifier of that originating payment (27-character KSUID).
Identifier of the company the record belongs to.
Identifier of the organization the record belongs to.
The customer who gave the cheque, as an object with the customer's id and name (name as recorded on the payment).
Identifier of the customer who gave the cheque (27-character KSUID).
The order the cheque paid, as an object with id and number; both are null when the cheque is not linked to an order.
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.
ISO 4217 code of the currency of amount.
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.
Amount as tendered, in minor units of original_currency_code.
ISO 4217 code of the currency the customer paid in.
Number of decimal places of the original currency; divide original_amount by 10 to this power.
Reference recorded on the originating payment.
Date and time the payment was received (ISO 8601).
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.
Identifier of the settlement that moved this payment into a money account, when one exists.
Identifier of the older cheque transfer made for this payment, when one exists.
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.
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).
Same value as financial_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.
Book that currently holds the cheque, as an object: type (company or organization) and id.
Who physically holds the paper cheque, as an object: type (company, organization, bank, customer or none) and id (null for bank and none).
Counter increased by one at each change of the cheque; use it to detect that the cheque moved.
Step history of the cheque in time order (deposit, settlement, rejection and so on, with reversals). Present only when requested with ?include=operations.