Getting started

Four steps to your first live transaction: register, get approved, generate your API key pair, and sign your first write request.

Step 1 — Register as a partner

Self-register with your business and representative contact details. This is a public endpoint — no API key is required yet.

curl -X POST https://api.billpadi.com/api/v1/partner/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Ada",
    "lastname": "Obi",
    "email": "ada@merchro.com",
    "password": "StrongPass1!",
    "phone": "+2348012345678",
    "companyName": "Merchro Ltd",
    "contactPerson": "Ada Obi",
    "country": "Nigeria",
    "state": "Lagos",
    "city": "Ikeja",
    "address": "12 Commercial Avenue"
  }'

const res = await fetch("https://api.billpadi.com/api/v1/partner/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    firstname: "Ada",
    lastname: "Obi",
    email: "ada@merchro.com",
    password: "StrongPass1!",
    phone: "+2348012345678",
    companyName: "Merchro Ltd",
    contactPerson: "Ada Obi",
    country: "Nigeria",
    state: "Lagos",
    city: "Ikeja",
    address: "12 Commercial Avenue"
  }),
});
const data = await res.json();

{
  "success": true,
  "message": "Partner registration successful. Awaiting admin approval.",
  "data": {
    "id": "665f1c2a9e1b2c0012a4e9f1",
    "firstname": "Ada",
    "lastname": "Obi",
    "email": "ada@merchro.com",
    "companyName": "Merchro Ltd",
    "status": "pending"
  },
  "timestamp": "2026-07-10T09:12:41.000Z",
  "path": "/api/v1/partner/auth/register"
}

Step 2 — Wait for approval

New partner accounts initialize in a pending status. Our compliance team verifies your business credentials and activates your account. API key authentication enforces that your partner status is active before processing live service requests.

Step 3 — Log in and generate an API key pair

Once approved, authenticate with your email and password via standard login to acquire a JWT bearer token for account configuration.

With your session token, call POST /partner/api-keys to generate your active API key and secret:

This returns your apiKey (e.g. sk_live_...) and apiSecret in plain text. Store both in your encrypted secret store immediately — for security, the API secret is hashed in our database and cannot be retrieved again.

curl -X POST https://api.billpadi.com/api/v1/partner/api-keys \
  -H "Authorization: Bearer <your-login-token>"

{
  "success": true,
  "message": "Save your API key and secret. You won't see them again.",
  "data": {
    "id": "665f20b19e1b2c0012a4ea02",
    "apiKey": "sk_live_1f9c2a7e4b6d0f83a5c1e9b7d4f2038a...",
    "apiSecret": "9a3e7c1b5d8f2046e1a9c7b3d5f80261e4a7c9b3d5f80261e4a7c9b3d5f8026"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/api-keys"
}

Step 4 — Make your first API request

Read operations (such as listing telecom networks or electricity DISCOs) require only the x-api-key header:

curl https://api.billpadi.com/api/v1/partner/airtime/networks \
  -H "x-api-key: sk_live_1f9c2a7e4b6d0f83a5c1e9b7d4f2038a..."

For write actions (airtime top-up, bill payments, payouts, crypto trades), you must sign the JSON body with your apiSecret and pass the HMAC hash in x-signature. Proceed to Authentication & Signing to view code examples for Node.js, Python, PHP, and Go.