Payouts

get/v1/bank_accountsList payout destinations
post/v1/bank_accountsRegister a payout destination
get/v1/payoutsList payouts
post/v1/payoutsPay out to a registered bank account
get/v1/payouts/{id}Retrieve a payout
post/v1/payouts/{id}/cancelCancel a payout before it is sent
get/v1/payouts/quoteWhat a payout would cost, and whether the balance covers it
get/v1/usdtUSDT settlement: whether it's on, Biftpay's rules, your wallets and the one automatic settlement uses
get/v1/usdt/previewBefore sending: dollars available, the fee, and the USDT the wallet should receive
get/v1/usdt/payoutsYour USDT payouts, newest first
post/v1/usdt/payoutsSend dollars as USDT to one of your wallets (added and cleared in the dashboard)

List payout destinations

get/v1/bank_accounts

bash

curl https://sandbox.api.biftpay.com/v1/bank_accounts \
  -H "Authorization: Bearer bp_test_..."

Responses

200
Registered bank accountsobject
Fields
object"list"required
dataarray of BankAccountrequired
Fields of data
idstring (uuid)required
object"bank_account"required
livemodebooleanrequired
bank_codestringrequired
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
As returned by the bank's name enquiry.
verified_atstring (date-time)required
created_atstring (date-time)required
has_morebooleanrequired
401
Missing or invalid API key

Register a payout destination

post/v1/bank_accounts

The account is checked with the bank (name enquiry) before it is saved, and the account name the bank returns is what is stored and shown. Adding the same account again returns the existing one. In test mode, account numbers ending in 0000 fail name enquiry.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

bank_codestringrequired

account_numberstringrequired

10-digit NUBAN

bash

curl -X POST https://sandbox.api.biftpay.com/v1/bank_accounts \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "999",
    "account_number": "0123456789"
  }'

Responses

201
The verified bank accountBankAccount
Fields
idstring (uuid)required
object"bank_account"required
livemodebooleanrequired
bank_codestringrequired
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
As returned by the bank's name enquiry.
verified_atstring (date-time)required
created_atstring (date-time)required
400
Invalid request
401
Missing or invalid API key
409
The object is in a state that doesn't allow this

List payouts

get/v1/payouts

Parameters

limitintegerin query

1 to 100 · default 20

starting_afterstring (uuid)in query

The id of the last item on the previous page.

bash

curl https://sandbox.api.biftpay.com/v1/payouts \
  -H "Authorization: Bearer bp_test_..."

Responses

200
A page of payoutsPayoutList
Fields
object"list"required
dataarray of Payoutrequired
Fields of data
idstring (uuid)required
Also the reference sent to the bank.
object"payout"required
livemodebooleanrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
total_debitedintegerrequired
amount + fee + vat
at least 0
currencyNGN | USDrequired
statusawaiting_approval | queued | processing | paid | failed | canceledrequired
awaiting_approval (Biftpay is reviewing it first, e.g. a large amount) -> queued -> processing (sent, waiting for the bank's confirmation) -> paid or failed. canceled is only possible before sending.
narrationstring | null
brandstring (uuid)
The brand whose balance pays it.
review_reasonsarray of amount | new_bank_account | account_review | security_change | unusual
Why Biftpay is checking it before it's sent (status awaiting_approval); empty otherwise. new_bank_account - the first payout to an account added in the last 24 hours; account_review - the business or brand is under review, or several disputes arrived this week; security_change - a password or authenticator change by the requester, or a settlement account change, in the last 24 hours; unusual - far larger than this merchant has paid out before, or most of the balance after 30 quiet days; amount - over an approval threshold Biftpay set for this merchant.
bank_accountobjectrequired
Fields of bank_account
idstring (uuid)required
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
approved_atstring (date-time) | null
failure_codestring | null
created_atstring (date-time)required
paid_atstring (date-time) | null
failed_atstring (date-time) | null
canceled_atstring (date-time) | null
has_morebooleanrequired
401
Missing or invalid API key

Pay out to a registered bank account

post/v1/payouts

Moves amount + fee + VAT from available to payout_in_flight in the same step that records the payout, so a short balance fails with 409 insufficient_funds and nothing is written. Payouts at or above the merchant's approval threshold wait for Biftpay's review (awaiting_approval). The outcome is settled only from the bank's status query: paid, or failed with the money returned to available.

In test mode, account numbers ending in 9999 fail after sending, 7777 are rejected by the provider, and 8888 stay processing.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

amountintegerrequired

at least 1

currencyNGN | USDrequired

bank_account_idstring (uuid)required

A registered, name-checked destination account.

narrationstring

up to 100 characters

brandstring (uuid)

Pay out of this brand's balance. Defaults to the business's own brand.

otpobject or object

Required when a signed-in user (not an API key) requests the payout. From POST /v1/payouts/otp.

bash

curl -X POST https://sandbox.api.biftpay.com/v1/payouts \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "NGN",
    "bank_account_id": "…"
  }'

Responses

201
CreatedPayout
Fields
idstring (uuid)required
Also the reference sent to the bank.
object"payout"required
livemodebooleanrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
total_debitedintegerrequired
amount + fee + vat
at least 0
currencyNGN | USDrequired
statusawaiting_approval | queued | processing | paid | failed | canceledrequired
awaiting_approval (Biftpay is reviewing it first, e.g. a large amount) -> queued -> processing (sent, waiting for the bank's confirmation) -> paid or failed. canceled is only possible before sending.
narrationstring | null
brandstring (uuid)
The brand whose balance pays it.
review_reasonsarray of amount | new_bank_account | account_review | security_change | unusual
Why Biftpay is checking it before it's sent (status awaiting_approval); empty otherwise. new_bank_account - the first payout to an account added in the last 24 hours; account_review - the business or brand is under review, or several disputes arrived this week; security_change - a password or authenticator change by the requester, or a settlement account change, in the last 24 hours; unusual - far larger than this merchant has paid out before, or most of the balance after 30 quiet days; amount - over an approval threshold Biftpay set for this merchant.
bank_accountobjectrequired
Fields of bank_account
idstring (uuid)required
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
approved_atstring (date-time) | null
failure_codestring | null
created_atstring (date-time)required
paid_atstring (date-time) | null
failed_atstring (date-time) | null
canceled_atstring (date-time) | null
400
Invalid request
401
Missing or invalid API key
409
The object is in a state that doesn't allow this
422
Idempotency-Key reused with a different request

Retrieve a payout

get/v1/payouts/{id}

Parameters

idstring (uuid)in pathrequired

bash

curl https://sandbox.api.biftpay.com/v1/payouts/{id} \
  -H "Authorization: Bearer bp_test_..."

Responses

200
The payoutPayout
Fields
idstring (uuid)required
Also the reference sent to the bank.
object"payout"required
livemodebooleanrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
total_debitedintegerrequired
amount + fee + vat
at least 0
currencyNGN | USDrequired
statusawaiting_approval | queued | processing | paid | failed | canceledrequired
awaiting_approval (Biftpay is reviewing it first, e.g. a large amount) -> queued -> processing (sent, waiting for the bank's confirmation) -> paid or failed. canceled is only possible before sending.
narrationstring | null
brandstring (uuid)
The brand whose balance pays it.
review_reasonsarray of amount | new_bank_account | account_review | security_change | unusual
Why Biftpay is checking it before it's sent (status awaiting_approval); empty otherwise. new_bank_account - the first payout to an account added in the last 24 hours; account_review - the business or brand is under review, or several disputes arrived this week; security_change - a password or authenticator change by the requester, or a settlement account change, in the last 24 hours; unusual - far larger than this merchant has paid out before, or most of the balance after 30 quiet days; amount - over an approval threshold Biftpay set for this merchant.
bank_accountobjectrequired
Fields of bank_account
idstring (uuid)required
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
approved_atstring (date-time) | null
failure_codestring | null
created_atstring (date-time)required
paid_atstring (date-time) | null
failed_atstring (date-time) | null
canceled_atstring (date-time) | null
401
Missing or invalid API key
404
Not found, or not visible to this key

Cancel a payout before it is sent

post/v1/payouts/{id}/cancel

Only awaiting_approval and queued payouts can be canceled. The held money returns to available.

Parameters

idstring (uuid)in pathrequired

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash

curl -X POST https://sandbox.api.biftpay.com/v1/payouts/{id}/cancel \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

200
The canceled payoutPayout
Fields
idstring (uuid)required
Also the reference sent to the bank.
object"payout"required
livemodebooleanrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
total_debitedintegerrequired
amount + fee + vat
at least 0
currencyNGN | USDrequired
statusawaiting_approval | queued | processing | paid | failed | canceledrequired
awaiting_approval (Biftpay is reviewing it first, e.g. a large amount) -> queued -> processing (sent, waiting for the bank's confirmation) -> paid or failed. canceled is only possible before sending.
narrationstring | null
brandstring (uuid)
The brand whose balance pays it.
review_reasonsarray of amount | new_bank_account | account_review | security_change | unusual
Why Biftpay is checking it before it's sent (status awaiting_approval); empty otherwise. new_bank_account - the first payout to an account added in the last 24 hours; account_review - the business or brand is under review, or several disputes arrived this week; security_change - a password or authenticator change by the requester, or a settlement account change, in the last 24 hours; unusual - far larger than this merchant has paid out before, or most of the balance after 30 quiet days; amount - over an approval threshold Biftpay set for this merchant.
bank_accountobjectrequired
Fields of bank_account
idstring (uuid)required
bank_namestringrequired
account_number_last4stringrequired
account_namestringrequired
approved_atstring (date-time) | null
failure_codestring | null
created_atstring (date-time)required
paid_atstring (date-time) | null
failed_atstring (date-time) | null
canceled_atstring (date-time) | null
404
Not found, or not visible to this key
409
The object is in a state that doesn't allow this

What a payout would cost, and whether the balance covers it

get/v1/payouts/quote

The fee and VAT go on top of the amount and come from the same available balance (the brand's, with brand). max_amount is the most that can be paid out now. Creating the payout checks again.

Parameters

amountintegerin queryrequired

at least 1

currencyNGNin query

brandstring (uuid)in query

bash

curl https://sandbox.api.biftpay.com/v1/payouts/quote \
  -H "Authorization: Bearer bp_test_..."

Responses

200
The quoteobject
Fields
object"payout_quote"required
currencyNGNrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
total_debitedintegerrequired
Minor units (kobo, cents).
at least 0
availableintegerrequired
Minor units (kobo, cents).
at least 0
max_amountintegerrequired
Minor units (kobo, cents).
at least 0
max_reasonbalance | per_payout | dailyrequired
What holds max_amount where it is.
sufficientbooleanrequired
The balance covers amount + fee + VAT.
within_limitsbooleanrequired
limitsobjectrequired
Fields of limits
tierstringrequired
custombooleanrequired
per_payoutintegerrequired
dailyintegerrequired
used_todayintegerrequired
400
Invalid request

USDT settlement: whether it's on, Biftpay's rules, your wallets and the one automatic settlement uses

get/v1/usdt

bash

curl https://sandbox.api.biftpay.com/v1/usdt \
  -H "Authorization: Bearer bp_test_..."

Responses

200
OKobject
Fields
object"usdt"required
enabledbooleanrequired
settle_walletstring | nullrequired
settingsUsdtSettingsrequired
Fields of settings
enabledbooleanrequired
cooling_hoursintegerrequired
min_usdintegerrequired
max_usdinteger | nullrequired
updated_bystringrequired
updated_atstring (date-time)required
walletsarray of CryptoWalletrequired
Fields of wallets
idstring (uuid)required
object"crypto_wallet"required
asset"USDT"required
networktron | ethereum | polygon | bscrequired
network_labelstringrequired
addressstringrequired
labelstring | nullrequired
usablebooleanrequired
Past the cooling-off period: can receive payouts.
usable_fromstring (date-time)required
created_atstring (date-time)required

Before sending: dollars available, the fee, and the USDT the wallet should receive

get/v1/usdt/preview

Parameters

usd_amountintegerin query

Cents.

at least 1

brandstring (uuid)in query

bash

curl https://sandbox.api.biftpay.com/v1/usdt/preview \
  -H "Authorization: Bearer bp_test_..."

Responses

200
OKUsdtPreview
Fields
object"usdt_preview"required
usd_availableintegerrequired
min_usdintegerrequired
max_usdinteger | nullrequired
available_nowbooleanrequired
USDT payouts are on and a partner is connected.
usd_amountinteger
feeinteger
vatinteger
net_usdinteger
usdt_estimatestring
USDT the wallet should receive.

Your USDT payouts, newest first

get/v1/usdt/payouts

bash

curl https://sandbox.api.biftpay.com/v1/usdt/payouts \
  -H "Authorization: Bearer bp_test_..."

Responses

200
OKobject
Fields
object"list"required
dataarray of CryptoPayoutrequired
Fields of data
idstring (uuid)required
object"crypto_payout"required
livemodebooleanrequired
walletstring (uuid)required
networkstring
addressstring
usd_amountintegerrequired
feeintegerrequired
vatintegerrequired
net_usdintegerrequired
usdt_amountstring | nullrequired
USDT the wallet received, as the partner reports it.
statusqueued | processing | paid | failedrequired
tx_hashstring | nullrequired
The on-chain transaction.
failure_codestring | nullrequired
created_atstring (date-time)required
paid_atstring (date-time) | nullrequired
has_morebooleanrequired

Send dollars as USDT to one of your wallets (added and cleared in the dashboard)

post/v1/usdt/payouts

The amount (cents) leaves your USD balance; Biftpay's fee and VAT come out of it and the partner sends the rest as USDT, 1 USDT per dollar. Held until the partner confirms, returned if it fails.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

usd_amountintegerrequired

at least 1

walletstring (uuid)required

brandstring (uuid)

otpobject or object

bash

curl -X POST https://sandbox.api.biftpay.com/v1/usdt/payouts \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "usd_amount": 1,
    "wallet": "…"
  }'

Responses

201
QueuedCryptoPayout
Fields
idstring (uuid)required
object"crypto_payout"required
livemodebooleanrequired
walletstring (uuid)required
networkstring
addressstring
usd_amountintegerrequired
feeintegerrequired
vatintegerrequired
net_usdintegerrequired
usdt_amountstring | nullrequired
USDT the wallet received, as the partner reports it.
statusqueued | processing | paid | failedrequired
tx_hashstring | nullrequired
The on-chain transaction.
failure_codestring | nullrequired
created_atstring (date-time)required
paid_atstring (date-time) | nullrequired
400
Invalid request
409
The object is in a state that doesn't allow this