Skip to main content
​
Breaking

​
Business API: new response format

We’re simplifying Business API responses and error codes. The API reference shows the new format. Field and error code changes reach your integration on your cutoff date, which we’ll send you by email. A smaller set of changes applies to every integration straight away, and they’re listed below.Renamed error codesThe type URL in these errors changes to match, and the feature_key for card KYC errors becomes card_kyc_enabled. Three internal card failure_code values (retry_declined, V1_NEGATIVE_FROZEN, and SUPERSEDED_BY_LINKED_TERMINATION_CREDIT) become OPERATION_FAILED.Renamed fieldOn virtual account transactions, ledger_transaction_id is replaced by transaction_id, which works with Get a transaction. The virtual_account.deposit.success webhook keeps all its current fields.Removed fieldsMetadatametadata stays on transactions and virtual account transactions, but internal keys are removed from it, including ledger ID keys, account_id, company_id, hold_stage, source_wallet, and idempotency_key_basis. All other keys stay the same.Proxy a JSON-RPC call to a node errors will contain only code and message. Card termination_reason text that mentions a partner is replaced with a general message.Applies straight awayThese changes don’t wait for your cutoff date:
  • metadata keys starting with provider, and internal staff and repair keys, are removed.
  • transaction_id is added to virtual account transactions and the virtual_account.deposit.success webhook.
  • Several messages are clearer, including failure_reason on payout webhooks and card transactions. Raw internal text is replaced with a safe message.
  • Conversion failure_reason only appears on failed conversions.
  • Internal repair notes are removed from card transaction descriptions, and a description naming a partner is removed.
  • The PROVIDER_ERROR title becomes Processing Error, and extensions.provider is removed.
Don’t match on message wording: use error codes and statuses instead.
​
Improved

​
Deprecated endpoints left the API reference

Deprecated endpoints are no longer in the API reference. They still work, and their old pages redirect to the replacement where there is one. If you still call one, move to its replacement. Create a lite card and Get a payout by reference have no replacement yet.
​
New

​
Business API reference: full endpoint coverage

The Business API reference now covers all 129 endpoints in the published spec, up from 69. These are newly documented:The reference also lists 19 deprecated aliases, marked as deprecated on their pages, each pointing to the endpoint that replaces it. Three endpoints that were already documented are now deprecated:Most endpoint pages have new titles. Their URLs haven’t changed.
​
New

​
Enterprise reference: full endpoint coverage

The Enterprise API reference now covers all 86 endpoints in the published spec, up from 42. These groups are newly documented:Existing groups also gained endpoints: wallet signing and sign logs, UTXOs and per-asset balances, transaction fee estimates, and webhook event types. Gas station pages moved to /api-reference/platform/gasstations/, and the old URLs redirect.
​
New

​
Choose the bank for virtual accounts

Create virtual account takes an optional bank field: nomba (Nombank MFB) or globus (Globus Bank). Leave it out and the account opens at the default bank, currently Nomba. A customer can hold accounts at both banks, or several at one bank, as long as each request uses a new reference. bank_name returns the issuing bank, and is always Sandbox Bank in sandbox. Any other value fails with bank must be one of: nomba, globus.
​
Breaking

​
Lite cards require Card KYC

Create lite card now requires approved Card KYC for the cardholder. Verify the customer with Card KYC first, then pass the returned customer_id. Three new fields are also required: card_brand, swipe_count, and terminate_date. Requests without approved KYC or these fields are rejected.
​
New

​
Card KYC

Cardholders are verified through the new Card KYC endpoint before a card can be issued. Submit the customer to POST /api/cards/kyc first. Approval returns a customer_id, which you then pass to Create card. Card KYC is enabled per account.
​
New

​
Virtual Accounts API

Virtual accounts are dedicated Nigerian bank account numbers issued against one of your customers. Deposits credit your NGN balance, which Get Balances already returns.Two requirements before you call create:
  • The customer must already carry a BVN, meaning an id_type of bvn, plus date of birth and contact details.
  • reference acts as the idempotency key, so reuse it when you retry.
​
New

​
Webhook source IPs published

The webhook reference pages for addresses, virtual cards, payouts, withdrawals, and beneficiaries now list the addresses Bitnob sends webhooks from, 18.171.51.218 and 13.134.154.133, with an nginx allow and deny example on each page.These addresses can change. Treat the allowlist as a network convenience rather than a security boundary, and verify the x-bitnob-signature header on every event.
​
Breaking

​
Payout webhooks reference

The events emitted across the payout flow of quote, initialize, and finalize are now documented.Two things to note when you handle these events:
  • Each event carries the payout record itself, so field names match the payouts API response, including quote_id, settlement_amount, from_asset, and the nested beneficiary object. This replaces the legacy payout.transfer.* shape.
  • data.status is the event outcome in lower case, one of initiated, processing, success, or expired. It is not the payout record’s upper case lifecycle status returned by Get Payout, so branch on the event field.
​
New

​
Interactive API playground

Supported API reference sections now include a Try it out panel that sends real, HMAC-signed requests and shows the live response.
  • As you fill in the path, query, and body fields, the panel builds a syntax-highlighted cURL command you can copy and run as is.
  • For POST, PUT, and PATCH endpoints, a Raw body tab accepts your own JSON payload. The exact bytes you paste are signed and sent verbatim, and they persist across page refreshes.
  • You enter your API credentials once. Timestamps, nonces, and signatures are generated on each run.
​
New

​
Page assistance menu

API reference pages now carry a Page Assistance menu with four actions.Every action operates on the whole page.
​
New

​
Stablecoin webhooks reference

New stablecoin webhook pages under the Addresses and Withdrawal sections document the deposit.success, transfer.success, and transfer.failed events.Each page covers signature verification with HMAC SHA512 through the x-bitnob-signature header, notification retries, local testing, and the full payload field reference with sample payloads.
​
Breaking

​
Card webhooks v2

Every outbound virtual card webhook moved to a new payload shape.Cross-border transactions emit two variants, cross_border_pending for the company wallet fee debit and cross_border_settled for the card balance principal debit. Both are transactionType values, which stay snake_case. Contactless and refund events also fire with several transactionType values under one event string, so branch on event first and then on transactionType.
​
Improved

​
Webhook payloads: top-level event_id

Webhook payloads for card top-up, card withdrawal, stablecoin transfer, and stablecoin deposit events now include a top-level event_id, which makes de-duplication and tracing easier. The transfer.success event also includes transaction_id in its data payload.
​
New

​
Card Issuing API v2 beta

New card creation endpoints are available, with support for physical cards, custom BIN ranges, and 3D Secure.
​
New

​
Virtual Cards API v2

The Virtual Cards API is now resource-oriented.New endpoints cover extended card details, spending limit controls, and customer cards lookup.
​
Breaking

​
Legacy Virtual Cards endpoints removed

Everything under /api/virtualcards is no longer supported. Card operations require an explicit cardId path parameter instead of implicit context, and the user-based model is replaced by a customer-centric model keyed on customerId.Update your integration to the new namespaces before upgrading.