Wallet credit
You can declare that one of your clients has paid. You never credit directly.
Why a request and not a credit
You are a third party. Only Instafuel observes the payment landing on its bank account.
If your call credited immediately, calling the API would be enough to create purchase credit with nothing collected behind it. Every request therefore goes through an Instafuel approval — no exception, and no threshold below which it would be automatic.
Three locks
A credit is only possible if all three are open:
- the key carries the
CREDIT_REQUEST_WRITEscope — otherwise403 PAPI_SCOPE_MISSING; walletCreditEnabledis true for your account — otherwise403 RESELLER_CREDIT_DISABLED;- the amount respects your per-operation and daily caps — otherwise
422.
Your current caps are on GET /v1/papi/me:
The flow
-
Upload the proof of payment
Up to 3 files, 10 MB each. Keep the returned
ids: they are required in the next step.Proof is mandatory, whatever the source
Mobile money included. It is the document Instafuel's bank reconciliation will require before approving.
-
Declare the payment
The response is a
202, never a200— and that difference is the whole point:202means "request recorded", not "operation done". Three things to read in that response:walletBalanceFcfais still 1,450,000: the balance has not moved. Do not display it as credited.clientReferencecame back prefixed with your introducer identifier (IFP7-). Two partners using "VIR-2026-0814" on the same wallet therefore do not collide.expiresAtis 7 days away: without approval by then, the request expires and has to be filed again.
A cap overrun is refused on the spot, with the figures you need to split the payment:
-
Track the request
statusMeaning PENDING_APPROVALwaiting for Instafuel validation APPROVEDwallet credited, entry posted to the ledger REJECTEDrefused — the reason is in rejectionReasonEXPIRED7 days without approval -
Instafuel approves
The wallet is credited, the entry is posted to the ledger and the proofs are attached to it. The request then reflects the entry produced:
balanceAfterFcfais the balance after the entry: that is the moment, and not before, when the credit becomes usable for fill-ups.
Fields
| Field | Required | Detail |
|---|---|---|
amountFcfa | yes | strictly positive whole FCFA |
source | yes | BANK_TRANSFER, MOBILE_MONEY, CASH_DEPOSIT, CHEQUE — the actual nature of the payment |
clientReference | yes | your own reference: transfer number, mobile money transaction id… |
proofIds | yes | 1 to 3 proof identifiers uploaded in step 1 |
note | no | free comment, 500 characters |
Caps
The daily cap counts credits already approved and requests still pending. Stacking requests under the cap does not get around it.
error.code | HTTP | Cause |
|---|---|---|
RESELLER_CREDIT_DISABLED | 403 | credit not enabled for your account |
RESELLER_CREDIT_CAP_EXCEEDED | 422 | per-operation cap exceeded |
RESELLER_DAILY_CAP_EXCEEDED | 422 | daily cap exceeded |
PROOF_REQUIRED | 400 | no proof supplied |
PROOF_INVALID | 422 | proof missing, deleted, already attached, or belonging to another company |
PROOF_TOO_MANY | 400 | more than 3 proofs |
WALLET_BLOCKED | 400 | the company's wallet is blocked |
A cap 422 is not retried as-is: split the payment or ask for a higher cap.
Re-checked at approval time
Days can pass between your request and the approval. Everything is re-checked at execution time: is your account still active, is credit still allowed, is the company still in your portfolio, are the proofs still valid, is the wallet unblocked.
If any of those changed, execution fails and the request stays pending rather than being marked approved by mistake.
What you cannot do
No refund, no debit, no wallet block, no cancellation of a posted entry. The ledger is immutable: a correction is a new entry, posted by Instafuel.