For organization admins
Set up an integration
Connecting another system to Flux takes a few minutes in the Flux app. You create an API key, register where events go, and give the developer a few ids. No code is needed.
You need to be an organization admin. Everything a key does stays inside your organization, and invoices and customers it creates are recorded as created by you, the admin who made the key. They go through your normal approval workflow.
1. Create an API key#
- Open Settings → Developers → API keys and create a key.
- Name it after the system that will use it, such as “Maxella workspace billing”.
- Choose its scopes. Give only what the integration needs (below).
- Copy the key. It's shown once: Flux keeps only a hash, so a lost key can't be recovered. Create a new one instead.
| The integration needs to | Give the key |
|---|---|
| Keep customers in sync | customers:write |
| Raise invoices | invoices:write, plus customers:read to look customers up |
| Show a billing page: totals, invoices, download and pay buttons | customers:read, invoices:read |
| Take payments online | payments:write |
| Manage its own webhooks | webhooks:manage |
| A full billing integration | customers:write, invoices:write, payments:write, webhooks:manage |
A :write scope includes the matching :read scope. The key list shows when each key was last used.
2. Register a webhook#
Webhooks tell the other system when something changes in Flux, such as an invoice being approved or paid.
- In Settings → Developers → Webhooks, add the endpoint URL the developer gives you. It must start with
https://. - Choose the events, or all events.
- Copy the signing secret (shown once) and pass it to the developer the same way as the key.
- Press Test to send a test event, and check the delivery log shows it as delivered.
The developer can also register endpoints themselves with the webhooks:manage scope. If an endpoint fails 50 times in a row, Flux switches it off and emails whoever registered it and your organization's support email. Switch it back on from the same page once it's fixed.
3. Online payments#
Online payment uses Paystack. In Settings → Payments you choose how your organization collects: through Flux's Paystack account, or your own. You also set up the settlement accounts payments go to. If you use your own Paystack account, add the webhook URL shown there to your Paystack dashboard.
The integration doesn't configure any of this. Whether an invoice can be paid online is decided when it's approved.
4. Invoice reminders (optional)#
Settings → Invoice reminders turns on due-soon and overdue emails and renewal notices. It also turns on the invoice.due_soon, invoice.overdue and enrollment.cycle_due webhooks. Reminders are off by default.
5. Hand over to the developer#
| Item | Where you find it | Notes |
|---|---|---|
| API key | Settings → Developers → API keys | Shown once. Send it through a password manager or secret-sharing tool, never by email or chat. |
| API base URL | Your Flux contact | Different for staging and production. |
| Service ids | The service catalogue in the Flux app | Invoice lines reference services by id. The API can't list them yet. |
| Settlement bank account ids | Settings → Payments | Only if the integration sets a customer's defaultSettlementBankId. |
| Webhook signing secret | Settings → Developers → Webhooks | Shown once, if you register the endpoint for them. |
Rotate or revoke#
- Replacing a key: create the new key, let the developer deploy it, then revoke the old one. Both work in between, so nothing breaks.
- Revoking a key stops it at once. Revoke straight away if a key may have leaked.
- Rotating a webhook secret stops the old secret at once. Agree a time with the developer first. See Rotate keys and secrets.
What your customers see#
Invoices, receipts and reminders are emailed by Flux under your organization's name. They may come from your own verified email domain, and replies go to your reply-to address. The signed PDF and payment links the integration shows your customers open the same invoice and receipt documents Flux sends.