Partner API
Partner API · Developer Docs

Build fintech and bill-payment features on our rails

The Partner API empowers your platform to automate wallet deposits, bank payouts, crypto trading, identity verification (NIN/BVN), gift cards, airtime, mobile data, electricity tokens, cable TV, betting wallets, education PINs, and international top-ups — with clean human-readable slugs, a unified HMAC-SHA256 signature scheme, and real-time webhook callbacks.

Base URLhttps://partner-api.billpadi.com/api/v1/partner
Authx-api-key header, HMAC-SHA256 request signing
Formatapplication/json in, JSON envelope out
Rate limit30 requests / 60s per route group (with failure circuit breaker)

All partner API requests are served under /api/v1/partner. Make sure to include your assigned x-api-key in the header of every request.

How it fits together

Every service and product group follows a predictable, battle-tested pattern:

  • Catalog / lookup endpoints (networks, packages, providers, rates, countries) — read-only operations that require only your x-api-key. Use clean slugs like mtn, dstv, ikeja-electric, or bet9ja.
  • Action endpoints (purchase, sell, fund, withdraw, verify) — write operations that move funds or verify identity. These require your x-api-key plus an HMAC-SHA256 signature in the x-signature header.
  • Status & listing endpoints — check any transaction status instantly by its reference, or retrieve paginated lists of past activity.
  • Webhook notifications — asynchronous completion events (e.g. electricity meter tokens, gift card approvals, bank transfer settlements) are delivered straight to your webhook URL signed with your webhookSecret.

Every response is wrapped in a consistent JSON envelope, and every write endpoint requires a unique partnerReference so you can reconcile records against your database seamlessly.

Wallet & Identity

01

Wallet Deposits

Initiate dynamic bank transfer checkout or provision dedicated permanent virtual accounts.

 02

Withdrawals & Payouts

Perform account name lookups, save beneficiary accounts, and execute automated bank transfers.

 03

Identity Verification

Verify customer NIN or BVN details with biometric and government identity validation rails.

Products & Value-Added Services

04

Airtime

Instant airtime top-ups for MTN, Airtel, Glo, and 9mobile.

 05

Mobile Data

Catalog bundles, SME data, and direct top-up packages.

 06

Electricity

Pay prepaid and postpaid DISCO bills with instant meter tokens.

 07

Cable TV

Verify smartcards and renew DSTV, GOtv, and StarTimes subscriptions.

 08

Betting Funding

Verify customer bet accounts and fund wallets across top bookmakers.

 09

Education PINs

Purchase WAEC and JAMB candidate examination and result checker PINs.

 10

Gift Cards

Purchase digital gift cards or submit cards for sale with automated settlement.

 11

Crypto Trading

Execute buy and sell orders for BTC, ETH, USDT, and USDC with real-time rates.

 12

International Top-Up

Send mobile airtime and data bundles to hundreds of global destinations.

A typical integration

  1. Register at POST /partner/auth/register and wait for partner account approval — see Getting Started.
  2. Log in to your partner portal or use your session token to generate an API key and retrieve your secret via POST /partner/api-keys.
  3. Sign every write request with your secret — see Authentication & Signing.
  4. Configure your webhook endpoint via PATCH /partner/webhook to receive real-time notifications for completed transactions — see Webhooks.
  5. Handle responses, pagination envelopes, and rate limits gracefully — see Errors & Status Codes and Rate Limits.

Production API keys are prefixed with sk_live_… and move real funds. We recommend testing your signature calculation and webhook handling with low denomination transactions first.

Next →Getting Started