---
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`

## Request

- Base URL: `https://collectionpartner-api.debitura.com`
- URL: `https://collectionpartner-api.debitura.com/cases/{id}/payments`
- Auth: API key in header `XApiKey`

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: Request to close the case as "Paid" if this payment fully settles the outstanding balance (default: false). If true and payment >= invoice remainder, the case is closed with "Paid" status. If true and payment < invoice remainder, the payment is still recorded but the case is left open (no error). To close a case with a partial payment, use the close endpoint with the PartiallyPaid close code.

## 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` DebituraWebExternalApiContractsV1PaymentsClientCommissionInvoiceDto: Whether and how a commission invoice can be raised for this payment's payout, and the state of the current one if it exists.
    - `payoutId` string, uuid
    - `paymentId` string, uuid
    - `caseId` string, uuid
    - `caseReference` string, nullable
    - `clientId` string, uuid
    - `clientName` string, nullable
    - `flowOwner` 'ManualSettlement' | 'CommissionInvoice': Who settles this payout's commission. ManualSettlement: settled outside commission invoicing. CommissionInvoice: settled through a commission invoice.
    - `commissionStatus` string, nullable
    - `paymentRecipient` string, nullable
    - `recordedCommissionAmount` number, double: Commission recorded in Debitura for this payout.
    - `commissionOutstandingAmount` number, double, nullable: Remaining commission after bank reconciliation; null for an ordinary source.
    - `lockedAmount` number, double: Deprecated compatibility name for RecordedCommissionAmount. Existing Collection Partner API integrations may still read this member.
    - `currencyCode` string, nullable
    - `currentInvoiceId` string, uuid, nullable
    - `currentInvoiceNumber` string, nullable
    - `origin` 'Generated' | 'Uploaded' | 'null', nullable: How the current invoice document was created.
    - `documentState` 'Draft' | 'Issued' | 'Voided' | 'Superseded' | 'null', nullable: The state of the current invoice document.
    - `deliveryState` 'NotSent' | 'Sent' | 'Failed' | 'null', nullable: Whether the current invoice has been sent to the client.
    - `settlementState` 'Unpaid' | 'Paid' | 'Reconciled' | 'PartiallyReconciled' | 'null', nullable: Whether the current invoice has been paid.
    - `issueDate` string, date-time, nullable
    - `dueDate` string, date-time, nullable
    - `mayStart` boolean
    - `ineligibilityCode` 'NotEnabled' | 'HandledOutsideInvoicing' | 'NoClientRelationship' | 'PaymentNotToClient' | 'CommissionAlreadySettled' | 'NotEligible' | 'null', nullable: Why a commission invoice cannot be raised for this payout. NotEnabled: commission invoicing is not enabled. HandledOutsideInvoicing: this payout's commission is settled outside commission invoicing. NoClientRelationship: no commission-invoicing relationship exists with this client. PaymentNotToClient: the payment was not made to the client. CommissionAlreadySettled: the commission is already paid or credited. NotEligible: not eligible for another reason.
    - `allowedActions` DebituraWebExternalApiContractsV1PaymentsClientCommissionInvoiceAllowedAction[], 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

## Changes

- **2026-10-21** `a7cf0ff022b6`: 4 warning
  - removed the request property `createUnpaidCommissionFollowUp` (media type: application/json-patch+json)
  - removed the request property `createUnpaidCommissionFollowUp` (media type: application/json)
  - removed the request property `createUnpaidCommissionFollowUp` (media type: text/json)
  - removed the request property `createUnpaidCommissionFollowUp` (media type: application/*+json)
- **2026-10-12** `f8145be751d0`: 15 breaking, 15 warning
  - the response property `clientCommissionInvoice/deliveryState` became nullable for the status `200` (media type: text/plain)
  - the response property `clientCommissionInvoice/deliveryState` became nullable for the status `200` (media type: application/json)
  - the response property `clientCommissionInvoice/deliveryState` became nullable for the status `200` (media type: text/json)
  - the response property `clientCommissionInvoice/documentState` became nullable for the status `200` (media type: text/plain)
  - …26 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/changes/cases/:id/payments/post.md)

---

[API](https://skmtc.dev/debitura/apis/debitura-collection-partner-api.md) - [All operations](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/revisions/a7cf0ff022b6?raw)