FluxDevelopers OpenAPI & schemasOpenAPI

Integration API v1

Integrate with Flux

Flux runs invoicing, payments, payroll, HR and tax for growing businesses. The integration API lets your system bill its own customers through a Flux organization: sync customers, raise invoices into Flux's approval workflow, take payment online and hear about every change by webhook.

How it works#

  1. You

    Sync customers

    Create each customer once with your own id as externalRef, and keep them up to date.

  2. You → Flux

    Raise invoices

    POST /invoices puts an invoice into the organization's approval workflow.

  3. Flux

    Approve and send

    The organization's reviewers approve it. Flux emails it to the customer's billing contacts.

  4. Flux → you

    Get paid, hear about it

    The customer pays online. Flux verifies it and sends invoice.paid and receipt.issued.

Approval stays a human control in Flux. Your system raises and reads; it doesn't approve.

What you can do#

You canWithPage
Create, update and find customers by your own reference/customersCustomers
Read a customer's services and statement totals/customers/{id}/enrollments, /statementCustomers
Raise invoices without double billing, and read them/invoicesInvoices
Read receipts for paid invoices/receipts/{invoiceId}Receipts
Give your customers PDF and payment links/invoices/{id}/linksSigned links
Start an online payment (Paystack)/invoices/{id}/checkoutPayments
Receive events, and manage where they go/webhook-endpointsWebhooks

These stay in the Flux app, so the API doesn't offer them:

  • Approving, returning, editing and voiding invoices. People with the right roles do this, and you hear about it by webhook.
  • The service catalogue, enrollments, bank accounts and payment settings.
  • Payroll, HR, payment vouchers, tax returns and reports.

Base URL and environments#

Every integration endpoint is under {BASE_URL}/api/v1. Signed links for your customers are under {BASE_URL}/public.

EnvironmentAPI base URLUse
Productionproduction API base URLYour organization's live data.
Staginghttps://erpapi.osigla.com.ng confirm the staging URL can be publishedFor building and testing, with a staging organization. how integrators get staging access

Keys start with flx_live_. There's no test mode, so build and test against staging with a staging organization, never against a live organization's customers.

Conventions at a glance#

  • Authenticate with Authorization: ApiKey flx_live_…. Authentication
  • JSON in and out, with camelCase field names. Errors are { "code", "message", "details" }. Errors
  • Lists are newest first, with cursor pagination. Pagination
  • Money is decimal in major units: 250000.00 is ₦250,000.00. Dates, money and currencies
  • 120 requests a minute per key by default. Rate limits

Go-live checklist#

Your integration is ready for production when it does all eight. Tick them off as you go; the ticks are saved in this browser only.

  1. Store the API key in a secret manager or an environment variable, never in code, URLs, logs or a browser. Ask for only the scopes you use. Authentication →

  2. Send externalRef on customers and invoices, and an Idempotency-Key on every create. A retried request can't double-bill. Idempotency →

  3. Branch on code, never on message. Retry 429 after Retry-After, and 5xx or network errors with backoff. Errors →

  4. Check Flux-Signature with HMAC-SHA256 over the raw body, compare in constant time, and reject timestamps more than 300 seconds old. Verify signatures →

  5. Respond 2xx within 10 seconds and do the work afterwards. Deduplicate on Flux-Event-Id, and don't rely on event order. Receiving webhooks →

  6. Treat an invoice as paid only after invoice.paid (or status: paid). Handle invoice.payment_review. Payments →

  7. Links expire. Ask for fresh ones when a page loads instead of storing them. Signed links →

  8. v1 grows by addition. Ignore unknown fields and event types instead of failing on them. Versioning →

Getting help#

Contact support email or URL with your organization's name and, where it helps, the invoice number, the Flux-Event-Id or the delivery id. Never send an API key or webhook secret.