# 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](/en/guides/perimetre).

**Key scope** — a capability attached to an API key: `COMPANIES_READ`, `COMPANIES_WRITE`, `CREDIT_REQUEST_WRITE`, `REPORTS_READ`. See [API keys](/en/guides/cles-api).

**Idempotency** — the guarantee that a replay does not produce a second operation. Carried by the `X-Idempotency-Key` header. See [Errors and idempotency](/en/guides/erreurs).

**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.