Wallet & Identity

Wallet Deposits

Fund your partner balance via on-demand bank checkout or provision a dedicated permanent virtual bank account under your company name for automated funding.

Base Path/api/v1/partner/deposit

Authx-api-key (+ x-signature on write actions)

Funding MethodsDynamic Bank Transfer Checkout · Dedicated Permanent Virtual Account

Webhook Eventdeposit.success

Method 1 — Dynamic Bank Transfer Checkout

Initiate an on-demand deposit. Returns payment transfer details or an instant checkout session:

Initialize deposit checkout

POST /partner/deposit/fund

Signature required

Field	Type	Required	Description
amount	number	required	Deposit amount in NGN (positive number)
method	string	optional	`bank_transfer` (default) or `card`
provider	string	optional	Optional override (e.g. `saveHaven`, `monnify`, `flutterwave`). Omit to use the active default provider.

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/deposit/fund \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "amount": 250000,
    "method": "bank_transfer"
  }'

const res = await partnerClient.post("/deposit/fund", {
  amount: 250000,
  method: "bank_transfer"
});

Example response — 200 OK

{
  "success": true,
  "message": "Deposit payment initialized successfully",
  "data": {
    "reference": "DEP_1720603200000_33B1",
    "amount": 250000,
    "paymentDetails": {
      "accountNumber": "9901827461",
      "bankName": "Wema Bank",
      "accountName": "Billpadi / Merchro Ltd",
      "expiresAt": "2026-07-10T10:20:03.000Z"
    }
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/deposit/fund"
}

Method 2 — Dedicated Permanent Virtual Account

For high-frequency funding, provision a persistent, dedicated Nigerian bank account number assigned specifically to your partner account. Any transfer to this account instantly credits your main partner balance 24/7/365.

Step 2.1: Initiate Identity Verification

Submit your BVN or NIN along with matching legal identity details:

Initiate permanent virtual account KYC

POST /partner/deposit/permanent/initiate

Signature required

Field	Type	Required	Description
identificationType	string	required	`bvn` or `nin`
value	string	required	11-digit BVN or NIN number
firstname	string	required	Legal first name matching identity records
lastname	string	required	Legal last name matching identity records
middlename	string	optional	Middle name (if registered)
dateOfBirth	string	optional	Format: `YYYY-MM-DD`
phoneNumber	string	optional	Registered phone number on BVN/NIN
address	string	optional	Registered business or personal address
state	string	optional	State / province
city	string	optional	City
postalCode	string	optional	Postal code

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/deposit/permanent/initiate \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "identificationType": "bvn",
    "value": "22123456789",
    "firstname": "Ada",
    "lastname": "Obi",
    "dateOfBirth": "1992-05-14",
    "phoneNumber": "+2348012345678"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Identity validation initiated",
  "data": {
    "isOtpRequired": true,
    "identityId": "ident_9f3a8b2c1e4d0f7a",
    "step": "otp_verification",
    "expiresIn": 3600,
    "nextStep": "Verify the OTP sent to your phone to continue"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/deposit/permanent/initiate"
}

Step 2.2: Verify OTP & Provision Virtual Account

Submit the one-time passcode delivered by the bank/identity authority to complete account provisioning:

Verify OTP and create permanent account

POST /partner/deposit/permanent/verify

Signature required

Field	Type	Required	Description
identityId	string	required	The `identityId` returned from Step 2.1
otp	string	required	OTP code delivered to the registered phone number
identificationType	string	optional	`bvn` or `nin` (defaults to `bvn`)

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/deposit/permanent/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "identityId": "ident_9f3a8b2c1e4d0f7a",
    "otp": "481920",
    "identificationType": "bvn"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Identity verified and permanent virtual account created successfully",
  "data": {
    "verified": true,
    "account": {
      "accountNumber": "7012345678",
      "bankName": "SafeHaven Microfinance Bank",
      "accountName": "BILLPADI / MERCHRO LTD",
      "status": "active",
      "type": "permanent",
      "currency": "NGN"
    }
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/deposit/permanent/verify"
}

Inspect Active Deposit Accounts

Retrieve details of your currently assigned virtual deposit account at any time:

Get permanent deposit account

GET /partner/deposit/accounts

API Key only

cURL

curl https://api.billpadi.com/api/v1/partner/deposit/accounts \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Deposit account retrieved successfully",
  "data": {
    "hasAccount": true,
    "account": {
      "accountNumber": "7012345678",
      "bankName": "SafeHaven Microfinance Bank",
      "accountName": "BILLPADI / MERCHRO LTD",
      "status": "active"
    }
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/deposit/accounts"
}

← PreviousAccount & Dashboard Next →Withdrawals & Payouts