Allocate Account Payment Use Case

When a debtor pays a lump sum against the account rather than against one specific claim, use allocate_account_payment. Receive spreads the payment across the account's open claims for you, crediting one claim at a time, and reports exactly how it was distributed.

This is the claim-managed counterpart of match_account_payment. Use it when you own the claim lifecycle through create_claims / update_claims. If your account is ledger-managed (you push invoices and payments as Ledger Entries), use match_account_payment instead — the two integration modes must not be mixed for the same debt.

Use credit_claims instead when the payment is already attributed to a specific claim on your side. See the Register Payments Use Case.

Be sure to include the Authorization header with the Bearer authentication scheme and the access_token as the credentials. The access_token is provided by the authentication request.

Example

John Doe has two open claims on one account — an older one for 45.00 EUR and a newer one for 45.00 EUR — and pays 60.00 EUR in a single bank transfer.

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/allocate_account_payment HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

[
  {
    "accountReference": "ACCOUNT_REFERENCE_002",
    "currency": "EUR",
    "totalAmount": 6000,
    "providerName": "trustly",
    "trackingId": "TRX-20260814-001",
    "paymentReference": "PAYMENT-9931"
  }
]

The older claim is cleared and resolves automatically; the newer one is left with 30.00 EUR outstanding and stays active. No matchStrategy was sent, so the payment was allocated OLDEST_FIRST.

Choosing a strategy

matchStrategy is optional and defaults to OLDEST_FIRST.

Both strategies allocate to the oldest claim first, ordered by due date. The name FEES_FIRST_THEN_OLDEST does not mean fees are cleared across every claim before any principal — it selects the same claim order, and changes only what is paid down inside each claim:

Strategy	Claim order	Within a claim
OLDEST_FIRST (default)	Oldest due date first	Principal before fees
FEES_FIRST_THEN_OLDEST	Oldest due date first	Fees before principal

Pick the one that matches the waterfall your system of record already applies. If you settle fees before principal on the oldest outstanding obligation, that is FEES_FIRST_THEN_OLDEST.

What it does to the fee balance

A claim's remaining balance is amount + totalFees, so an allocated payment draws down both — you do not need a separate call to reduce fees, and you should not also send an update_claims with recomputed balances for the same payment. That would double-count.

Which bucket drains first is decided by matchStrategy. Taking one claim of 40.00 principal plus 10.00 fees, and paying 20.00 against it:

	OLDEST_FIRST	FEES_FIRST_THEN_OLDEST
Principal	40.00 → 20.00	40.00 → 30.00
Fees	10.00 → 10.00 (untouched)	10.00 → 0.00 (cleared first)

Same payment, same claim, different bucket. A claim resolves when the whole balance — principal and fees — reaches zero.

Reconciling the result

The HTTP response returns messageIds, not the distribution. The per-claim breakdown arrives on the event.accountPayment.allocated webhook:

{
  "messageType": "event.accountPayment.allocated.v1",
  "accountReference": "ACCOUNT_REFERENCE_002",
  "totalAmount": 6000,
  "currency": "EUR",
  "matchStrategy": "OLDEST_FIRST",
  "allocations": [
    { "claimRef": "CLAIM_REF_A", "amount": 4500, "claimResolved": true },
    { "claimRef": "CLAIM_REF_B", "amount": 1500, "claimResolved": false }
  ],
  "unallocatedRemainder": 0,
  "providerName": "trustly",
  "trackingId": "TRX-20260814-001",
  "paymentReference": "PAYMENT-9931",
  "correlationId": "1a83c2d6-e3b5-4503-b756-0bfaa596439e"
}

trackingId, paymentReference and meta are echoed back exactly as you sent them, and correlationId matches the messageId from the HTTP response — so you can tie the outcome to your own payment record from either end.

This one event is usually all you need to close claims on your side. Each entry carries claimResolved, so you learn which claims the payment closed without also subscribing to event.claim.resolved. Subscribe to the claim-level event as well only if you need to catch closures that did not come from an allocation.

See the Webhook Validation Use Case for verifying the signature, and the list of webhooks for the full event catalogue.

Notes

• Amounts are in cents. totalAmount is the lump payment to distribute, not a per-claim figure.
• Only active claims on the account, in the same currency as the payment, are eligible. Restrict further with context.productReference to allocate within a single product.
• Overpayment is safe. Each claim receives at most its remaining balance, no claim is driven negative, and anything left over is reported as unallocatedRemainder for you to handle.
• trackingId is a correlation handle, not an idempotency key. Sending the same payment twice allocates twice. De-duplicate before calling.
• If a credit fails part-way, event.accountPaymentAllocation.failed is emitted with the allocations that were already applied. Those are not rolled back, so a payment can be partly applied — reconcile on that event rather than assuming all-or-nothing.
• The request can include multiple accounts; each is processed and reported independently.

FAQ

• How can I get an Access Token? You can get a token using the Authentication Use Case
• Should I use allocate_account_payment or credit_claims? It depends on the shape of your payment events. If your payment arrives targeted at a specific obligation you have already identified, use credit_claims. If it arrives as a lump against the account and you want Receive to spread it, use allocate_account_payment. Both are supported; pick one per payment flow rather than mixing them for the same payment.
• Do I need to update the claim balances afterwards? No. The allocation credits the claims itself, including fees. Sending an update_claims with recomputed balances for the same payment would apply it twice.
• How do I know which claims were closed? From the allocations array on event.accountPayment.allocated — each entry has a claimResolved flag.
• What happens if the payment is larger than everything outstanding? Every claim is cleared and the excess is reported as unallocatedRemainder. Nothing is over-allocated and no balance goes negative.
• What if the account has claims in several currencies? Only claims matching the payment currency are eligible. Send one call per currency.

Related Pages

• Register Payments Use Case
• Payment Reversal Use Case
• Resolve Claims Use Case
• Webhook Validation Use Case