Instafuel Partner API
Instafuel is a fuel payment platform. A company funds a Fuelz wallet — its prepaid fuel purchase credit — and its drivers then pay for fill-ups at any partner station, whichever the fuel brand. Every transaction is traced, capped and reconciled.
This documentation is written for business introducers: partners who bring in and manage a portfolio of client companies on Instafuel. You build your own interface, Instafuel provides the API.
One public surface, and one only
The partner API is /v1/papi/*. It authenticates with an ifp_live_* or ifp_test_* API key. Everything documented here is reachable with that key, and nothing else is.
What you can do
| Area | Capability |
|---|---|
| Portfolio | list your client companies, read and update their record, onboard new ones |
| Client accounts | create and manage your clients' fleet manager and finance director accounts |
| Money | read wallets and the ledger, request a credit with proof of payment |
| Operations | read transactions, drivers, alerts |
| Reports | trigger an export and fetch the file once it is ready |
What you cannot do: credit a wallet without Instafuel approval, debit one, block one, see a company outside your portfolio, or touch stations and fuel brands.
Where to start
| You want to | Go to |
|---|---|
| Make your first call right now | Quickstart |
| Understand the portfolio model | Business introducer |
| Manage your keys and environments | API keys |
| Get a client's wallet credited | Wallet credit |
| Browse the operations | API reference |
Environments
| Environment | Base URL | Keys | Use |
|---|---|---|---|
| Staging | https://instafuel-backend-staging.up.railway.app | ifp_test_* | integration, test data |
| Production | provided with your ifp_live_* key | ifp_live_* | real money |
The two environments are strictly separated: distinct databases, non-interchangeable keys. An ifp_test_* key presented against production is rejected, and the other way round too.
The production address is not public
It is handed to you together with your ifp_live_* key, when your account is opened. The whole documentation — examples included — is written against staging: going live means changing two environment variables, the base URL and the key.
These addresses are not final: they are the current deployments. Examples are generated from the site configuration, so they will follow a domain change without any rewriting.
Real money
Credit requests approved in production move real money. Always validate your integration on staging, and make sure you send a distinct X-Idempotency-Key per business operation — not per network attempt.
What you can rely on
Integer amounts. A wallet balance is a prepaid fuel purchase credit, denominated in FCFA and usable only to pay for fill-ups at partner stations. It is neither a deposit nor electronic money: it cannot be refunded in cash, transferred between companies, or spent on anything other than fuel.
Technically, every amount travels as whole FCFA in the amountFcfa field: 500000, never 500000.0. Decimal numbers are not supported — a decimal amount is rejected with 400 WALLET_INVALID_AMOUNT, never rounded nor truncated. Only volumes (litres) are decimal.
Stable error codes. error.code is a contract, error.message is display text that may change. See Errors and idempotency.
Scope derived from the key. No query parameter widens what you can see. See Scope.
Idempotency. Every financial mutation requires X-Idempotency-Key. A replay never produces a second operation.
Immutable ledger. An entry is never modified nor deleted. A correction is a new entry.