Skip to main content
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

​
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: 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: 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:
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. 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 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. For request examples and reconciliation of your own reports, follow Report payments. For retry behavior, pagination, and public request boundaries, see Errors and safe retries, Pagination and synchronization, and Public limits.