Debtor: who owes the money
A debtor is a reusable record for a person or organization, including their identity, addresses, and contact details. Create or reuse the debtor before creating the order, then pass its UUID asdebtor_id; pass other liable
parties as additional_debtor_ids. Accepted cases keep their own debtor
snapshot. Every debtor reads back
acting_as as consumer or business, never blank. The record is locked
(409) only while one of its orders still has a claim under review; a
finished order without claims does not lock it.
Debtors → — identity data,
reuse, editing restrictions, and validation rules.
Order: what you submit
An order groups the debtor, claims, and supporting evidence you submit to paywise. Chooseinvoice, rental, or titled, build an editable draft, then
finalize it for review. After acceptance, keep the order as the submission
record and follow the mandate for collection activity.
For submission, orders remain the finalization boundary: finalizing one order
validates and submits every claim currently assigned to it as one aggregate.
An order read embeds those claims as complete read projections, but the claim
UUID—not its position in that array—is its identity.
Orders → — order types,
construction, finalization, review, withdrawal, rejection, and acceptance.
Claim: what is owed
A claim represents one amount owed and its legal basis, such as an unpaid invoice, a rental month, or a titled amount. A claim always has a current order, but is a first-class resource of its own. The claim UUID is the durable correlation key: store it and use GET/v2/claims/{id}/ even if review moves
the claim to another order. Complete claim reads include the current
order_id, lifecycle status, debtor UUID projection, payments, subtype data,
and timestamps.
Claims → — receivable and
titled claims, amounts, dates, legal bases, charges, and evidence.
Mandate: the accepted collection case
A mandate is the read-only collection case that paywise creates or extends on acceptance. Follow it for the accepted claims, current balance, and case state. Several orders may contribute to one main case, with subcases for other liable parties. Mandates → — main cases, subcases, shared balances, states, and reference numbers.Statements: how collection activity reaches accounting
Statements are read-only settlement records for reconciling payouts, payments, charges, and closings. The standard multi-case statement is the default and covers a clearing run that can include several cases. Aktenabrechnungen settle one case and are produced only for customers configured for single-mandate statements. Historical published and cancelled single-mandate statements remain readable after configuration changes; synchronize that collection only where it is configured or historical records exist. Statements → — the two resources, financial details, files, cancellations, and synchronization.Supporting resources
During order review, find published questions with
GET
/v2/orders/{order_id}/requests-to-client/
and answer them using the order UUID, before a mandate exists.
One lifecycle example
Create claim C inline with draft order A, or stage it withPOST /v2/claims/ and order_id: A. Store C’s UUID. During review, paywise
may move C to order B; the client cannot change order_id itself. The same
GET /v2/claims/C/ now returns order_id: B, while C’s UUID, content, child
URLs, and your_reference stay unchanged. If B is accepted, C reads
status: "accepted" and exposes its mandate_id; later collection state
belongs to that mandate.
Existing records keep their UUIDs. Read a known claim directly at its stable
claim URL and continue from its current lifecycle state without recreating it.
The migration guide explains
field mappings and traffic cutover.
Every resource belongs to the selected company. A direct Case key selects its
company implicitly; a Partner key selects an entitled company with
X-On-Behalf-Of-Company. See
Authentication and environments
for access details.