Skip to main content

Create a payment on a case

POST 
/cases/:id/payments

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:

  1. Full Payment (payment >= outstanding):

    • If CloseCase=true → closes case with 'Paid' status
    • If CloseCase=false → case remains open

  2. 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.

Request​

Responses​

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).