---
title: "Create a payment on a case"
method: POST
path: "/cases/{id}/payments"
tags: ["Cases"]
---

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

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- DebituraWebExternalApiContractsV1PaymentsCreatePaymentRequest — Request to create a payment on a case. **Currency:** Payment must be in the same currency as the invoice. Currency is automatically determined from the case and cannot be specified in the request.
  - `date` string, date-time, required — Payment date (when payment was received). Provide date only without time component.
  - `paymentAmount` number, double, required — Total payment amount received. When both PayoutCreditor and PayoutCollectionPartner are supplied they must sum to this amount. When both are omitted, the split is computed server-side from the case's pricing terms.
  - `payoutCreditor` number, double, nullable — Amount to be paid out to creditor. **Optional — omit by default.** Normal usage is to leave this (and PayoutCollectionPartner) unset: the split is then computed server-side from the case's pricing terms (success fee), which is correct for almost every integration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a negotiated split where the collection partner already holds funds) — most callers should never need it. When supplied, PayoutCollectionPartner must also be supplied and the two must sum to PaymentAmount. A zero value here (entire payment routed to the partner), or an explicit split supplied on a case that already has no outstanding balance, is accepted but surfaced as a warning in the response (`CreatePaymentResponse.Warnings`) rather than rejected — review these warnings, as they are signs of a misconfigured or duplicate payment.
  - `payoutCollectionPartner` number, double, nullable — Amount to be kept by collection partner (commission). **Optional — omit by default.** Normal usage is to leave this (and PayoutCreditor) unset: the split is then computed server-side from the case's pricing terms (success fee), which is correct for almost every integration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a negotiated split where the collection partner already holds funds) — most callers should never need it. When supplied, PayoutCreditor must also be supplied and the two must sum to PaymentAmount. See PayoutCreditor (above) for the soft-guard warnings this can trigger.
  - `paymentRecipient` string, required — Who received the payment. **Valid values:** - **Creditor**: Payment was received by the creditor (client). When used, you must also specify CommissionPaymentStatus. - **Platform**: Payment was received by Debitura platform. Commission is automatically marked as paid. - **CollectionPartner**: Payment was received by the collection partner. Commission is automatically marked as paid.
  - `commissionPaymentStatus` string, nullable — Commission payment status. **Required only if PaymentRecipient is Creditor.** When PaymentRecipient is CollectionPartner or Platform, this field is ignored and commission is automatically marked as Paid. **Valid values:** - **Paid**: Commission has been paid to collection partner - **Unpaid**: Commission has not yet been paid to collection partner
  - `closeCase` boolean
  - `createUnpaidCommissionFollowUp` boolean — Whether to run the unpaid-commission follow-up chain when this payment leaves the collection partner's commission Unpaid (PaymentRecipient = Creditor, CommissionPaymentStatus = Unpaid). The chain is: stamp the payout reminder date, email the partner, and create the UnpaidCommissionInvoiceClient follow-up task — which the reminder robot then drives. Defaults to `true`, preserving the standard API / UI behaviour. Set to `false` to opt this source out of the entire chain (no stamp, email, task, reminders or escalation); the Payment and Payout are still created normally. Used by ingestion partners (e.g. ASTOP) that already report commission settlement out of band and must not trigger the chase.

## Response `200`

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

- DebituraWebExternalApiContractsV1PaymentsCreatePaymentResponse — Response after creating a payment
  - `paymentId` string, uuid
  - `caseReference` string, nullable, required
  - `date` string, date-time
  - `paymentAmount` number, double
  - `payoutCreditor` number, double
  - `payoutCollectionPartner` number, double
  - `paymentRecipient` string, nullable, required
  - `commissionPaymentStatus` string, nullable, required
  - `closeCase` boolean
  - `caseClosed` boolean
  - `closeCode` string, nullable
  - `remainingAmount` number, double
  - `clientCommissionInvoice` DebituraDomainModelPartnerCommissionInvoicesPartnerCommissionInvoiceActionDescriptorDTO
    - `payoutId` string, uuid
    - `paymentId` string, uuid
    - `caseId` string, uuid
    - `caseReference` string, nullable
    - `clientId` string, uuid
    - `clientName` string, nullable
    - `flowOwner` 1 | 2
    - `commissionStatus` string, nullable
    - `paymentRecipient` string, nullable
    - `lockedAmount` number, double
    - `currencyCode` string, nullable
    - `currentInvoiceId` string, uuid, nullable
    - `currentInvoiceNumber` string, nullable
    - `origin` 1 | 2
    - `documentState` 1 | 2 | 3 | 4
    - `deliveryState` 1 | 2 | 3
    - `settlementState` 1 | 2
    - `issueDate` string, date-time, nullable
    - `dueDate` string, date-time, nullable
    - `mayStart` boolean
    - `ineligibilityCode` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21
    - `allowedActions` DebituraDomainModelPartnerCommissionInvoicesPartnerCommissionInvoiceAllowedAction[], nullable
  - `warnings` string[], nullable — Non-blocking warnings about this payment. Always present (empty when there is nothing to flag). Currently populated only when an explicit PayoutCreditor/PayoutCollectionPartner override was supplied and (a) it allocates zero to the creditor, or (b) the case already had no outstanding balance before this payment — both are signs of a misconfigured or duplicate payment. The payment is still recorded; these are advisory only, not errors. Review and resolve out of band if unexpected (e.g. via the case's Payments view in the Partner Portal, or by contacting Debitura support).

## Other responses

- `400` — Invalid request (validation errors)
- `404` — Case not found or not assigned to you
- `409` — A request with this Idempotency-Key is already in progress. Retry after the indicated delay.
- `422` — The Idempotency-Key has already been used with a different request body.
- `500` — Server error occurred

---

[API](https://skmtc.net/debitura/apis/debitura-collection-partner-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-collection-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-collection-partner-api/revisions/40bd25a4edaf/schema)