db09d0fd5c94
Create a payment on a case
Records a payment received for a collection case.
Use Case: Use this endpoint when you receive a payment from the debtor. Provide the payment amount and, in the normal case, nothing else for the split — omit both PayoutCreditor and PayoutCollectionPartner and Debitura computes the creditor/partner split server-side from the case's pricing terms (success fee). This is the default and recommended usage for almost every integration.
Advanced override — PayoutCreditor / PayoutCollectionPartner: Supplying both fields lets you dictate the split explicitly instead of using the computed one. This is an advanced, opt-in override for legitimate edge cases (e.g. a negotiated split where the collection partner already holds funds) — it is not the normal path and most integrations should never set it. When supplied:
- Both fields are required together, and MUST sum to PaymentAmount (within 0.01 tolerance).
- The response's Warnings array surfaces (without blocking the request) if the split allocates zero to the creditor, or if the case had no outstanding balance before this payment — both are signs of a misconfigured or duplicate payment and should be reviewed.
Currency: Payment must be in the same currency as the invoice. The currency is automatically determined from the case.
PaymentRecipient Options:
- Creditor - Payment was received by the creditor (your client). When using this option, you MUST also specify CommissionPaymentStatus.
- CollectionPartner - Payment was received by you (the collection partner). Commission is automatically marked as Paid since you already have the funds.
CommissionPaymentStatus: This field tracks whether the collection partner's commission has been paid. It's only required when PaymentRecipient is 'Creditor'.
- Paid - The creditor has already paid your commission
- Unpaid - The creditor has not yet paid your commission
Note: When PaymentRecipient is 'CollectionPartner', this field is automatically set to 'Paid' since you already have the money.
Critical Validation:
- PayoutCreditor and PayoutCollectionPartner are optional but must be supplied together. When supplied, they MUST equal PaymentAmount (within 0.01 tolerance). When omitted (recommended), the split is computed from the case terms.
- An explicit split that zeroes the creditor, or that is supplied on an already-settled (zero-remainder) case, is accepted but surfaced as a warning in the response — not blocked.
- CommissionPaymentStatus is required only if PaymentRecipient is 'Creditor'
Payment Flow:
-
Full Payment (payment >= outstanding):
- If CloseCase=true → closes case with 'Paid' status
- If CloseCase=false → case remains open
-
Partial Payment (payment < outstanding):
- The payment is recorded regardless of CloseCase. The case is NOT closed (CloseCase is honoured only when the payment fully settles the balance) and no error is returned.
- To close on a partial payment, use the close endpoint with the PartiallyPaid close code.
Path parameters
Headers
Optional idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with Type: "IdempotencyConflict". Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.
Request body
Example request
{
"date": "2026-07-31",
"paymentAmount": 5000,
"payoutCreditor": 4000,
"payoutCollectionPartner": 1000,
"paymentRecipient": "Creditor",
"commissionPaymentStatus": "Paid",
"closeCase": false
}Response
Payment created successfully (or duplicate Idempotency-Key — the original response is replayed). Check the Warnings array for non-blocking advisory notices (e.g. about an explicit payout-split override).