This guide is for shop and finance staff connecting Kustom to Fortnox through Junipeer. It covers what the integration does, the connection, how payouts are booked and matched, and what to check before going live.
Work through Connecting payment services to Junipeer first. It covers the steps every payment provider shares. This guide covers what is specific to Kustom and Fortnox.
What the integration does
The Kustom ↔ Fortnox integration has one flow:
Flow | What it does |
|---|---|
Export Payouts to Fortnox | Reads Kustom settlements (payouts), matches each transaction to its Fortnox invoice, marks the invoice as paid and books the fees. |
It does not create orders, invoices or credit invoices. The invoices must already be in Fortnox — usually created by your webshop integration — and must carry a reference that Junipeer can match.
Before you start
Fortnox is prepared: an integration user, currencies, and a payment method for Kustom. See Prepare Fortnox for integration.
You have Kustom settlements API credentials. Ask your Kustom contact if you don't have them.
You know which Fortnox accounts to use for fees, VAT on fees and rounding. Ask your bookkeeper.
Connecting Kustom and Fortnox
In the Junipeer app, go to Get Started → Connect Systems. Connect Fortnox by clicking the Fortnox button and logging in. Then fill in the Kustom fields:
Field | What to enter |
|---|---|
Kustom settlements API Url | The address of Kustom's settlements API. Usually |
Kustom API user/id | The username or ID for the Kustom settlements API. |
Kustom API password or secret | The password for the Kustom settlements API. It is stored as a secret. |
All three are required. When both systems show a green checkmark, you are ready to configure.
Booking settings for payouts
Open Configure → Settings and find Booking Accounting Settings for Settlements. Add Kustom as the payment provider and fill in the accounts below. This decides how each payout is booked in Fortnox. Without it, payouts will not book correctly.
The account numbers below are the usual Swedish examples shown in the app. Confirm every account with your bookkeeper before you save — your chart of accounts may differ.
Setting | What to enter |
|---|---|
Payment Method | The payment method (betalsätt) in Fortnox for Kustom. Required. The list is read from Fortnox — if Kustom is missing, add it in Fortnox first. |
Map Currency with Mode of Payment (if different than (default) Payment Method above) | Optional (advanced). Use a different Fortnox payment method for payouts in a certain currency, for example EUR payouts that go to a separate EUR account. Currencies you don't map use the Payment Method above. |
Account Number Bank Costs | The account for Kustom's fee, excluding tax. Required. The app suggests 6570. |
VAT account for provider fees | Where VAT on Kustom's fees is booked. This is input VAT you can deduct. Required. Only used when Kustom reports VAT on a fee. The app suggests 2641 in Sweden. |
Account Number for Incoming Tax | Only used when the payout isn't from Sweden. Leave empty for Swedish payments. |
Account Number for Penny rounding | Small differences between the invoice amount and the paid amount. Required. The app suggests 3740. |
Account Number for Currency Profit | Optional. Small differences caused by currency conversion that give a profit. The app suggests 3960. Leave empty to use the penny rounding account for both profit and loss. |
Account Number for Currency Loss | Optional. The same for a loss. The app suggests 7960. |
Click the ? next to each setting in the app for more details.
How payouts are matched to invoices
How a payout is reconciled
From the customer's payment to the right account in your ERP.
Matching relies on the reference saved on the order or invoice when the order was synced. Without the reference the payout cannot be matched.
When Kustom pays out, Junipeer reads the payout and finds the Fortnox invoice for each transaction. Matched invoices are marked as paid, and the fees are booked to the accounts you set above.
To find the right invoice, Junipeer takes a reference from the payout and searches for it in a field on the Fortnox invoice (or order). You decide where it looks under General Settings:
Setting | What it does |
|---|---|
Payout Reference Field | Required. The Fortnox field that holds the reference, usually the shop order ID or the payment order ID. In many setups this is ExternalInvoiceReference1. Open a recent invoice in Fortnox to see which field holds the order reference. |
Fallback Payout Reference Field | Optional (advanced). A second field to try if the reference isn't found in the first one, for example ExternalInvoiceReference2. |
Use Payment ID as Payout Reference | Optional (advanced). By default Junipeer searches for the merchant reference (usually your order number). Choose this to search for the payment ID instead (usually the Kustom order ID), or to try one and then the other. Pick what is actually stored in your Payout Reference Field. |
Search for the Payout Reference on the Order | Optional (advanced). Yes searches on the Fortnox order and then finds its invoice. No searches directly on the invoice. |
Book keep invoice payment | Optional (advanced), default Yes. Books (bokför) the payments Junipeer creates from payouts. Keep it on Yes if invoices should be marked as paid automatically. |
Read more in Matching payout references in Fortnox and Payout reconciliation.
Going live
Payouts are usually not something you can test in advance. The scheduled run must run in production, and you should check the results after each run.
Fortnox is connected and prepared, including a payment method for Kustom.
The three Kustom fields are filled in and the connection shows a green checkmark.
Export Payouts to Fortnox is turned on.
Booking Accounting Settings for Settlements is filled in for Kustom, and your bookkeeper has confirmed the accounts.
Payout Reference Field matches the field your webshop integration writes the order reference to. Check one recent Fortnox invoice.
Schedule Export Payouts to Fortnox. Payouts are usually run once a day, for example at 23:00.
Contact your Junipeer onboarding contact to review the setup before you go live.
After the first payouts, check in Fortnox that invoices are marked as paid and that fees are booked to the right accounts.
Common pitfalls
Connection fails. Check the Kustom settlements API Url first, then the user and password. The credentials are for Kustom's settlements API.
Invoices not created by Junipeer. If invoices reach Fortnox through another tool, they may not have a reference Junipeer can match.
"No invoice found" on a payout. Usually the Payout Reference Field points to a field that is empty or holds a different reference than the payout carries. Open the failing task in the logs, note the reference, and check which Fortnox field holds it. The invoice may also not exist yet, if the payout arrived before the order was synced.
The payment method is missing from the list. Create it in Fortnox first, then click Clear Cache on the settings page.
Payment date before invoice date. Fortnox can reject a payment dated before the invoice. See Error codes.
Invoices in another currency than the payout. This gives "Unsupported currency combination". If you sell in several currencies, contact Junipeer support to set it up.
New payment provider switched on in the webshop before Junipeer was configured. Payouts for those early orders can get wrong references. Configure Junipeer first. If it already happened, contact support.