Receivables, movements and settlements

Three concepts that are easily confused when integrating for the first time, because they all talk about "money" but represent different things. This page explains them together.

Definitions

Receivable — an accounting record of debt (or of its modification). The customer creates it when issuing an invoice, credit note, return, adjustment or withholding. The receivable expresses "what is expected to be collected" or "what is no longer owed". It is not money, it is a document.

Movement — a record of money that effectively came in or out of a receivable account. It originates when a client transfers to the CVU, or when an internal operation runs (tax, commission, rollback). It is real money, not a document.

Settlement — a periodic accounting cutover that moves the funds accumulated in a receivable account into the customer's current account. Max Pay does it automatically. It comes with a summary including totals, taxes, commissions and the receivables it covers.

How they relate

The customer decides when and to which receivable to match each incoming movement: Max Pay does not do it automatically.

Why they are not linked automatically

When a B2B client with several outstanding invoices transfers $45,000, the system cannot infer which invoice was paid. Did they pay the oldest? The newest? A partial amount? Did they settle two together? That decision is accounting-related and depends on each customer's policy.

That is why Max Pay separates:

• Movements are facts: this amount came in on this day.
• Receivables are customer intentions: "these receivables are pending".
• The matching is done by the integrator with PATCH /v1/receivables/{id}/status (see Match incoming collections to receivables).

Comparison table

Aspect	Receivable	Movement	Settlement
What does it represent?	Debt or debt adjustment	Money coming in/out	Periodic accounting cutover
Who creates it?	The customer (ERP)	External source (client) or internal (taxes, rollback)	Generated automatically by Max Pay
When?	When the ERP invoices	When money arrives or a debit is applied	Periodically, per receivable account
Granularity?	One per invoice/note/adjustment	One per transfer	One per account and cycle
Webhook?	receivable.created, receivable.paid, etc.	movement.created	settlement.completed

Combined lifecycle

A typical case (Pattern A):

1. Day 1: ERP creates an invoice → POST /v1/receivables → state PENDING. Webhook receivable.created.
2. Day 5: client transfers to the CVU → Max Pay records movement.created. The receivable stays in PENDING until the integrator decides to match it.
3. Day 5 (same day): ERP receives the webhook, identifies that the collection corresponds to that invoice, calls PATCH /receivables/{id}/status PAID. Webhook receivable.paid.
4. Day 15 (cutover): settlement cycle. The movement enters the settlement; the receivable transitions to SETTLED. Webhook settlement.completed with the summary, and receivable.settled.

Differences between collected and invoiced

It is common for the sum of PAID/SETTLED receivables not to match the settled amount exactly. Common causes:

• Tax withholdings discounted by the client (recorded as a RETENTION child of the invoice).
• Max Pay commissions on the collection.
• Taxes applied by the system before settling.
• Collections without a receivable (money arrived but the ERP had no invoice issued).
• Partial collections or payments covering several receivables.

The report for each settlement details these differences so the integrator can reconcile.