# Instafuel Partner API

import { StagingUrl } from "../../src/ApiExample";

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.

<Callout type="info" title="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.
</Callout>

## 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](/en/guides/demarrage-rapide) |
| Understand the portfolio model | [Business introducer](/en/guides/apporteur-affaires) |
| Manage your keys and environments | [API keys](/en/guides/cles-api) |
| Get a client's wallet credited | [Wallet credit](/en/guides/credit-wallet) |
| Browse the operations | [API reference](/api) |

## Environments

| Environment | Base URL | Keys | Use |
|---|---|---|---|
| Staging | <StagingUrl /> | `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.

<Callout type="caution" title="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.
</Callout>

<Callout type="danger" title="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.
</Callout>

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

**Scope derived from the key.** No query parameter widens what you can see. See [Scope](/en/guides/perimetre).

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