# Numero ## Docs - [Overview](https://docs.usenumero.com/01-overview.md): Build fintech products on Numero β€” move money, collect payments, issue cards, verify identities, and pay bills through one integration. - [Authentication](https://docs.usenumero.com/02-authentication.md): All API requests must be authenticated using your API key, sent via the x-api-key header. - [Request Signing](https://docs.usenumero.com/03-request-signing.md): Most POST endpoints require a request signature so Numero can verify the integrity and authenticity of the payload. - [Errors & Responses](https://docs.usenumero.com/04-errors-and-responses.md): All Numero API responses follow a consistent format, making it easy to handle both successful and failed requests. - [Buy airtime πŸ”’](https://docs.usenumero.com/api-reference/airtime/buy-airtime-πŸ”’.md): Purchase airtime for a phone number. - [List airtime networks πŸ”’](https://docs.usenumero.com/api-reference/airtime/list-airtime-networks-πŸ”’.md): List the available airtime networks (MTN, Glo, Airtel, 9mobile). - [Get Balance](https://docs.usenumero.com/api-reference/balance.md): Retrieve your merchant account balance. Supports multiple currencies. - [Get wallet balance](https://docs.usenumero.com/api-reference/balance/get-wallet-balance.md): Retrieve your merchant account balance. Supports multiple currencies. - [Fund a betting wallet πŸ”’](https://docs.usenumero.com/api-reference/betting/fund-a-betting-wallet-πŸ”’.md): Deposit funds into a validated betting account. - [List bookmakers πŸ”’](https://docs.usenumero.com/api-reference/betting/list-bookmakers-πŸ”’.md): Retrieve the list of supported betting platforms. - [Validate a betting customer ID πŸ”’](https://docs.usenumero.com/api-reference/betting/validate-a-betting-customer-id-πŸ”’.md): Verify a customer's betting account before funding. - [Bills purchase notification](https://docs.usenumero.com/api-reference/bills_purchase_notification.md): Sent to your subscription URL when any VAS purchase (airtime/data/electricity/cable/betting) succeeds **or** fails. Verify the `X-Numero-Signature` header (HMAC-SHA256 of the raw body, keyed by your subscription's signing secret) before trusting the payload. - [Buy a cable add-on πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/buy-a-cable-add-on-πŸ”’.md): Purchase an add-on package for an existing subscription. - [List add-ons for a bouquet πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/list-add-ons-for-a-bouquet-πŸ”’.md): Retrieve available add-on packages for a subscription plan. - [List bouquets for a provider πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/list-bouquets-for-a-provider-πŸ”’.md): Retrieve available subscription plans for a specific provider. - [List cable providers πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/list-cable-providers-πŸ”’.md): Retrieve the list of available cable TV providers. - [Pay a cable subscription πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/pay-a-cable-subscription-πŸ”’.md): Subscribe or renew a cable TV subscription. - [Validate a smartcard πŸ”’](https://docs.usenumero.com/api-reference/cable-tv/validate-a-smartcard-πŸ”’.md): Verify a customer's smart card or IUC number before purchasing. - [Cardholder's Cards](https://docs.usenumero.com/api-reference/cardholders-cards.md): List all cards belonging to a cardholder. - [Create Cardholder](https://docs.usenumero.com/api-reference/cardholders-create.md): Create a reusable cardholder (end-customer) you can issue cards to. - [Get Cardholder](https://docs.usenumero.com/api-reference/cardholders-get.md): Retrieve a single cardholder by id. - [Issue Card to Cardholder](https://docs.usenumero.com/api-reference/cardholders-issue-card.md): Issue a new card to an existing cardholder. - [List Cardholders](https://docs.usenumero.com/api-reference/cardholders-list.md): List the cardholders (end-customers) under your business. - [Cardholder Transactions](https://docs.usenumero.com/api-reference/cardholders-transactions.md): Retrieve the combined statement across a cardholder's cards. - [Cardholder statement (across their cards)](https://docs.usenumero.com/api-reference/cardholders/cardholder-statement-across-their-cards.md): Returns the transaction history across all of a cardholder's cards. - [Create a cardholder](https://docs.usenumero.com/api-reference/cardholders/create-a-cardholder.md): Create one of your customers as a cardholder. You attest their KYC (required by the issuer). - [Get a cardholder](https://docs.usenumero.com/api-reference/cardholders/get-a-cardholder.md): Returns a single cardholder by their `customerId`. - [Issue a card to a cardholder](https://docs.usenumero.com/api-reference/cardholders/issue-a-card-to-a-cardholder.md): Issue a card to an existing cardholder (KYC already on file). - [List a cardholder's cards](https://docs.usenumero.com/api-reference/cardholders/list-a-cardholders-cards.md): Returns every card issued to a single cardholder. - [List cardholders](https://docs.usenumero.com/api-reference/cardholders/list-cardholders.md): Returns the cardholders you've created. - [Freeze & Unfreeze Card](https://docs.usenumero.com/api-reference/cards-freeze.md): Temporarily block or re-enable a card. - [Get Card](https://docs.usenumero.com/api-reference/cards-get.md): Retrieve a single card by reference (masked). - [Issue Card](https://docs.usenumero.com/api-reference/cards-issue.md): Issue a USD virtual card to a customer, with KYC supplied inline. - [Set Card Limits](https://docs.usenumero.com/api-reference/cards-limits.md): Set per-card daily and per-transaction spend limits. - [List Cards](https://docs.usenumero.com/api-reference/cards-list.md): List all virtual cards issued by your business. - [Cards](https://docs.usenumero.com/api-reference/cards-overview.md): Issue and manage virtual USD cards for your customers β€” one API, issuer abstracted. - [List Card Products](https://docs.usenumero.com/api-reference/cards-products.md): Discover the card products you can issue from, with their capabilities and your entitlement status. - [Reveal Card Details](https://docs.usenumero.com/api-reference/cards-reveal.md): Fetch the full PAN, CVV and expiry for a card (sensitive). - [Top Up Card](https://docs.usenumero.com/api-reference/cards-topup.md): Move USD from your card wallet onto a card. - [Card Transactions](https://docs.usenumero.com/api-reference/cards-transactions.md): Retrieve the spend statement for a card. - [Withdraw from Card](https://docs.usenumero.com/api-reference/cards-withdraw.md): Pull USD off a card back to your card wallet. - [Card statement](https://docs.usenumero.com/api-reference/cards/card-statement.md): Returns a card's transaction history (settlements, refunds, cross-border, declines…). This is the per-card statement; your USD card-wallet transactions (funding, top-ups, fees) are separate. - [Freeze a card](https://docs.usenumero.com/api-reference/cards/freeze-a-card.md): Freeze a card to block spend temporarily, then unfreeze to re-enable it. Freezing is reversible (unlike termination). - [Fund a card](https://docs.usenumero.com/api-reference/cards/fund-a-card.md): Move USD from your card wallet onto the card. - [Get a card](https://docs.usenumero.com/api-reference/cards/get-a-card.md): Returns a single card by its reference, masked. The balance shown is Numero's mirrored figure. - [Issue a virtual card](https://docs.usenumero.com/api-reference/cards/issue-a-virtual-card.md): Issue a USD virtual card. Pass the cardholder's KYC inline (the cardholder is created/reused automatically), or use the Cardholders flow to issue to an existing cardholder. `initialBalance` is debited from your USD card wallet (fund-first). - [List available card products](https://docs.usenumero.com/api-reference/cards/list-available-card-products.md): The card products your business can issue from, each with its `capabilities` (the valid values for `capability` at issue β€” e.g. `APPLE_PAY`, `GOOGLE_PAY`) and your entitlement status. Use this to discover product codes and card types instead of hardcoding them. You can only issue from products with… - [List cards](https://docs.usenumero.com/api-reference/cards/list-cards.md): Returns all cards your business has issued, masked. Supports pagination. - [Reveal full card details (sensitive)](https://docs.usenumero.com/api-reference/cards/reveal-full-card-details-sensitive.md): Returns the full PAN, CVV and expiry, fetched securely from the issuer. Numero never stores the full PAN. Handle the response in a PCI-aware context only. - [Set per-card spend limits](https://docs.usenumero.com/api-reference/cards/set-per-card-spend-limits.md): Set the daily and/or per-transaction USD limits for a card. Omit a field to leave it unchanged. - [Unfreeze a card](https://docs.usenumero.com/api-reference/cards/unfreeze-a-card.md): curl -X POST "https://api-dev.usenumero.com/numeroaccount/api/v1/business/card/NCRD24AD18BEBD474A/freeze" \. - [Withdraw from a card](https://docs.usenumero.com/api-reference/cards/withdraw-from-a-card.md): Move USD from the card back to your card wallet. - [Buy a data bundle πŸ”’](https://docs.usenumero.com/api-reference/data/buy-a-data-bundle-πŸ”’.md): Purchase a mobile-data bundle for a phone number. - [List data networks πŸ”’](https://docs.usenumero.com/api-reference/data/list-data-networks-πŸ”’.md): List the available mobile-data networks. - [Look up data plans for a provider πŸ”’](https://docs.usenumero.com/api-reference/data/look-up-data-plans-for-a-provider-πŸ”’.md): Look up the data bundles available for a network. - [Buy electricity πŸ”’](https://docs.usenumero.com/api-reference/electricity/buy-electricity-πŸ”’.md): Purchase an electricity token for a validated meter. - [List electricity discos πŸ”’](https://docs.usenumero.com/api-reference/electricity/list-electricity-discos-πŸ”’.md): Retrieve the list of available electricity providers and their plan types. - [Validate a meter πŸ”’](https://docs.usenumero.com/api-reference/electricity/validate-a-meter-πŸ”’.md): Verify a customer's meter number before purchasing electricity. - [Get Transactions](https://docs.usenumero.com/api-reference/transactions.md): Retrieve a paginated list of transactions on your merchant account. Supports filtering by date range and search terms. - [Transfer notification funding notification payout notification](https://docs.usenumero.com/api-reference/transfer_notification-funding_notification-payout_notification.md): Money-movement lifecycle events for outbound transfers, wallet funding, and payouts. The `data` is the transaction object below (delivered inside the `{ id, event, created_at, data }` envelope β€” see the Webhooks section). - [Initiate Bulk Transfer](https://docs.usenumero.com/api-reference/transfers-bulk.md): Send money to multiple bank accounts in a single request. - [Calculate Bulk Transfer Fees](https://docs.usenumero.com/api-reference/transfers-fee-bulk.md): Calculate fees for a bulk transfer. Returns the total fees and a per-item breakdown. - [Calculate Single Transfer Fee](https://docs.usenumero.com/api-reference/transfers-fee-single.md): Calculate the fee for a single transfer before initiating it. Use this to show your users the exact cost. - [Get Bank List](https://docs.usenumero.com/api-reference/transfers-get-banks.md): Retrieve the list of supported Nigerian banks and their codes. Use the bank codes when validating accounts and initiating transfers. - [Transfers & Payouts](https://docs.usenumero.com/api-reference/transfers-overview.md): Send money instantly to any bank account in Nigeria. Numero supports both single and bulk transfers, with real-time status tracking. - [Initiate Single Transfer](https://docs.usenumero.com/api-reference/transfers-single.md): Send money to a single bank account. You should validate the account first to confirm the recipient details. - [Get Transfer Status](https://docs.usenumero.com/api-reference/transfers-status.md): Check the current status of a transfer using its reference. - [Validate Account Number](https://docs.usenumero.com/api-reference/transfers-validate-account.md): Verify a recipient's bank account before a transfer β€” confirms the account name and that it can receive funds. - [Get a transfer's status by reference](https://docs.usenumero.com/api-reference/transfers/get-a-transfers-status-by-reference.md): Check the current status of a transfer using its reference. - [Initiate a bulk transfer πŸ”’](https://docs.usenumero.com/api-reference/transfers/initiate-a-bulk-transfer-πŸ”’.md): Send money to multiple bank accounts in a single request. - [Initiate a single transfer πŸ”’](https://docs.usenumero.com/api-reference/transfers/initiate-a-single-transfer-πŸ”’.md): Send NGN to a bank account. Use the `validationCode`/`transferSessionId` from `/business/validate`. **(signed)** - [List transactions](https://docs.usenumero.com/api-reference/transfers/list-transactions.md): Retrieve a paginated list of transactions on your merchant account. Supports filtering by date range and search terms. - [Preview fees for a batch of transfers πŸ”’](https://docs.usenumero.com/api-reference/transfers/preview-fees-for-a-batch-of-transfers-πŸ”’.md): Calculate fees for a bulk transfer. Returns the total fees and a per-item breakdown. - [Preview the fee for a single transfer πŸ”’](https://docs.usenumero.com/api-reference/transfers/preview-the-fee-for-a-single-transfer-πŸ”’.md): Calculate the fee for a single transfer before initiating it. Use this to show your users the exact cost. - [Resolve a bank account (name enquiry) πŸ”’](https://docs.usenumero.com/api-reference/transfers/resolve-a-bank-account-name-enquiry-πŸ”’.md): Returns the account name for a bank/account pair and a `transferSessionId` to carry into the transfer. **(signed)** - [Generate a request signature (integration helper)](https://docs.usenumero.com/api-reference/utilities/generate-a-request-signature-integration-helper.md): Returns the HMAC signature for a given body, for use while integrating. Sign locally in production. - [List banks](https://docs.usenumero.com/api-reference/utilities/list-banks.md): The curated, transfer-ready bank list. Use a bank's `cbnCode` as `destinationBankCode` on transfers. - [Re-query a VAS purchase πŸ”’](https://docs.usenumero.com/api-reference/utilities/re-query-a-vas-purchase-πŸ”’.md): Re-query and reconcile a bill payment by `reference`. A confirmed success completes it (and captures any token); a confirmed failure refunds the debit. Poll this if a purchase response was pending or you missed the BILLS_PURCHASE_NOTIFICATION webhook. - [Betting](https://docs.usenumero.com/api-reference/vas-betting.md): Fund customer accounts on major Nigerian betting platforms. - [Cable TV](https://docs.usenumero.com/api-reference/vas-cable-tv.md): Subscribe, renew, and manage cable TV subscriptions for DSTV, GOtv, Startimes, and other providers. - [Electricity](https://docs.usenumero.com/api-reference/vas-electricity.md): Purchase prepaid or postpaid electricity tokens. Supports all major Nigerian electricity distribution companies . - [Value Added Services](https://docs.usenumero.com/api-reference/vas-overview.md): Pay for utilities and services on behalf of your users. Numero supports electricity, cable TV subscriptions, and betting account funding. - [Business Verification](https://docs.usenumero.com/api-reference/verification-business.md): Verify businesses using CAC registration numbers, company names, or Tax Identification Numbers. - [Financial Verification](https://docs.usenumero.com/api-reference/verification-financial.md): Verify bank accounts and run Anti-Money Laundering checks. - [Generic & Credit Verifications](https://docs.usenumero.com/api-reference/verification-generic.md): For verification types not covered by the dedicated endpoints , use the generic verification endpoint. - [Verification History](https://docs.usenumero.com/api-reference/verification-history.md): View past verifications and retrieve detailed results. - [Identity Verification](https://docs.usenumero.com/api-reference/verification-identity.md): Verify individual identities using BVN, NIN, Voter's Card, Driver's License, or Passport. - [Verification / KYC](https://docs.usenumero.com/api-reference/verification-overview.md): Verify customer identities and businesses using a wide range of Nigerian and international identity documents. - [Phone Verification](https://docs.usenumero.com/api-reference/verification-phone-address.md): Verify phone numbers (basic, advanced, and phone + NIN cross-check). - [AML / sanctions screening](https://docs.usenumero.com/api-reference/verification/aml-sanctions-screening.md): Run an Anti-Money Laundering screening against global watchlists. - [Generic verification (by product code)](https://docs.usenumero.com/api-reference/verification/generic-verification-by-product-code.md): Run any verification product by its code with a free-form payload. Use the typed endpoints above where one exists. - [Get a verification by id](https://docs.usenumero.com/api-reference/verification/get-a-verification-by-id.md): Retrieve the full details and result of a specific verification. - [List verification history](https://docs.usenumero.com/api-reference/verification/list-verification-history.md): Retrieve a paginated list of all verification requests. - [Look up a company by name](https://docs.usenumero.com/api-reference/verification/look-up-a-company-by-name.md): Search for a company by name. - [Verify a bank account](https://docs.usenumero.com/api-reference/verification/verify-a-bank-account.md): Verify a bank account number and retrieve account holder details. - [Verify a company (CAC advanced)](https://docs.usenumero.com/api-reference/verification/verify-a-company-cac-advanced.md): CAC verification with detailed company information. - [Verify a company (CAC basic)](https://docs.usenumero.com/api-reference/verification/verify-a-company-cac-basic.md): Basic Corporate Affairs Commission lookup by registration number. - [Verify a company (CAC premium)](https://docs.usenumero.com/api-reference/verification/verify-a-company-cac-premium.md): CAC verification with full records including directors and shareholders. - [Verify a driver's licence (FRSC)](https://docs.usenumero.com/api-reference/verification/verify-a-drivers-licence-frsc.md): Verify a driver's license number. - [Verify a phone number (advanced)](https://docs.usenumero.com/api-reference/verification/verify-a-phone-number-advanced.md): Phone verification with extended data. - [Verify a phone number against a NIN](https://docs.usenumero.com/api-reference/verification/verify-a-phone-number-against-a-nin.md): Verify that a phone number and NIN belong to the same person. - [Verify a phone number (basic)](https://docs.usenumero.com/api-reference/verification/verify-a-phone-number-basic.md): Basic phone number verification. - [Verify a TIN](https://docs.usenumero.com/api-reference/verification/verify-a-tin.md): Verify a Tax Identification Number. - [Verify a voter's card](https://docs.usenumero.com/api-reference/verification/verify-a-voters-card.md): Verify a Permanent Voter's Card number. - [Verify a voter's card (premium)](https://docs.usenumero.com/api-reference/verification/verify-a-voters-card-premium.md): PVC verification with extended data. - [Verify an international passport](https://docs.usenumero.com/api-reference/verification/verify-an-international-passport.md): Verify a Nigerian international passport. - [Verify BVN](https://docs.usenumero.com/api-reference/verification/verify-bvn.md): Verify a Bank Verification Number. - [Verify BVN (advanced β€” full record + photo)](https://docs.usenumero.com/api-reference/verification/verify-bvn-advanced-β€”-full-record-+-photo.md): BVN verification with extended data (photo, additional details). - [Verify NIN](https://docs.usenumero.com/api-reference/verification/verify-nin.md): Verify a National Identification Number. - [Verification notification](https://docs.usenumero.com/api-reference/verification_notification.md): Sent when a verification flips out of Pending into Completed or Failed. - [Create Business Virtual Account](https://docs.usenumero.com/api-reference/virtual-accounts-create-business.md): Create a virtual NUBAN account for a corporate entity. Requires business registration details. - [Create Customer Virtual Account](https://docs.usenumero.com/api-reference/virtual-accounts-create-customer.md): Create a virtual NUBAN account for an individual customer. Requires basic KYC information. - [Get Virtual Account](https://docs.usenumero.com/api-reference/virtual-accounts-get.md): Retrieve the details of a specific virtual account by its reference. - [List All Virtual Accounts](https://docs.usenumero.com/api-reference/virtual-accounts-list.md): Retrieve a paginated list of all virtual accounts created under your merchant account. - [Collections](https://docs.usenumero.com/api-reference/virtual-accounts-overview.md): Create dynamic NUBAN accounts so customers can pay you by bank transfer, with funds auto-credited to your wallet. - [Create a business virtual account πŸ”’](https://docs.usenumero.com/api-reference/virtual-accounts/create-a-business-virtual-account-πŸ”’.md): Create a virtual NUBAN account for a corporate entity. Requires business registration details. - [Create a customer virtual account πŸ”’](https://docs.usenumero.com/api-reference/virtual-accounts/create-a-customer-virtual-account-πŸ”’.md): Issue a dedicated NGN account for an end customer. Inflows settle to your wallet. **(signed)** - [List virtual accounts](https://docs.usenumero.com/api-reference/virtual-accounts/list-virtual-accounts.md): Retrieve a paginated list of all virtual accounts created under your merchant account. - [Look up a virtual account by reference](https://docs.usenumero.com/api-reference/virtual-accounts/look-up-a-virtual-account-by-reference.md): Retrieve the details of a specific virtual account by its reference. - [Virtual account created](https://docs.usenumero.com/api-reference/virtual_account_created.md): Sent when a customer or business virtual account is minted. - [Webhook Best Practices](https://docs.usenumero.com/api-reference/webhooks-best-practices.md): Follow these guidelines to build a robust webhook integration. - [Webhooks](https://docs.usenumero.com/api-reference/webhooks-overview.md): Receive real-time notifications when events occur on your account β€” funding, transfers, payouts, bills, verifications, and more. - [Webhook Signature Verification](https://docs.usenumero.com/api-reference/webhooks-verification.md): Verify the X-Numero-Signature on every webhook before trusting the payload. ## OpenAPI Specs - [numero-public-api](https://docs.usenumero.com/openapi/numero-public-api.yaml)