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 a verification fee when a fresh ID or credit check is run for that farmer.

How a lookup is priced

total = Σ (data fee for each returned section) + any verification fees

Data fees (per section, NGN)

Section	Fee
`identity`	25
`bvn_nin_data`	30
`credit_history`	50
`outstanding_loans`	20
`transaction_volume`	20
`farms`	40
`underwriting_value`	45
`wallet`	15
`socioeconomic_profile`	20

Verification fees (added only when a fresh check runs)

When	Breakdown key	Fee
`bvn_nin_data` requested → fresh BVN check	`verification_fee.bvn`	50
`bvn_nin_data` requested → fresh NIN check	`verification_fee.nin`	35
`credit_history` requested → credit check (basic)	`verification_fee.credit_check`	80
`credit_history` requested → credit check (advanced)	`verification_fee.credit_check`	150

The credit check fee is skipped when a recent check is on file for that farmer, 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:

Line	NGN
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
verification_fee.bvn	50
verification_fee.nin	35
verification_fee.credit_check	80
Total charged	310

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,
    "verification_fee.bvn": 50,
    "verification_fee.nin": 35,
    "verification_fee.credit_check": 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 }
  }
}

Base URL https://api.riwe.io/v1/rupa Get API access