Payments

A payment in xTool records a movement of money for an organisation. It is an independent entity: it can exist without a document or a transaction.

Use payments when you need to store how much was paid, when, in which currency, and which invoice documents that money applies to.

Direction

Direction is relative to the organisation:

• incoming — money received by the organisation
• outgoing — money sent by the organisation

Currency and amount

Create and update use a constrained ISO 4217 currency code (for example EUR).

amount is a positive decimal. On create, currency is required.

Updating the payment amount with PATCH does not automatically change existing allocations. If the payment already has allocations to documents and you also want those allocated amounts to match the new payment amount (or a new split), send an updated allocations array in the same request. Omit allocations only when you intentionally leave the current allocations unchanged.

Allocations

A payment can be split across documents through allocations.

Each allocation links:

• a document_id
• an amount applied to that document

Rules of thumb:

• One payment can allocate to several documents
• One document can receive several payments over time
• Partial payments are normal: allocate only the amount paid so far, then create another payment later for the remainder

On payment update, if you send allocations, they replace the existing set for that payment.

Allocation shape in the API

On payment detail (GET / POST / PATCH responses), each allocation includes:

List responses use a shorter allocation view (document_id, document_number, amount).

Relation to transactions

Payments are not transactions.

For France invoices that already have a send.france transaction, creating a payment allocated to that invoice can also sync the payment to the France provider. Use france.invoice.payment_received on the send transaction as a shortcut. For inbound invoices (receive.france), use france.invoice.payment_sent to mark payment as transmitted without creating a Payment. On B2B domestic, these correspond to CDV 212 / 211; B2C and B2B cross-border may not use CDV.

See Send and receive invoices and Transactions.

API overview

Create example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "direction": "incoming",
  "amount": "300.00",
  "currency": "EUR",
  "paid_at": "2026-08-09T00:00:00Z",
  "allocations": [
    {
      "document_id": "invoice-document-uuid",
      "amount": "300.00"
    }
  ]
}

Example — update payment amount and keep the allocation in sync:

1
2
3
4
5
6
7
8
9

{
  "amount": "500.00",
  "allocations": [
    {
      "document_id": "invoice-document-uuid",
      "amount": "500.00"
    }
  ]
}

Relation to tax reports

Payments can become sources of a tax report when regulatory reporting aggregates eligible invoices and payments (for example certain France e-reporting scenarios).