Match incoming collections to receivables

When a collection arrives at a receivable account, Max Pay records a movement but does not automatically link it to a specific receivable. The "this payment cancels this invoice" decision is always made by the integrator, because only the ERP knows the customer's accounting logic.

This guide covers the typical matching pattern: receive a collection webhook, identify which receivable it corresponds to, and mark it as paid.

To understand why Max Pay does not link automatically, see Receivables, movements and settlements.

Flow

1. Receive the movement

When a client transfers to a receivable account, Max Pay emits movement.created:

{
  "type": "movement.created",
  "data": {
    "movement": {
      "id": 88123,
      "receivableAccountId": 4242,
      "movementType": "CREDIT",
      "operationType": "DEPOSIT",
      "amount": 45000.00,
      "counterParty": {
        "name": "Kiosco Central",
        "taxId": "30998888887"
      }
    }
  }
}

The counterParty.taxId is the key to identifying the client. The receivableAccountId indicates the account credited.

2. Look up candidate receivables

List the client's (or the account's) PENDING receivables that could correspond to the collection:

GET /v1/receivables?receivableAccountId=4242&status=PENDING

If the customer operates with Pattern A accounts (one account per client), filtering by receivableAccountId is enough. In Pattern B or C, where a single account has several clients, also filter by clientId resolved from the taxId.

3. Decide the match

The strategy depends on the customer's model:

• Exact amount match: if movement.amount matches exactly with a single PENDING receivable, match directly.
• Match by externalId: if your ERP sends the client-side invoice number (via DEBIN or bank reference) and you saved it in externalId when creating the receivable, the match is trivial.
• Partial match: if less money came in than what was invoiced, the integrator can record a RETENTION or ADJUSTMENT for the difference (see Credit notes and adjustments) and mark the receivable as PAID.
• Advance / multi-collection: if more money comes in than what was invoiced, it stays as a credit balance with no receivable. It is matched when the next receivable appears.

4. Mark as PAID

Once the receivable is identified:

PATCH /v1/receivables/99001/status
Idempotency-Key: erp-mark-paid-99001
Content-Type: application/json

{ "status": "PAID" }

Max Pay emits receivable.paid. The receivable is recorded as collected.

Reconciliation at cutover

The change to PAID is an administrative decision by the integrator; it does not imply the money has entered the customer's current account. The effective transfer of money occurs in the settlement cycle, which moves collected amounts from the receivable account to the customer's current account.

The settlement report shows the difference between the settled amount (what actually came in) and the receivables marked as PAID/SETTLED (what the ERP declared). That difference helps detect wrong matchings or collections without a receivable.

Special case: rollback

If an incoming movement is reversed (bank rejection after crediting), Max Pay emits a new movement.created with operationType: ROLLBACK referencing the original movement. If the integrator had already marked the receivable as PAID based on that collection, they must reverse the matching by cancelling the receivable and issuing a new one if applicable (see Lifecycle — there is no native rollback from PAID to PENDING).