Wallet & Identity

Withdrawals & Bank Payouts

Disburse funds from your partner wallet directly to any commercial bank or licensed fintech in Nigeria via real-time NIBSS Instant Payments (NIP).

Base Path/api/v1/partner/withdraw · /api/v1/partner/bank-transfer

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

Payout TypesSaved Beneficiary Withdrawal · Direct Account Transfer

Webhook Eventswithdrawal.success · withdrawal.failed

Step 1 — Verify Bank Account (Name Enquiry)

Perform an instant real-time NIP name enquiry before saving an account or initiating a payout to confirm account owner validity:

Verify bank account details

POST /partner/withdraw/accounts/verify

Signature required

Field	Type	Required	Description
accountNumber	string	required	10-digit NUBAN bank account number
bankCode	string	required	Standard 3-6 digit CBN bank code (e.g. `058` for GTBank, `044` for Access, `011` for First Bank)

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/withdraw/accounts/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "accountNumber": "0123456789",
    "bankCode": "058"
  }'

const res = await partnerClient.post("/withdraw/accounts/verify", {
  accountNumber: "0123456789",
  bankCode: "058"
});

Example response — 200 OK

{
  "success": true,
  "message": "Payout account verified successfully",
  "data": {
    "accountName": "ADAOBI MERCHRO ENTERPRISES",
    "accountNumber": "0123456789",
    "bankCode": "058",
    "bankName": "Guaranty Trust Bank"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/withdraw/accounts/verify"
}

Step 2 — Manage Beneficiary Bank Accounts

Save verified bank accounts for seamless recurring payouts without re-entering account details each time.

Save payout beneficiary account

POST /partner/withdraw/accounts

Signature required

Field	Type	Required	Description
accountNumber	string	required	10-digit NUBAN account number
bankCode	string	required	CBN bank code
accountName	string	optional	Account name (auto-resolved if omitted)
bankName	string	optional	Bank name

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/withdraw/accounts \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "accountNumber": "0123456789",
    "bankCode": "058",
    "accountName": "ADAOBI MERCHRO ENTERPRISES",
    "bankName": "Guaranty Trust Bank"
  }'

Example response — 201 Created

{
  "success": true,
  "message": "Payout account added successfully",
  "data": {
    "id": "665f29c19e1b2c0012a4eb10",
    "accountNumber": "0123456789",
    "accountName": "ADAOBI MERCHRO ENTERPRISES",
    "bankCode": "058",
    "bankName": "Guaranty Trust Bank"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/withdraw/accounts"
}

List saved payout accounts

GET /partner/withdraw/accounts

API Key only

Delete a saved payout account

DELETE /partner/withdraw/accounts/:id

Signature required

Executing Payouts

Option A — Withdraw to Saved Beneficiary

Disburse funds using a saved beneficiary's bankAccountId:

Withdraw funds to beneficiary

POST /partner/withdraw

Signature required

Field	Type	Required	Description
amount	number	required	Amount to withdraw in NGN
bankAccountId	string	required	24-character hexadecimal MongoDB ID of saved bank account
partnerReference	string	required	Unique reference (2–100 chars) for idempotency
provider	string	optional	Optional routing provider override

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/withdraw \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "amount": 50000,
    "bankAccountId": "665f29c19e1b2c0012a4eb10",
    "partnerReference": "PAYOUT-REF-8849"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Withdrawal initiated successfully",
  "data": {
    "reference": "WTH_1720603200000_77A1",
    "partnerReference": "PAYOUT-REF-8849",
    "amount": 50000,
    "fee": 50,
    "status": "pending",
    "accountName": "ADAOBI MERCHRO ENTERPRISES",
    "accountNumber": "0123456789",
    "bankName": "Guaranty Trust Bank"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/withdraw"
}

Option B — Direct Bank Transfer

Execute an instant bank transfer on the fly without saving the beneficiary beforehand:

Execute direct bank transfer

POST /partner/bank-transfer

Signature required

Field	Type	Required	Description
amount	number	required	Transfer amount in NGN
accountNumber	string	required	10-digit NUBAN account number
accountName	string	required	Account name (from name enquiry)
bankCode	string	required	CBN bank code
partnerReference	string	required	Unique reference for idempotency
provider	string	optional	Optional routing provider override

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/bank-transfer \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "amount": 100000,
    "accountNumber": "0123456789",
    "accountName": "ADAOBI MERCHRO ENTERPRISES",
    "bankCode": "058",
    "partnerReference": "TRF-DIRECT-9901"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Bank transfer initiated successfully",
  "data": {
    "reference": "TRF_1720603200000_99X2",
    "partnerReference": "TRF-DIRECT-9901",
    "amount": 100000,
    "fee": 50,
    "status": "pending"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/bank-transfer"
}

When the recipient bank settles the funds, Billpadi fires a withdrawal.success webhook. In the rare event of a reversal or communication failure, a withdrawal.failed webhook is sent and funds are automatically refunded to your wallet.

← PreviousWallet Deposits Next →Identity Verification