Draft documentation — API not yet rolled out. These documents are published in advance so you can prepare your integration. The contract and examples may change before release. Sandbox access will be provided separately; publication of these documents does not mean the API is available for testing or production use.
curl and jq. Replace the host placeholder with the sandbox API origin supplied by paywise and use your sandbox key. Keep keys out of source control and shared logs.
Confirm the expected company and environment: sandbox before continuing. Configure the company’s dunning flow in the portal before release; creating invoices can be tested first.
2. Create a debtor
Persist id in your integration. Do not blindly retry debtor creation: it is not idempotent. A customer-number lookup is available, but does not guarantee uniqueness or prevent concurrent duplicate creation. See retry rules.
3. Create a held invoice
Choose dates appropriate for your test: document_date must not be after due_date. Future-due invoices are accepted. Amounts must be positive.
A new invoice returns 201 and dunning_state: held. An eligible existing invoice with the same number returns 200; changed values in a repeated POST do not update it. Use PATCH /invoices/{id}/ to correct a held invoice.
4. Upload an optional PDF and wait for readiness
This preview supports one PDF per invoice. Repeating the upload replaces it; multiple-PDF support will be documented in a later contract update.
Use a valid synthetic invoice PDF. Do not set the multipart Content-Type yourself: curl adds the required boundary.
Read document.status: pending, ready, failed, or rejected. Poll with a delay until ready; stop and inspect failures rather than polling indefinitely. Uploading a supplied document is asynchronous: a successful upload does not mean it is usable yet. Release returns 409 document_not_ready until it is ready. For a failed/rejected document, upload replacement bytes while the invoice remains held. There is no retry endpoint. A replacement removes the old PDF; a failed replacement does not restore it.
If you do not supply a document, this readiness gate does not apply.
5. Release explicitly
The release action takes no request body, including no empty JSON object.
Release enrolls the invoice into the company default flow. Existing company/debtor pauses and activation state still apply; inspect the returned state rather than assuming immediate sending. The sandbox is a test environment, not a channel for live debtor contact.
6. Report a payment
This example reports full payment. Set value_date to the actual payment date; future payment dates are rejected. Use a stable reference identifying the payment.
Before Inkasso handover, covering the invoice amount marks it paid and stops dunning. After handover the collection case owns settlement. See the lifecycle rules for partial payments, retries, and terminal states.
