Record Payments
Report payments collected from debtors.
Payment Flow
When recording a payment, specify who received it and how to allocate between creditor and your commission. Debitura handles revenue share calculations automatically.
Payment Recipients
| Recipient | When to Use | Commission |
|---|---|---|
CollectionPartner | Debtor paid you directly | Automatically marked paid |
Creditor | Debtor paid creditor directly | You specify: paid or unpaid |
Platform | Payment through Debitura | Automatically marked paid |
When the debtor pays the creditor directly, you must indicate whether the creditor has settled your commission. Update via the Portal when they do.
Unpaid Commission Follow-Up
When a payment leaves your commission unpaid (recipient Creditor, commission still unpaid) on a production case, Debitura automatically starts a follow-up so you chase the creditor for your success fee: it emails you the amount owed and creates an "invoice the client" task that later escalates to a chase task.
This runs by default on payments you record through the API. To suppress it for a given payment — for example when your system already tracks commission settlement out of band — set createUnpaidCommissionFollowUp: false on the request. The payment and payout are still recorded normally; only the email, task, and reminders are skipped.
Allocation Rules
Payouts must sum to the payment amount (within rounding tolerance). The system validates this before accepting the payment.
Accepted Date Window
A payment date must be on or after 2015-01-01 and on or before today plus one year, inclusive at both ends. A date outside that window returns 400 Bad Request with a ValidationError code and a message naming both the rejected date and the accepted window, rendered as yyyy-MM-dd. Nothing is persisted.
The same bounds apply to the edit path, so a correction cannot move a payment out of the window either — see Correct or Remove Payments.
In practice this catches serialisation mistakes rather than genuine dates. A two-digit year serialises as year 0026, and an unset date field serialises as 0001-01-01. Both used to be stored; both are now rejected at the boundary.
Retrying Safely
If a request times out or your client retries automatically, attach an Idempotency-Key header — a repeat with the same key replays the original response instead of recording a second payment. See Idempotency for the full semantics.
Closing with Payment
Set closeCase: true on a payment and the case is automatically closed as Paid only if the payment fully settles the outstanding balance. If the payment is less than the outstanding amount, the payment is still recorded and the case is left open — closeCase: true is simply ignored for that partial payment (no error). This means you can safely send closeCase: true on every payment and let the final, balance-settling payment trigger the close.
To close a case with partial recovery (when the debtor will not pay the full balance), use the separate POST /cases/{id}/close endpoint with closeCode: "PartiallyPaid" instead.
For endpoint details and all fields, see Create Payment. To fix or reverse a payment you already recorded, see Correct or Remove Payments.