Payouts

Send money from your available balance to a Nigerian bank account.

1. Add the bank account#

bash

curl https://sandbox.api.biftpay.com/v1/bank_accounts \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: acct-vendor-17" \
  -H "Content-Type: application/json" \
  -d '{ "bank_code": "058", "account_number": "0123456789" }'

bank_code is the bank's code (3 to 6 digits). Biftpay checks the account with the bank first (name enquiry) and saves the account name the bank returns. Show it to whoever is approving the payout. Adding the same account again returns the one you already have.

2. Check the cost (optional)#

GET /v1/payouts/quote?amount=500000&currency=NGN returns the fee, VAT and the total that will leave your balance, and whether your balance covers it.

3. Pay out#

bash

curl https://sandbox.api.biftpay.com/v1/payouts \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: payout-vendor-17-oct" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500000, "currency": "NGN", "bank_account_id": "...", "narration": "October invoice" }'

The payout and the fee leave your available balance in the same step (total_debited = amount + fee + VAT). If the balance is too small, nothing happens and you get 409 insufficient_funds.

Statuses#

Status	Meaning
`awaiting_approval`	Biftpay is checking it first. `review_reasons` says why, for example a large amount or a bank account added in the last 24 hours.
`queued`	Waiting to be sent. You can still cancel it.
`processing`	Sent to the bank, waiting for confirmation.
`paid`	The bank confirmed it (`payout.paid`).
`failed`	The bank rejected it. The full amount, fee included, goes back to your available balance (`payout.failed`).
`canceled`	Canceled before it was sent (`payout.canceled`).

A payout's final status comes only from the bank's own confirmation, never from a guess, so processing can last a little while.

Limits#

Payouts have a per-payout and a daily limit based on your business type. Your current limits and today's usage are in the dashboard; ask Biftpay if you need more. Automatic settlement isn't limited.