Partner API
Guide

Account & dashboard

Manage your partner business credentials, retrieve your webhook secret, rotate API keys, inspect main wallet balance, and review webhook delivery logs.

These account-management endpoints are authenticated with your Dashboard Login JWT Token (obtained from POST /api/v1/auth/login) using the standard Authorization: Bearer <token> header.

Partner profile & webhook secret

Get partner profile

GET /partner/profile
Dashboard Bearer Auth

Returns your partner registration status, representative details, configured webhook URL, and your active webhookSecret:

cURL
curl https://api.billpadi.com/api/v1/partner/profile \
  -H "Authorization: Bearer <your-login-token>"
Example response — 200 OK
{
  "success": true,
  "message": "Profile retrieved successfully",
  "data": {
    "id": "665f1c2a9e1b2c0012a4e9f1",
    "firstname": "Ada",
    "lastname": "Obi",
    "email": "ada@merchro.com",
    "phone": "+2348012345678",
    "partner": {
      "companyName": "Merchro Ltd",
      "contactPerson": "Ada Obi",
      "status": "active",
      "webhookUrl": "https://api.yourdomain.com/webhooks/billpadi",
      "webhookSecret": "a8f3b4c1d2e9876543210fedcba9876543210fedcba9876543210fedcba98765",
      "allowedIps": ["102.89.44.12", "197.210.55.0/24"],
      "createdAt": "2026-06-02T11:04:00.000Z"
    }
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/profile"
}

IP whitelist management

Billpadi enforces network-level IP whitelisting for your API keys. When configured, any request sent from an IP address not in your whitelist is immediately rejected with 403 Forbidden.

Update authorized IP addresses

PUT /partner/ip-whitelist
Dashboard Bearer Auth

Send an array of exact IPv4/IPv6 addresses or CIDR blocks. Set to [] (empty array) to disable IP restrictions during sandbox testing:

cURL
Node.js
curl -X PUT https://api.billpadi.com/api/v1/partner/ip-whitelist \
  -H "Authorization: Bearer <your-login-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      "102.89.44.12",
      "197.210.55.0/24"
    ]
  }'
const res = await fetch("https://api.billpadi.com/api/v1/partner/ip-whitelist", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer ",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    allowedIps: ["102.89.44.12", "197.210.55.0/24"]
  })
});
const data = await res.json();
Example response — 200 OK
{
  "success": true,
  "message": "IP whitelist updated successfully",
  "data": {
    "allowedIps": [
      "102.89.44.12",
      "197.210.55.0/24"
    ],
    "count": 2
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/ip-whitelist"
}

API key management

Generate or rotate API key

POST /partner/api-keys
Dashboard Bearer Auth

Returns a newly generated apiKey and apiSecret pair. Store the secret immediately in your environment secrets manager; it is encrypted at rest and cannot be recovered if lost.

List active API keys

GET /partner/api-keys
Dashboard Bearer Auth

Returns your active key metadata (ID, masked prefix, status, and creation date).

Deactivate an API key

DELETE /partner/api-keys/:keyId
Dashboard Bearer Auth

Dashboard, wallet & audit

Get dashboard analytics

GET /partner/dashboard
Dashboard Bearer Auth

Get partner wallet balance

GET /partner/wallet
Dashboard Bearer Auth
cURL
curl https://api.billpadi.com/api/v1/partner/wallet \
  -H "Authorization: Bearer <your-login-token>"
Example response — 200 OK
{
  "success": true,
  "message": "Wallet retrieved successfully",
  "data": {
    "balance": 8450000.50,
    "currency": "NGN",
    "ledgerBalance": 8450000.50
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/wallet"
}

Lookup any transaction by reference

GET /partner/transactions/:reference
Dashboard Bearer Auth

Get webhook dispatch audit history

GET /partner/webhooks
Dashboard Bearer Auth
← PreviousWebhooksNext →Wallet Deposits