> ## Documentation Index > Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com. > Always use the sandbox environment for testing. Never put live API keys in sample code. > Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats. > Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry. > Quotes expire. Re-quote rather than reusing a stale quote id. # Create a card > Issues a card for an existing customer (customer_id) or a new one (customer). Prepaid cards can be funded at creation; collateral cards need the customer approved through card KYC first. The card starts as pending, and the card.created webhook follows when it is ready. ## OpenAPI ````yaml /api-collections/swagger/bitnob-api-v2.openapi.json post /api/cards openapi: 3.1.0 info: description: >- The Bitnob API for businesses: customers, virtual accounts, cards, payouts, crypto addresses and transfers, Lightning, trading and exchange rates. ## Authentication Every request is signed with your API key's client id and secret. **Signed requests (recommended).** Send: - `X-Auth-Client`: your client id - `X-Auth-Timestamp`: the current Unix time in seconds; requests more than 5 minutes off are refused - `X-Auth-Nonce`: a unique random string for this request - `X-Auth-Signature`: hex HMAC-SHA256 of `{client_id}:{timestamp}:{nonce}:{body}` using your secret, where body is the raw request body (empty for GET) **Secret mode.** Send `X-Auth-Client` and `X-Auth-Secret` instead. Simpler, but the secret travels with every request. Live keys work only for an active organisation; sandbox keys work at any time. `ANY /api/whoami` echoes the authenticated client and is the quickest way to check your signing. ## Responses Successful responses are wrapped in an envelope with `success`, `message`, `data` and, on lists, `metadata`. Errors come either as the envelope with `success: false` and an `error` object, or as an RFC 7807 problem with a machine-readable `code`; branch on the code. Every response carries an `X-Correlation-ID` header; errors repeat it as `request_id`. Quote it to support. Every request passes a per-IP rate limit of 500 requests a minute (429 with `Retry-After`). This document is maintained by hand and checked against the route table on every build: every /api route is listed here. title: Bitnob API version: 1.0.0 servers: - description: Production url: https://api.bitnob.com security: - BitnobClientId: [] BitnobClientSecret: [] tags: - description: Check that your requests are signed correctly. name: Authentication - description: >- The people and businesses you serve. Creating and editing them needs the customers feature. name: Customers - description: >- Naira accounts that receive bank transfers, for your company or for a customer. name: Virtual accounts - description: Crypto deposit addresses, for your company or for a customer. name: Addresses - description: >- Virtual cards: issue, fund, withdraw, freeze, terminate, and the card KYC and corporate onboarding behind them. name: Cards - description: 'Pay out to bank accounts and mobile money: quote, initialize, finalize.' name: Payouts - description: Saved payout recipients. name: Beneficiaries - description: Banks and account lookups for payouts. name: Banks - description: Balance transfers between Bitnob organisations. name: Transfers - description: Crypto withdrawals. name: Withdrawals - description: Lightning invoices and payments. name: Lightning - description: Lightning addresses, LNURL withdraw links and LNURL payments. name: LNURL - description: Blockchain node access. name: Nodes - description: Quotes and orders for buying and selling. name: Trading - description: Rates and conversions. name: Exchange rates - description: Your transaction history. name: Transactions - description: Wallet balances. name: Balances paths: /api/cards: post: tags: - Cards summary: Create a card description: >- Issues a card for an existing customer (customer_id) or a new one (customer). Prepaid cards can be funded at creation; collateral cards need the customer approved through card KYC first. The card starts as pending, and the card.created webhook follows when it is ready. operationId: cardsCreate requestBody: content: application/json: examples: collateral_existing_customer: summary: Collateral card for a KYC-approved customer, one monthly limit value: card_brand: visa card_limits: monthly_limit: 1000000000 card_program: collateral card_type: virtual customer_id: 019a3b5c-3e5f-7a1b-8c2d-4e5f6a7b8c63 reference: ref_sbx_c0l1a7e2 webhook_url: https://example.com/webhooks/cards prepaid_inline_customer: summary: Prepaid card for a new customer, funded with $10 value: amount: 10000000 card_brand: visa card_limits: daily_limit: 500000000 transaction_limit: 100000000 card_program: prepaid card_type: virtual currency: USD customer: city: Lagos country: NGA customer_type: individual date_of_birth: '1990-04-12' dial_code: '+234' email: adaeze.okafor@example.com first_name: Adaeze id_number: '00000000000' id_type: NIN last_name: Okafor line1: 12 Admiralty Way phone_number: '8000000001' postal_code: '106104' state: Lagos name: Adaeze Okafor reference: ref_sbx_4f9c2a71 user_metadata: '{"employee_id":"E-1042"}' webhook_url: https://example.com/webhooks/cards schema: $ref: '#/components/schemas/CardsCreateRequest' required: true responses: '201': content: application/json: examples: collateral_card: summary: Collateral card accepted, still provisioning value: data: card: available_actions: [] balance_amount: '0' balance_breakdown: null balance_currency: USD billing_address: city: Lagos country: NGA line1: 12 Admiralty Way line2: Lekki Phase 1 postal_code: '106104' state: Lagos business_spend: null card_brand: visa card_limits: monthly_limit: '1000000000' card_program: collateral card_type: virtual company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 contactless_payment: false created_at: '2026-10-30T09:15:02Z' created_by: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 created_status: processing customer_id: 019a3b5c-3e5f-7a1b-8c2d-4e5f6a7b8c63 display_amount: 0 first_six_digit: '000000' id: 019a3b5c-2c4d-7e6f-8a9b-0c1d2e3f4a51 masked_pan: '' name: Tunde Bakare nickname: '' reference: ref_sbx_c0l1a7e2 status: pending updated_at: '2026-10-30T09:15:02Z' user_metadata: '{}' webhook_url: https://example.com/webhooks/cards message: Card created successfully success: true timestamp: '2026-10-30T09:15:02.481Z' prepaid_card: summary: Prepaid card accepted, still provisioning value: data: card: available_actions: [] balance_amount: '0' balance_breakdown: null balance_currency: USD billing_address: city: Miami country: United States line1: 3401 N. Miami, Ave. Ste 230 line2: '' postal_code: '33127' state: Florida business_spend: null card_brand: visa card_limits: daily_limit: '500000000' transaction_limit: '100000000' card_program: prepaid card_type: virtual company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 contactless_payment: false created_at: '2026-10-30T09:15:02Z' created_by: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 created_status: processing customer_id: 019a3b5c-3e5f-7a1b-8c2d-4e5f6a7b8c61 display_amount: 0 first_six_digit: '000000' id: 019a3b5c-2c4d-7e6f-8a9b-0c1d2e3f4a51 masked_pan: '' name: Adaeze Okafor nickname: '' reference: ref_sbx_4f9c2a71 status: pending updated_at: '2026-10-30T09:15:02Z' user_metadata: '{"employee_id":"E-1042"}' webhook_url: https://example.com/webhooks/cards message: Card created successfully success: true timestamp: '2026-10-30T09:15:02.481Z' schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: $ref: '#/components/schemas/CardsCardResponse' type: object description: Created '400': content: application/json: examples: amount_below_minimum: summary: Initial funding below $2 value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00aa detail: amount below minimum funding of $2 request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00aa status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR company_insufficient_balance: summary: The company balance cannot cover the initial funding and fee value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a6 detail: >- Insufficient company balance for card creation: required 10.50, available 4.00 USD extensions: available: '4.00' company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 currency: USD error_code: COMPANY_INSUFFICIENT_BALANCE required: '10.50' request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a6 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR field_validation: summary: A field fails validation value: error: code: BAD_REQUEST details: card_type: 'Card type must be one of: virtual physical' email: Email must be a valid email address message: Validation failed request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a3 success: false timestamp: '2026-10-30T09:15:02.481Z' invalid_body: summary: The body is not valid JSON value: error: code: BAD_REQUEST message: Invalid request body request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a2 success: false timestamp: '2026-10-30T09:15:02.481Z' invalid_expiry: summary: expiry is not YYYY-MM value: error: code: BAD_REQUEST message: expiry must be in YYYY-MM format request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a5 success: false timestamp: '2026-10-30T09:15:02.481Z' kyc_required: summary: Collateral card for a customer not yet approved by card KYC value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a8 detail: >- KYC verification required before issuing this card (status=pending) request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a8 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR max_active_cards: summary: >- The customer already holds the maximum number of active cards value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a7 detail: customer already has 3 active cards, maximum is 3 request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a7 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR name_required: summary: Neither name nor customer_id was sent value: error: code: BAD_REQUEST message: name is required unless customer_id is provided request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a4 success: false timestamp: '2026-10-30T09:15:02.481Z' collateral_initial_funding: summary: amount sent on a collateral card value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a9 detail: >- initial funding is not supported for collateral cards; create with amount=0 and fund the card afterwards request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00a9 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- The request is invalid. Body and field checks answer with the envelope (BAD_REQUEST); the card service answers with a Problem (VALIDATION_ERROR), which also covers an unfunded company (extensions.error_code COMPANY_INSUFFICIENT_BALANCE), a customer at the active-card maximum and a collateral-card customer not yet approved by card KYC. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '401': $ref: '#/components/responses/Unauthorized' '403': content: application/json: examples: card_creation_off: summary: Card issuance is switched off for the company value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0092 detail: The card creation feature is currently not available. extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 feature_key: card_creation_enabled request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0092 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Feature Not Enabled type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED customer_cards_off: summary: >- The holder is a customer of the company and customer cards are off value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0095 detail: >- The cards for customers feature is currently not available. extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 feature_key: customer_cards request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0095 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Feature Not Enabled type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED customers_off: summary: The customers product is off for the company value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0096 detail: The customers feature is currently not available. extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 feature_key: customers request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0096 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Feature Not Enabled type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED ip_not_whitelisted: $ref: '#/components/examples/IPNotWhitelisted' org_not_active: $ref: '#/components/examples/OrgNotActive' org_not_active_live: $ref: '#/components/examples/OrgNotActiveLive' personal_workspace_customers: $ref: '#/components/examples/PersonalWorkspaceCustomers' virtual_cards_off: summary: The company does not have virtual cards value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0091 detail: The virtual cards feature is currently not available. extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 feature_key: virtual_cards request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f0091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Feature Not Enabled type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- On a personal account any customer but the owner, and any new customer, is refused (PERSONAL_WORKSPACE_CUSTOMERS). The org is not active (ORG_NOT_ACTIVE, envelope), the company does not have virtual cards or card creation (FEATURE_NOT_ENABLED), or the card is for a customer of the company while the customers or customer_cards feature is off (FEATURE_NOT_ENABLED). Own use (a team_member customer, or an individual workspace's own customer) is always allowed. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '408': $ref: '#/components/responses/RequestTimeout' '409': content: application/json: examples: duplicate_reference: summary: The reference is already taken value: code: ALREADY_EXISTS correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ab detail: card with reference 'ref_sbx_4f9c2a71' already exists extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 field: reference resource: card value: ref_sbx_4f9c2a71 request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ab status: 409 timestamp: '2026-10-30T09:15:02Z' title: Resource Already Exists type: https://api.bitnob.com/errors/ALREADY_EXISTS schema: $ref: '#/components/schemas/Problem' description: >- reference was already used for another card of this company (ALREADY_EXISTS). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '422': content: application/json: examples: program_disabled: summary: card_program is not enabled for the company value: code: CARD_STATE_CONFLICT correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ac detail: card program "collateral" is not enabled for this company request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ac status: 422 timestamp: '2026-10-30T09:15:02Z' title: Card Program Disabled type: https://api.bitnob.com/errors/CARD_STATE_CONFLICT self_kyc_required: summary: Individual workspace owner has not started card KYC value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ad detail: >- verify your identity for cards first: start card KYC, then create the card extensions: error_code: CARD_KYC_REQUIRED request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f00ad status: 422 timestamp: '2026-10-30T09:15:02Z' title: Card verification required type: https://api.bitnob.com/errors/PRECONDITION_FAILED schema: $ref: '#/components/schemas/Problem' description: >- The card program is not enabled for this company (CARD_STATE_CONFLICT), or an individual workspace asked for a card before its owner started card KYC (PRECONDITION_FAILED, error_code CARD_KYC_REQUIRED). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' '503': content: application/json: examples: auth_service_busy: $ref: '#/components/examples/AuthServiceBusy' auth_service_unavailable: $ref: '#/components/examples/AuthServiceUnavailable' card_service_unavailable: summary: The card service is not reachable value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f009b detail: >- Service is temporarily unavailable. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f009b status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE limits_unavailable: $ref: '#/components/examples/LimitsUnavailable' issuer_failed: summary: The card issuer refused or failed the call value: code: EXTERNAL_SERVICE_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f009a detail: An internal error occurred. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f009a status: 503 timestamp: '2026-10-30T09:15:02Z' title: Card Operation Failed type: https://api.bitnob.com/errors/EXTERNAL_SERVICE_ERROR schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- Temporarily unavailable; retry later. The identity service could not check the credentials, the card issuer is unreachable, or the tier limits could not be read (LIMITS_UNAVAILABLE). headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' components: schemas: CardsCreateRequest: properties: amount: description: Initial funding, micro-units (1 USD = 1,000,000). format: int64 minimum: 0 type: integer card_brand: enum: - visa - mastercard type: string description: Card network. card_limits: $ref: '#/components/schemas/CardsCardLimitsInput' card_program: description: Defaults to the company's program when omitted. enum: - prepaid - collateral - collateral_business type: string card_type: enum: - virtual - physical type: string description: Form of the card. contactless_payment: type: boolean description: Whether the card allows contactless payments. currency: type: string description: Card currency. customer: $ref: '#/components/schemas/CardsCustomerInfo' customer_id: description: Existing customer. Provide this or customer. format: uuid type: string expiry: description: Requested expiry month, YYYY-MM. Refused on collateral programs. pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ type: string idempotency_key: type: string description: >- A UUID that makes a retry safe. One is generated if you leave it out. name: description: Cardholder name. Required unless customer_id is given. maxLength: 100 type: string reference: type: string description: Your unique reference for this card. user_metadata: description: JSON object as a string, at most 5KB. maxLength: 5120 type: string webhook_url: format: uri type: string description: HTTPS URL that receives webhooks for this card. required: - card_type type: object Envelope: description: >- Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead. properties: data: description: >- The payload; its shape is given per operation. Omitted when there is none. error: $ref: '#/components/schemas/ErrorInfo' message: description: Human-readable summary; omitted when empty. type: string metadata: $ref: '#/components/schemas/Pagination' request_id: description: >- Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support. type: string success: description: true on success type: boolean timestamp: description: When the response was written. format: date-time type: string required: - success - timestamp type: object CardsCardResponse: properties: card: $ref: '#/components/schemas/CardsCard' type: object ErrorEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - properties: success: const: false required: - error type: object description: >- The envelope as an error: success is false, error is set, data is absent. Problem: description: >- RFC 7807 problem. Returned when authentication fails and for errors raised by the services behind a handler (validation, domain refusals such as FEATURE_NOT_ENABLED or PRECONDITION_FAILED, partner outages); branch on code. properties: code: description: >- Machine-readable; branch on this, not on the status or the wording. For example VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_NOT_ENABLED, PERSONAL_WORKSPACE_CUSTOMERS, TIER_PRODUCT_LOCKED, NOT_FOUND, DUPLICATE_KEY_ERROR, ALREADY_EXISTS, PRECONDITION_FAILED, INSUFFICIENT_FUNDS, TIER_LIMIT_REACHED, RATE_LIMIT_EXCEEDED, TIMEOUT, SERVICE_UNAVAILABLE, LIMITS_UNAVAILABLE, PLATFORM_PAUSED, INTERNAL_ERROR. type: string correlation_id: description: >- The request's correlation id, the same value as the X-Correlation-ID response header. type: string detail: description: >- What went wrong for this request, safe to show; internal and partner failures carry a generic sentence. type: string extensions: additionalProperties: true description: >- Code-specific facts, for example feature_key (FEATURE_NOT_ENABLED), field or field_violations (VALIDATION_ERROR), rail, window, limit, used, requested and remaining (TIER_LIMIT_REACHED), scope (PLATFORM_PAUSED). type: object instance: type: string request_id: description: Equal to correlation_id. type: string status: description: The HTTP status, repeated. type: integer timestamp: format: date-time type: string title: description: >- Short summary of the code, for example Validation Error or Feature Not Enabled. type: string type: description: https://api.bitnob.com/errors/{code} format: uri type: string required: - type - title - status - code - timestamp type: object CardsCardLimitsInput: description: >- Spending limits in micro-units (1 USD = 1,000,000). Card program rules (for example a single limit) are enforced by the service. properties: all_time_limit: description: Lifetime, micro-units. format: int64 minimum: 0 type: integer daily_limit: description: Per day, micro-units. format: int64 minimum: 0 type: integer monthly_limit: description: Per month, micro-units. format: int64 minimum: 0 type: integer transaction_limit: description: Per transaction, micro-units. format: int64 minimum: 0 type: integer weekly_limit: description: Per week, micro-units. format: int64 minimum: 0 type: integer yearly_limit: description: Per year, micro-units. format: int64 minimum: 0 type: integer type: object CardsCustomerInfo: description: Inline customer for card creation. properties: business_name: type: string description: Registered business name. city: maxLength: 100 type: string description: City. country: description: ISO 3166-1 alpha-3 country code, for example NGA. maxLength: 3 minLength: 3 type: string customer_type: enum: - individual - business - team_member type: string description: Type of customer. date_of_birth: description: Date of birth. maxLength: 10 type: string dial_code: maxLength: 5 type: string description: International dial code, for example +234. email: format: email type: string description: Email address. first_name: maxLength: 100 type: string description: First name. id_number: maxLength: 50 type: string description: Number on the identity document. id_type: maxLength: 50 type: string description: Type of identity document. last_name: maxLength: 100 type: string description: Last name. line1: maxLength: 200 type: string description: Address line 1. line2: type: string description: Address line 2. phone_number: maxLength: 20 type: string description: Phone number without the dial code. postal_code: maxLength: 20 type: string description: Postal code. state: maxLength: 100 type: string description: State. required: - customer_type - first_name - last_name - date_of_birth - id_type - id_number - email - phone_number - dial_code - line1 - city - state - postal_code - country type: object ErrorInfo: properties: code: description: >- Machine-readable, for example BAD_REQUEST, NOT_FOUND, CONFLICT, ORG_NOT_ACTIVE, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE, INTERNAL_ERROR. type: string details: additionalProperties: true description: >- For field validation, a map of field name to message ("email": "Email must be a valid email address"); for a body that does not decode, the offending field. type: object message: type: string required: - message type: object Pagination: description: >- List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set. properties: has_more: type: boolean limit: type: integer next_cursor: description: Opaque; pass as cursor for the next page. type: string offset: type: integer page: type: integer per_page: type: integer total: type: integer total_pages: type: integer type: object CardsCard: description: A card. Optional string fields are omitted when unset. properties: available_actions: items: enum: - FUND - WITHDRAW - FREEZE - UNFREEZE - TERMINATE - UPDATE_LIMITS type: string type: array balance_amount: description: Balance, micro-units (1 USD = 1,000,000). pattern: ^-?[0-9]+$ type: string balance_breakdown: description: >- Null without a live balance read (lists, terminated cards, read failure). oneOf: - $ref: '#/components/schemas/CardsBalanceBreakdown' - type: 'null' balance_currency: type: string billing_address: oneOf: - $ref: '#/components/schemas/CardsBillingAddress' - type: 'null' business_spend: oneOf: - $ref: '#/components/schemas/CardsBusinessSpend' - type: 'null' card_brand: type: string card_limits: oneOf: - $ref: '#/components/schemas/CardsCardLimits' - type: 'null' card_program: enum: - prepaid - collateral - collateral_business type: string card_type: enum: - virtual - physical - lite type: string company_id: format: uuid type: string contactless_payment: type: boolean created_at: format: date-time type: string created_by: type: string created_status: enum: - processing - completed - failed type: string customer_id: format: uuid type: string display_amount: description: Balance in major units (USD). type: number display_spent_current_month: type: number display_topup_current_month: type: number failure_reason: type: string first_six_digit: description: >- Always "000000": the BIN is redacted on every card, including one still provisioning (empty masked_pan). type: string id: format: uuid type: string last_four_digit: type: string masked_pan: type: string name: type: string nickname: description: Company label; empty when none. type: string preferred_name: type: string reference: type: string spent_current_month: description: Present when aggregates are included, micro-units. pattern: ^-?[0-9]+$ type: string stablecoin_address: type: string stablecoin_network: type: string status: enum: - pending - active - frozen - blocked - pending_termination - terminated - failed type: string terminated_at: type: string termination_reason: type: string topup_current_month: description: Present when aggregates are included, micro-units. pattern: ^-?[0-9]+$ type: string updated_at: format: date-time type: string user_metadata: description: JSON string; "{}" when unset. type: string webhook_url: type: string required: - id - company_id - customer_id - card_type - status - created_status - masked_pan - balance_amount - balance_currency - card_program - available_actions - display_amount - contactless_payment - card_limits - nickname - business_spend - balance_breakdown - user_metadata - billing_address - created_by - created_at - updated_at type: object CardsBalanceBreakdown: description: Live split of balance_amount. properties: amount_due: description: Owed to our partner, micro-units. pattern: ^-?[0-9]+$ type: string as_of: description: When our partner was read; may be cached up to 5 minutes. format: date-time type: string available: description: Spendable now, micro-units. Equals balance_amount. pattern: ^-?[0-9]+$ type: string currency: description: ISO 4217. type: string non_withdrawable: description: Spendable but not withdrawable, micro-units. pattern: ^-?[0-9]+$ type: string pending: description: >- Authorization holds, micro-units; null when our partner does not report them. pattern: ^-?[0-9]+$ type: - string - 'null' scope: enum: - CARD - SHARED_POOL type: string withdrawable: description: Withdrawable, micro-units. pattern: ^-?[0-9]+$ type: string type: object CardsBillingAddress: properties: city: type: string country: type: string line1: type: string line2: type: string postal_code: type: string state: type: string type: object CardsBusinessSpend: description: Business card limit and spend, in cents. properties: available_to_spend: description: Cents. format: int64 type: integer limit_amount: description: Cents; 0 means no card limit. format: int64 type: integer limit_frequency: description: Empty means no card limit. type: string spent_in_period: description: Cents. format: int64 type: integer type: object CardsCardLimits: description: Set limits only; unset keys are omitted. properties: all_time_limit: description: all_time_limit, micro-units. pattern: ^-?[0-9]+$ type: string daily_limit: description: daily_limit, micro-units. pattern: ^-?[0-9]+$ type: string monthly_limit: description: monthly_limit, micro-units. pattern: ^-?[0-9]+$ type: string transaction_limit: description: transaction_limit, micro-units. pattern: ^-?[0-9]+$ type: string weekly_limit: description: weekly_limit, micro-units. pattern: ^-?[0-9]+$ type: string yearly_limit: description: yearly_limit, micro-units. pattern: ^-?[0-9]+$ type: string type: object headers: X-Correlation-ID: description: >- Generated for every request (any value the client sends is ignored); quote it to support. Errors repeat it as request_id and correlation_id. example: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 schema: type: string Retry-After: description: Seconds to wait before retrying. example: 1 schema: minimum: 0 type: integer X-RateLimit-Limit: description: Requests allowed per window by the per-IP limiter (500 a minute). example: 500 schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. example: 0 schema: type: integer X-RateLimit-Reset: description: Seconds until the window resets. example: 37 schema: type: integer responses: Unauthorized: content: application/json: examples: unauthorized_auth_failed: $ref: '#/components/examples/UnauthorizedAuthFailed' unauthorized_invalid_secret: $ref: '#/components/examples/UnauthorizedInvalidSecret' unauthorized_invalid_signature: $ref: '#/components/examples/UnauthorizedInvalidSignature' unauthorized_locked_out: $ref: '#/components/examples/UnauthorizedLockedOut' schema: $ref: '#/components/schemas/Problem' description: >- Authentication failed: a signing header is missing or malformed, the timestamp is more than 5 minutes off, the signature or secret is wrong, or the client is locked out after failed checks (UNAUTHORIZED). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' RequestTimeout: content: application/json: examples: request_timeout: $ref: '#/components/examples/RequestTimeout' schema: $ref: '#/components/schemas/Problem' description: >- The request ran past its deadline (TIMEOUT); retry, with the same reference for writes. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' TooManyRequests: content: application/json: examples: rate_limited: $ref: '#/components/examples/RateLimited' rate_limited_envelope: $ref: '#/components/examples/RateLimitedEnvelope' schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- Rate limited. The per-IP limiter (500 requests a minute) answers with a Problem and Retry-After; operation-specific throttles answer with the envelope. headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' ServerError: content: application/json: examples: internal_error: $ref: '#/components/examples/InternalError' internal_error_envelope: $ref: '#/components/examples/InternalErrorEnvelope' internal_error_unhandled: $ref: '#/components/examples/InternalErrorUnhandled' schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- Something failed on our side; safe to retry idempotent requests (INTERNAL_ERROR). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' examples: IPNotWhitelisted: summary: The request came from an IP not on the key's allowlist value: code: FORBIDDEN correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: IP address not whitelisted request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Forbidden type: https://api.bitnob.com/errors/FORBIDDEN OrgNotActive: description: Live keys only; sandbox requests pass. summary: A money-moving operation from an organisation that is not active value: error: code: ORG_NOT_ACTIVE message: >- Your organisation is not currently active. Please contact your administrator. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' OrgNotActiveLive: description: Sandbox keys are never refused this way. summary: A live key on an organisation that is not active yet value: error: code: ORG_NOT_ACTIVE message: >- Your business isn't active yet, so live isn't available. Use your sandbox keys until it's activated. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' PersonalWorkspaceCustomers: description: >- A personal (individual) account has no customers but its owner. Creating a customer, or naming any customer other than the owner's own record, is refused whatever the organisation's enabled features say. summary: A personal account acting for someone other than its owner value: code: PERSONAL_WORKSPACE_CUSTOMERS correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: A personal account can only act for its owner. extensions: company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01 request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Not Available On A Personal Account type: https://api.bitnob.com/errors/PERSONAL_WORKSPACE_CUSTOMERS AuthServiceBusy: description: 'Sent with Retry-After: 1.' summary: Too many large signed bodies are being checked at once value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Authentication service is busy, retry shortly request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE AuthServiceUnavailable: description: 'Sent with Retry-After: 1. The detail is worded exactly like this today.' summary: The identity service could not be reached to check the credentials value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Service Authentication service unavailable is currently unavailable request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE LimitsUnavailable: summary: The tier limit check could not run value: code: LIMITS_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- We could not verify your account limits right now. Please try again shortly. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Limits Unavailable type: https://api.bitnob.com/errors/LIMITS_UNAVAILABLE UnauthorizedAuthFailed: description: >- Returned when X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce or X-Auth-Signature is missing, the nonce is not 8 to 128 characters, the signature is not hex, or the timestamp is more than 5 minutes from the server's clock. The detail does not say which; check each. summary: A signing header is missing or malformed, or the timestamp is stale value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Authentication failed request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedInvalidSecret: summary: 'Secret mode: the client id or secret is wrong' value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Invalid credentials request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedInvalidSignature: description: >- The detail is the identity service's reason when it gives one (an unknown client or a reused nonce reads differently); Invalid signature otherwise. summary: The signature does not match value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Invalid signature request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedLockedOut: summary: Too many failed credential checks value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Too many failed credential checks; retry later request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED RequestTimeout: summary: The request ran past its deadline value: code: TIMEOUT correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: The request took too long to complete. Please try again. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 408 timestamp: '2026-10-30T09:15:02Z' title: Request Timeout type: https://api.bitnob.com/errors/TIMEOUT RateLimited: summary: The per-IP limit (500 requests a minute) is reached value: code: RATE_LIMIT_EXCEEDED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Too many requests. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 429 timestamp: '2026-10-30T09:15:02Z' title: Rate Limit Exceeded type: https://api.bitnob.com/errors/RATE_LIMIT_EXCEEDED RateLimitedEnvelope: summary: An operation-specific throttle (answered by the handler) value: error: code: RATE_LIMIT_EXCEEDED message: >- a verification link was sent to this customer in the last minute; try again shortly request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' InternalError: summary: Something failed on our side value: code: INTERNAL_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: An internal error occurred. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 500 timestamp: '2026-10-30T09:15:02Z' title: Internal Server Error type: https://api.bitnob.com/errors/INTERNAL_ERROR InternalErrorEnvelope: summary: A failure answered by the handler value: error: code: INTERNAL_ERROR message: Failed to list transactions request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' InternalErrorUnhandled: summary: An unexpected failure value: code: INTERNAL_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: An internal server error occurred request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 500 timestamp: '2026-10-30T09:15:02Z' title: Internal Server Error type: https://api.bitnob.com/errors/INTERNAL_ERROR securitySchemes: BitnobClientId: type: apiKey in: header name: X-Auth-Client description: | Your workspace client id. All calls must include four headers: - `X-Auth-Client` — your workspace client id - `X-Auth-Timestamp` — Unix seconds - `X-Auth-Nonce` — 16-byte random hex - `X-Auth-Signature` — hex(HMAC-SHA256( `{client_id}:{timestamp}:{nonce}:{raw_body}`, client_secret)) The playground computes the timestamp, nonce and signature for you. BitnobClientSecret: type: apiKey in: header name: X-Playground-Client-Secret description: > Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.