Billing & credits

Only POST /lookup is billed. GET /me, POST /report, consents, and webhook management are free. Each lookup is charged per data section returned, plus any third‑party pass‑through costs incurred to freshly verify that farmer.

How a lookup is priced

total = Σ (Riwe data fee for each returned section) + applicable pass‑through fees

Riwe data fees (per section, NGN)

Third‑party pass‑through fees (added only when incurred)

Pass‑through for the credit bureau is skipped on a cache hit (recent bureau pull), so repeat lookups of the same farmer can cost less.

Worked example — a bank's full lookup

A bank requesting all five of its sections for a farmer needing fresh verification:

The exact breakdown is returned inside every successful lookup under data.billing:

"billing": {
  "amount_charged": 310,
  "currency": "NGN",
  "credits": 31000,
  "breakdown": {
    "riwe_fee.identity": 25,
    "riwe_fee.bvn_nin_data": 30,
    "riwe_fee.credit_history": 50,
    "riwe_fee.outstanding_loans": 20,
    "riwe_fee.transaction_volume": 20,
    "passthrough.bvn": 50,
    "passthrough.nin": 35,
    "passthrough.credit_bureau": 80
  }
}

Paying less: request only the sections you need

By default a lookup returns all of your allowed sections. Pass a sections array to narrow it and pay only for those:

curl -X POST https://api.riwe.io/v1/rupa/lookup \
  -H "X-API-KEY: rk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "rupa_id": "rp-7lif9u", "sections": ["identity", "credit_history"] }'

Wallet & credits

• Lookups draw from your partner wallet (its balance is shown by GET /me as wallet_balance, in NGN). credits in the billing block is the same value expressed in Riwe's internal credit unit.
• Top up your wallet from the partner dashboard (Riwe admin can also credit it).
• If the balance is too low, the lookup is not performed and returns 402 with the amount required and the price breakdown — you are not charged.
• If a lookup fails after charging (rare, internal error), the amount is automatically refunded.

Insufficient‑balance response

{
  "success": false,
  "message": "Insufficient wallet balance for this lookup.",
  "data": {
    "required_amount": 65,
    "breakdown": { "riwe_fee.identity": 25, "riwe_fee.farms": 40 }
  }
}