If a payment was made on your side, pass it on to the portal. Preferably use the payment endpoint: you send the amount and the portal updates the collection order, the messages and the paylinks. If you do not know the collection order number, use your customer number and invoice number.
Which option do you choose?
| Situation | Use |
|---|---|
You stored the collection_order_id of the collection order |
POST /v3/collection_orders/{id}/payments |
| You know the customer number and the payment reference | POST /v3/debtors/{debtor_number}/collection_orders/payments?payment_reference=… |
| You know the customer number and the invoice number | POST /v3/debtors/{debtor_number}/collection_orders/payments?invoice_number=… |
| You synchronise your outstanding items | The synchronisation lowers the amount automatically. See Synchronising outstanding items through the API |
| The whole collection order has been paid and you do not want to pass on an amount | Set the status to paid with PATCH /v3/collection_orders/{id} |
Advice: use the payment endpoint with customer number and invoice number. Every system has these, and you do not need to store collection order numbers. The payment endpoint is simpler than processing payments by changing invoice lines with a PATCH.
How to do it
- Choose the call from the table above.
- Send the amount in cents (
amount) and the kind of line (type) in the body:paymentfor a payment orcreditfor a credit note. Withouttypeit is a payment. - Optionally add
round: the remaining amount in cents you want to write off. If an amount up to that value remains after the payment, the portal writes it off as a payment difference and the collection order becomes Paid. - Read the response: the number of updated collection orders and paylinks.
Example: 25.40 euros is outstanding and the customer pays 25.00 euros. With round set to 100 (1 euro), the portal writes off the 40 cents as a line of type payment difference. The collection order becomes Paid and you can see the difference in your reports.
Good to know
- By customer number, the portal books the payment on every running collection order of that customer that contains the payment reference or invoice number. If the same invoice number is in an invoice collection order and a reminder collection order, both are updated.
- Collection orders that are already Paid are skipped. If the portal finds no collection order, you still get a successful response with 0 updated collection orders.
- When the collection order is fully paid, the portal closes it and also closes its open messages and paylinks.