Glossary
Money
Fuelz — the unit of account of the Instafuel wallet. One Fuelz corresponds to one FCFA of fuel to be paid for at a partner station.
It is an internal unit of account, not a means of payment: Fuelz are neither refundable in cash, nor transferable between companies, nor usable for anything other than fuel. Instafuel issues no electronic money and holds no deposit account — the wallet records a right to purchase fuel that has already been paid for.
In the API, that unit is always expressed in whole FCFA (amountFcfa): 500000, never 500000.0. Decimal numbers are not supported on amounts: a decimal is rejected (400 WALLET_INVALID_AMOUNT), never rounded. Fuel volumes (litres) are decimal.
Wallet — the counter of a company's fuel purchase credit. Funded by an approved credit once a payment has been observed, debited on every validated fill-up. It cannot be emptied other than in fuel.
Ledger — the immutable journal of wallet movements. An entry is never modified nor deleted; a correction is a new entry. The displayed balance is a cache whose authoritative value remains the sum of the entries.
Hold — a temporary reservation of funds. Placed when a fill-up opens, to guarantee the amount will be available at validation; released if the transaction is cancelled, captured otherwise. A PENDING transaction is a hold in progress: funds are committed but not yet debited.
Available balance — the wallet balance minus the current holds. That is what a driver can actually spend.
Cap — a spending or credit limit. On the company side it bounds daily or monthly spending; on the introducer side, the amount you can declare per operation and per day.
Proof of payment — supporting document (transfer, mobile money receipt, cheque) attached to a credit request. A proof can only be attached to a single entry. Mandatory whatever the source.
Actors
Company (Company) — the end client. Owns a wallet, vehicles, drivers.
Business introducer — the partner who brings in and manages a portfolio of client companies. That is you, and that is what your ifp_* key represents.
Portfolio — the set of companies attached to an introducer. A company belongs to one introducer at any point in time.
Driver (Driver) — the employee of a client company who pays for fill-ups. Attached to a company, never to an introducer.
Fuel brand (marketeur) — the fuel brand: Total, Shell, Petroci… It owns the station network and sets reference prices. You do not interact with fuel brands: the whole point of Instafuel is that your clients pay at any station, whichever the brand.
Operations
Scope — the set of data visible to a key. Always derived from the key, never from the request. See Scope.
Key scope — a capability attached to an API key: COMPANIES_READ, COMPANIES_WRITE, CREDIT_REQUEST_WRITE, REPORTS_READ. See API keys.
Idempotency — the guarantee that a replay does not produce a second operation. Carried by the X-Idempotency-Key header. See Errors and idempotency.
Approval request — a sensitive operation initiated by you and validated by Instafuel. The initiator never approves their own request. A credit request expires after 7 days without approval.
Feature flag — the switch enabling a feature. When off, it answers 404 FEATURE_DISABLED, never 403: it stays invisible.
Identifiers
Reference code (ref) — a readable, stable identifier exposed on the main entities, meant for support and disputes: ENT-B14E77A3 for a company, TRX-4B71E0A9 for a transaction, APP-7C3D91B0 for an introducer. Distinct from the technical identifier (id), which remains the one to use in URLs.
RCCM — the Ivorian trade and personal property credit register, a company's legal identifier. Format CI-ABJ-2024-B-12345.
NIF — tax identification number.
Phone number — always in Ivorian international format: +225 followed by 10 digits.