Payment allocation ( payment_allocation )

Role

Whenever a payment is reconciled with one or more invoices, a payment_allocation is created to materialize that allocation. It answers: how much of which payment was applied to which invoice?

The allocation is a two-level object:

• L'header (pal_) identifies the source and its overall allocation status (partial or complete).

• The lignes (pai_) detail each individual allocation — how much was applied to which target (invoice, credit note, order, etc.).

Creating an allocation has immediate side effects: update of the settlement_status of the relevant financial documents and update of the status of the source payment. Invoice lifecycle remains independent.

Identifier and structure

The header uses prefix pal_ ; each line uses prefix pai_.

{
"object": "payment_allocation",
"id": "pal_3c8f1a9b2d4e7f6a",
"merchant_id": "mer_1a2b3c4d5e6f7a8b",
"source_type": "psp_payment",
"source_id": "psp_7e4b2d9f1c3a8e5f",
"source_reference": null,
"reverses_allocation_id": null,
"reversed_by_allocation_id": null,
"status": "complete",
"created_at": "2026-06-17T14:30:00.000Z",
"updated_at": "2026-06-17T14:30:00.000Z",
"items": [
  {
    "object": "payment_allocation_item",
    "id": "pai_1a3f2b9c4d8e5f7a",
    "payment_allocation_id": "pal_3c8f1a9b2d4e7f6a",
    "target_type": "invoice",
    "target_id": "inv_4a7b2e9f1c3d8a5e",
    "amount": 120000,
    "currency": "eur",
    "created_at": "2026-06-17T14:30:00.000Z"
  }
]
}

Header fields

Lignes d'imputation

Each line (payment_allocation_item) describes allocation of a sub-amount from the source to one specific target document. An allocation may have several lines when the payment covers several invoices.

Lines are available through GET /v1/payment-allocations/:id (returned in the parent object) or through the GET /v1/payment-allocations?source_id=psp_….

Status

filter. The header status reflects whether the full source amount has been allocated.

Sources and targets

Source types

Target types

Side effects on targets

Creating an allocation immediately updates statuses of the relevant objects.

Creation

A payment_allocation is created through POST /v1/payment-allocations. The request describes the source and the list of allocation lines.

POST /v1/payment-allocations

{
"source_type": "psp_payment",
"source_id": "psp_7e4b2d9f1c3a8e5f",
"items": [
  {
    "target_type": "invoice",
    "target_id": "inv_4a7b2e9f1c3d8a5e",
    "amount": 120000,
    "currency": "eur"
  }
]
}

The platform validates that:

• The source is in an eligible status (see source table).
• All targets belong to the same merchant and use the same currency as the source.
• No target is over-allocated (total applied ≤ document amount).
• The sum of lines does not exceed the source amount.
• AR targets belong to the same buyer as the source when the source carries a buyer_id.

The read endpoints:

GET /v1/payment-allocations/:id
GET /v1/payment-allocations?source_type=psp_payment&source_id=psp_7e4b
GET /v1/payment-allocations?target_type=invoice&target_id=inv_4a7b

In processes

In practice, payment_allocation are not created manually — they are produced by reconciliation nodes.

The usual flow for a PSP receipt is: psp_payment.succeeded → propose_payment_allocation → reconcile_payment → payment_allocation created → invoices settled.

Correct an allocation

An allocation is an immutable fact: it is neither edited nor deleted. To correct it, reverse it. contre-passe.

POST /v1/payment-allocations/:id/reverse

The call creates a compensating allocation — the exact mirror of the named allocation, aggregated by target, with opposite amounts. No breakdown is chosen. All relevant statuses are recalculated: source payment, invoices, credit notes, refund rollups.

Correcting an amount therefore happens in two steps: reverse then a new allocation. Reversal frees source capacity, so reallocating is an ordinary operation — there is deliberately no reversal of a reversal.

Refus

• an allocation that has already been reversed;
• a compensating allocation, which itself cannot be reversed;

• the mirror created by POST /v1/payments/:id/reverse : it is imposed by the payment it reverses. A disputed SEPA debit returned to the buyer leaves nothing to allocate.

The call accepts an source_reference : replay after a timeout returns the existing compensation instead of creating a second one.

Identify the reversal. Negative amounts alone are not enough to know which allocation is undone when several target the same document. The relationship is therefore explicit in both directions:

{
"id": "pal_compensation",
"reverses_allocation_id": "pal_origine",
"reversed_by_allocation_id": null
}

reverses_allocation_id is populated on the compensation and points to the allocation being undone; reversed_by_allocation_id is populated on the original and points to its compensation. Both are null on an ordinary allocation, so a connector never needs to scan the list to determine whether an allocation was reversed.

Canceled or written-off documents. Reversing an allocation that targeted them lowers their settlement level but does not reopen never the document: reopening a written_off document would silently change the receivable based on a decision belonging to the merchant. The platform emits invoice.terminal_settlement_changed and lets a process or operator take the decision.

Events

Events payment_allocation.partial and payment_allocation.complete are mutually exclusive — only one is emitted per creation. Events on target documents (invoice.paid, invoice.partially_paid, payment.matched…) are emitted in the same transaction.