Payments
A payment is money arriving against an invoice. It can come through a payment gateway, from a customer's wallet, or by hand when somebody pays by bank transfer.
Payments are separate from invoices on purpose. One invoice can be settled by
several payments, a single payment can be split across invoices, and a payment
can arrive long before or after the document it settles. What connects them is
the invoice's balance, which is the number that decides whether it is paid.
Three ways money arrives
Through a gateway
The customer pays by card or direct debit and the provider tells Kontier what happened. Stripe and GoCardless are supported. The payment appears with the provider's reference and moves through its own states as the provider confirms or fails it.
This is the path you want for self-serve.
From a wallet
The customer has a prepaid balance and the invoice draws on it. Nothing leaves a bank; the money was already there. See Wallets for holds, top-ups and how a balance is spent.
Recorded by hand
A bank transfer, a cheque, a write-off. Nothing comes back through a provider, so somebody records it against the invoice. This is the path most B2B invoices actually take, and it is the one people forget to document.
Amounts are major units, as strings
amount on a manual payment is "49.99", not 4999. The optional currency
field is an echo-guard: when you send it, it must equal the invoice's currency,
which is a cheap way to catch a payment being applied to the wrong invoice.
Record one in the dashboard
-
Open the invoice
Payments attach to an invoice, not to a customer, so start from Billing and open the one being settled.
-
Record the payment
Use Record Payment. Enter the amount that actually arrived, the source it arrived through, and the date it landed.
Partial payments are fine. The invoice keeps a balance and stays unpaid until the balance reaches zero.
-
Check it in the ledger
Ledger → Payments is the cross-customer view: everything that arrived, in date order, filterable by time range and direction.
Record one over the API
amount and source are required; everything else is optional. source
identifies how the money arrived and is a free-form string, so agree a convention
across your organisation and stick to it.
Refunds go back the way they came
POST /v1/invoices/{id}/refund returns money through the original provider. Its
amount is in major units, the same as recording a payment.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Record Payment | POST /invoices/{id}/record-payment |
| Amount on the form | amount, major units, a string |
| Source | source, a free-form string |
| Reference | reference, your bank or provider reference |
| Ledger → Payments | GET /invoices/{id}/payments per invoice |
| Ledger → Transactions | every money movement, not only payments |
| Balance on the invoice | what is still owed after all payments |
Where payments go next
- The invoice settles itself. When the balance reaches zero the invoice
becomes
paid; no separate step. - A failure starts dunning on the retry policy the plan carries.
- Overpayment becomes wallet credit rather than a negative balance.
Next step
Continue to Wallets for prepaid balances, holds and top-ups.
Reference
| Topic | When you need it |
|---|---|
| Wallets | Prepaid balance, holds and auto-topup |
| Dunning | What happens when a payment fails |
| Credit notes | Reducing what is owed rather than refunding it |
| Payment gateways | Connecting Stripe or GoCardless |
| Payments API | Payment retrieval and the per-invoice payment list |