Biftpaydocs
Dashboard

Balance

Retrieve balances

get/v1/balance

Read straight from the ledger. One entry per currency in each bucket. Each brand holds its own money; without brand this is the whole business (the sum of its brands).

Parameters

brandstring (uuid)in query

One brand's own money (default: the whole business)

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

Responses

  • 200
    Current balancesBalance
    Fields
    object"balance"required
    livemodebooleanrequired
    brandstring (uuid) | null

    The brand asked for; null for the whole business

    pendingarray of BalanceAmountrequired

    Captured, not yet settleable.

    Fields of pending
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    availablearray of BalanceAmountrequired

    Can be paid out.

    Fields of available
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    reservearray of BalanceAmountrequired

    Rolling reserve held against chargebacks.

    Fields of reserve
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    payout_in_flightarray of BalanceAmountrequired

    Sent to a bank, not yet confirmed.

    Fields of payout_in_flight
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    refund_in_flightarray of BalanceAmount

    Being refunded to customers, not yet confirmed by the provider.

    Fields of refund_in_flight
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    dispute_holdarray of BalanceAmount

    Held while a dispute is decided.

    Fields of dispute_hold
    currencyNGN | USDrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

  • 400
    Invalid request
  • 401
    Missing or invalid API key

Every movement on the merchant's balances, newest first

get/v1/balance_transactions

One row per ledger line on the merchant's accounts. amount is signed in the merchant's terms: positive adds to bucket, negative takes from it; balance_after is that bucket's balance after the line. Payment lines carry gross and fee (fee plus VAT). Lines of one entry share type and created_at. Paginate with starting_after=<id>.

Parameters

limitintegerin query

1 to 100 · default 20

starting_afterstringin query
brandstring (uuid)in query

One brand's own money (default: the whole business)

currencyNGN | USDin query
bucketavailable | pending | reserve | payout_in_flight | refund_in_flight | dispute_holdin query
typestringin query

Comma-separated: payments, releases, payouts, refunds, disputes, conversions (corrections included).

fromstring (date)in query

Inclusive, Lagos time

tostring (date)in query

Inclusive, Lagos time

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

Responses

  • 200
    A page of balance transactionsBalanceTransactionList
    Fields
    object"list"required
    dataarray of BalanceTransactionrequired
    Fields of data
    idstringrequired
    object"balance_transaction"required
    typestringrequired

    e.g. charge.capture, charge.release, payout.hold, payout.settle, refund.hold

    descriptionstringrequired
    bucketpending | available | reserve | payout_in_flight | refund_in_flight | dispute_holdrequired
    amountintegerrequired

    Signed; positive adds to the bucket.

    balance_afterintegerrequired

    The bucket's balance after this line.

    grossinteger

    Payments only: what the customer paid.

    feeinteger

    Payments only: Biftpay's fee plus VAT, taken from gross.

    currencyNGN | USDrequired
    source_idstring | null

    The payment, payout or refund that caused it.

    created_atstring (date-time)required
    has_morebooleanrequired
  • 400
    Invalid request
  • 401
    Missing or invalid API key

The statement as CSV (up to 20,000 lines; narrow the dates for more)

get/v1/balance_transactions/export

Same filters as the list. The CSV comes in data, for a dashboard to save as file_name.

Parameters

brandstring (uuid)in query

One brand's own money (default: the whole business)

currencyNGN | USDin query
bucketavailable | pending | reserve | payout_in_flight | refund_in_flight | dispute_holdin query
typestringin query

Comma-separated: payments, releases, payouts, refunds, disputes, conversions (corrections included).

fromstring (date)in query

Inclusive, Lagos time

tostring (date)in query

Inclusive, Lagos time

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

Responses

  • 200
    The statementobject
    Fields
    object"statement_export"required
    file_namestringrequired
    content_type"text/csv"required
    rowsintegerrequired
    truncatedbooleanrequired

    More lines matched than one export holds.

    datastringrequired

    CSV text

  • 400
    Invalid request
  • 401
    Missing or invalid API key

Your rolling reserve - terms, what's held, and when it's released

get/v1/reserve

A rolling reserve holds a share of each payment for a set time against chargebacks. terms is null when none applies. Held money is released to available automatically, on the dates in releases (Lagos days).

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

Responses

  • 200
    OKobject
    Fields
    object"reserve"required
    livemodebooleanrequired
    termsobject | nullrequired
    Fields of terms
    percent_bpsintegerrequired
    daysintegerrequired
    reasonstring | nullrequired
    reason_textstring | nullrequired

    The reason in plain words.

    notestring | nullrequired
    sincestring (date-time) | nullrequired
    heldarray of objectrequired
    Fields of held
    currencystringrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    paymentsintegerrequired
    next_release_atstring (date-time) | nullrequired
    releasesarray of objectrequired
    Fields of releases
    datestring (date)required
    currencystringrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

Biftpay's dollar rate, the dollars available to convert, and (with usd_amount) the naira they'd give

get/v1/fx

Parameters

brandstring (uuid)in query
usd_amountintegerin query

Cents.

at least 1

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

Responses

  • 200
    OKFxPreview
    Fields
    object"fx_preview"required
    rateFxRate or nullrequired
    usd_availableintegerrequired
    min_usdintegerrequired
    max_usdintegerrequired

    The most that can convert now (balance, maximum and today's cap).

    daily_cap_usdinteger | nullrequired
    converted_today_usdintegerrequired
    blockedconversions_paused | no_rate | rate_stale | balance_below_minimum | daily_cap_reached | nullrequired
    usd_amountinteger
    ngn_amountinteger

    The naira usd_amount gives at this rate (rounded down).

Your dollar-to-naira conversions, newest first

get/v1/fx/conversions

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

Responses

  • 200
    OKobject
    Fields
    object"list"required
    dataarray of FxConversionrequired
    Fields of data
    idstring (uuid)required
    object"fx_conversion"required
    livemodebooleanrequired
    usd_amountintegerrequired
    ratestringrequired
    ngn_amountintegerrequired
    brandstring | nullrequired
    sourcemerchant | auto | staffrequired
    payoutstring | nullrequired
    created_atstring (date-time)required
    has_morebooleanrequired

Convert dollars to naira at the rate you were shown

post/v1/fx/conversions

rate_id is the rate from GET /v1/fx. If Biftpay has published a new rate since, nothing converts and the error says the new rate (rate_changed). Naira is rounded down to the kobo.

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

Cents.

at least 1

rate_idstring (uuid)required
brandstring (uuid)
bash
curl -X POST https://sandbox.api.biftpay.com/v1/fx/conversions \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "usd_amount": 1,
    "rate_id": "…"
  }'

Responses

  • 201
    ConvertedFxConversion
    Fields
    idstring (uuid)required
    object"fx_conversion"required
    livemodebooleanrequired
    usd_amountintegerrequired
    ratestringrequired
    ngn_amountintegerrequired
    brandstring | nullrequired
    sourcemerchant | auto | staffrequired
    payoutstring | nullrequired
    created_atstring (date-time)required
  • 400
    Invalid request
  • 409
    The object is in a state that doesn't allow this