> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Report payments you receive directly from debtors, and follow payments received by paywise through mandate balances, status updates, and statements.

The **payment** resource records payments that you, the client, report to
paywise. Use it when a debtor pays you directly so paywise can account for the
money you have already received when reviewing the claim or collecting the
remaining debt.

Payments a debtor makes to paywise are published through the mandate's balance
and status updates and ultimately included in a statement. They do not appear
as payment resources in `GET /v2/payments/`.

## When to use the payment resource

| Who received the money? | What your integration does |
| - | - |
| You, the client | Report the payment against the claim or mandate. Read the resulting payment resource to reconcile your report. |
| paywise | Follow the mandate's balance and published status updates, then reconcile the settlement through [Statements](/api-docs/case-management-api/concepts/statements). No client payment report is needed. |

## Partial payments before handover (Teilzahlungen)

Recording **partial payments you received before handing the case over to
paywise** is an intended part of creating and submitting an order. Include
these receipts when preparing the claim so paywise knows what has already
been paid and what remains to be collected.

For an invoice claim, keep the original invoice amount in `principal_amount`
and record each partial payment separately in `payments`. For example, if a
€1,000 invoice has already been paid in part by €200, submit the original
€1,000 principal and a €200 payment. With no additional charges, the open
claim is €800. Do not reduce the principal to €800 and also report the €200
payment, as that would deduct the receipt twice.

You can include these payments in the claim's inline `payments[]` when
creating the order or claim, or add them through the claim-scoped payment
endpoint while preparing the draft for submission. Use the date the money
was credited to you as `value_date`.

If the debtor pays you again after handover, route the report by lifecycle.
Before acceptance, report against the claim. After acceptance, report against the exact mandate or subcase.

## Where to report a payment

Address a claim payment by the stable claim UUID; its current order is not part
of the URL:

| Lifecycle stage | Endpoint | Behavior |
| - | - | - |
| Draft order | `POST /v2/claims/{claim_id}/payments/` | Record partial payments received before handover as a fact on the claim. You can delete the report while the order is a draft. |
| Order under review (`submitted` or `awaiting_client_response`) | `POST /v2/claims/{claim_id}/payments/` | Records the payment on the exact claim for the review team. The report is immutable. |
| Accepted case or subcase | `POST /v2/mandates/{mandate_id}/payments/` | Recommended after acceptance. Target the exact main mandate or subcase; the report is immediately immutable. |
| Accepted claim compatibility route | `POST /v2/claims/{claim_id}/payments/` | Still accepted and delegates to accepted-case reporting while preserving exact claim attribution. The report is immediately immutable. |

The accepted-claim route remains supported for compatibility and delegates to
the same reporting seam as the mandate route. It preserves the exact claim
target and applies the reporting effect to that claim's attached mandate,
including its subcase when applicable; it never selects a sibling claim.
Choose one route and one idempotency key for each payment; do not report the
same receipt through both.

Every claim payment route — `GET` and `POST /v2/claims/{claim_id}/payments/`
and `DELETE /v2/claims/{claim_id}/payments/{id}/` — requires the payment
permissions in every lifecycle state: `case:payments:read` to list and
`case:payments:write` to report or delete. A key without them is
`403 permission_denied`. Inline `payments[]` on `POST /v2/orders/` and
`POST /v2/claims/` are the claim's opening balance and stay under
`case:orders:write`. On an expired draft, reporting and deleting answer
`409 order_expired`.

The public input contains an optional `your_reference` and `metadata`, a
positive EUR `amount`, and a non-future `value_date`. Zero, negative, and future values
return `400`. Payment method is not part of the public input.

### Overpayment and duplicates

The two routes guard differently, because a draft claim still has a known open
value while an accepted case is reconciled by paywise:

| Route | Overpayment | Duplicate |
| - | - | - |
| Draft claim (`POST /v2/claims/{claim_id}/payments/`, and inline `payments[]` on claim create) | Rejected: the sum of payments may not exceed `principal_amount` plus `additional_charges` (`400`, `amount.value` / `overpayment`). A `value_date` before the claim's `document_date` is `400` as well. | Same `amount`, `value_date`, and `your_reference` on the same claim is `409 duplicate_payment` (`400 payments` / `duplicate_payment` inline). |
| Accepted claim or case (`POST /v2/claims/{claim_id}/payments/` or `POST /v2/mandates/{mandate_id}/payments/`) | Accepted; paywise reconciles any surplus. | A report for the same case, amount, and `value_date` within 24 hours of an existing report is `409 duplicate_payment_report` with `existing_payment_id` and `existing_payment` (`amount`, `value_date`, `created_at`). The window covers that one mandate: a report on the main case and the same payment on one of its subcases are two separate reports. A repeat with the same `your_reference` is a duplicate too; to recover a lost response, repeat the original request with its `Idempotency-Key`, which replays the `201`. |

There is no way to force a second, genuine payment with identical amount and
value date through the API within that 24-hour window; contact paywise
support in that case.

A closed case takes no further reports: when the mandate's
`state.processing.code` is `ended`, `canceled_by_client`, or
`canceled_by_service_provider`, or the mandate's `archived` flag is `true`, `POST /v2/mandates/{mandate_id}/payments/` answers `409 conflict` with
`Cannot report a payment on a closed mandate.` Contact paywise if money
arrives after closure.

## Payment metadata

Payment creation accepts an optional `metadata` array of `{type, value}`
objects, including inline `payments[]` on a new claim, claim-scoped reports,
and mandate-scoped reports. Use the payment-specific types, for example:

```json theme={null}
{
  "metadata": [
    {"type": "transaction:reference", "value": "BANK-TX-0042"}
  ]
}
```

The array retains duplicate types. Payment reads expose the stored metadata,
including values on existing v1 payment records, with the same payment UUID.
Do not report an old receipt again to make its metadata available. Payments
do not accept `events`, and there is no metadata update endpoint.

## Reading and correcting your reports

Use `GET /v2/payments/` and `GET /v2/payments/{id}/` to read reported payments
and match them to your records using `id` and `your_reference`. These
read-only endpoints expose client payment reports, not a ledger of all money
received during collection. Reports that paywise discarded during its payment
review are omitted from both, and reading one answers `404`.

A report on a draft order claim can be deleted through the claim-scoped
endpoint. After finalization, and for reports to accepted mandates or
subcases, the report is immutable. There is no payment reversal operation;
contact paywise to correct an incorrect finalized report.

The `payment.reported` event concerns a finalized client payment report.
Draft reports are silent. Reporting against an accepted claim, mandate, or
subcase emits this event; it does not announce money received by paywise.

## Following payments received by paywise

When a debtor pays paywise, follow the case and its settlement:

1. **Balance update:** `mandate.balance_updated` tells you the legal balance
   changed. Fetch the mandate and read its current `legal_balance`; the event
   itself contains no amounts. Costs can also trigger a balance update, so
   the event alone does not identify a payment.
2. **Status update:** Read the published payment update in the mandate's
   [history](/api-docs/case-management-api/workflows/follow-a-case). Published
   updates explain the case activity; the mandate's `state` holds its current
   legal, processing, and payment state.
3. **Statement:** Reconcile the payment and its allocation when the
   [statement](/api-docs/case-management-api/concepts/statements) becomes
   available. Statements provide the settlement data for your accounting.

In the sandbox, report payments you receive through the same payment
endpoints. To simulate a debtor paying paywise, use *Zahlung des Schuldners
an paywise* in the sandbox portal's
[sandbox drawer](/api-docs/case-management-api/concepts/sandbox#sandbox-drawer).

For request examples and reconciliation of your own reports, follow
[Report payments](/api-docs/case-management-api/workflows/report-payments).

For retry behavior, pagination, and public request boundaries, see
[Errors and safe retries](/api-docs/essentials/errors-and-safe-retries),
[Pagination and synchronization](/api-docs/essentials/pagination-and-synchronization),
and [Public limits](/api-docs/essentials/limits).

## Related reference

* [POST `/v2/claims/{claim_id}/payments/`](/api-docs/case-management-api/reference/claims/create-claim-payment)
* [DELETE `/v2/claims/{claim_id}/payments/{id}/`](/api-docs/case-management-api/reference/claims/delete-claim-payment)
* [POST `/v2/mandates/{mandate_id}/payments/`](/api-docs/case-management-api/reference/mandates/create-mandate-payment)
* [GET `/v2/payments/`](/api-docs/case-management-api/reference/payments/list-payments)
* [GET `/v2/payments/{id}/`](/api-docs/case-management-api/reference/payments/get-payment)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.