'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
Virtual Cards
Bitnob’s Virtual Cards API allows you to programmatically issue and manage USD-denominated virtual debit cards for users. These cards can be used for online purchases, subscriptions, and other payments just like physical debit cards.
Create Card
Issue a new virtual or physical card for a customer. The card is created in an active state and can be used immediately after funding.
Create Card Body Parameters
Customer ID to issue the card for. The customer must exist in your Bitnob account.
The type of card to issue. Accepted values are virtual or physical.
The card network brand. Accepted values are visa or mastercard.
The currency denomination for the card (e.g., USD, NGN). All transactions on the card will be settled in this currency.
The billing address associated with the cardholder.
Primary street address line (e.g., house number and street name).
Secondary address line for additional information such as suite or apartment number.
City of the billing address.
State or province of the billing address.
Postal or ZIP code of the billing address.
Two-letter ISO 3166-1 alpha-2 country code (e.g., NG, US, GB).
Optional spending limits to apply to the card. Includes single_transaction, daily, weekly, and monthly limit fields.
Custom key-value pairs you can attach to the card for internal tracking (e.g., department, cost center).
Response
Unique identifier for the newly created card.
Identifier of the company that owns this card.
Identifier of the customer the card was issued to.
The type of card issued — virtual or physical.
The card network brand — visa or mastercard.
The last four digits of the card number.
The currency denomination for the card.
Current card status. Newly created cards are active.
Current balance on the card. Starts at 0.00 upon creation.
Applied spending limits including single_transaction, daily, weekly, and monthly caps.
The billing address associated with the card.
Custom key-value pairs attached to the card.
ISO 8601 timestamp of when the card was created.
ISO 8601 timestamp of the last update to the card.
Get Card
Retrieve the details of a specific card by its ID. This returns general card information including balance and status, but not sensitive card data like the full card number or CVV.
Path Parameters
The unique identifier of the card to retrieve.
The response is identical to that of Create Card. Refer to the Create Card Response section for field explanations.
Get Card Details (Sensitive)
Retrieve sensitive card data including the full card number, CVV, and expiry date. This endpoint returns PCI-sensitive information and should be used with extreme care.
Only call this endpoint when absolutely necessary. Never log or store the full card number or CVV. Display card details securely in the UI and consider implementing additional verification (e.g., 2FA) before showing details to end users.
Path Parameters
Indicates whether the API request was successful or failed.
A human-readable message describing the result of the request.
The unique identifier of the card whose sensitive details are being retrieved.
The full card number associated with the card. This is PCI-sensitive information and must be handled securely.
The card verification value used for additional security during transactions.
The expiration month of the card.
The expiration year of the card.
The name printed on the card.
Primary street address for the cardholder.
Additional address details such as apartment or suite number.
City of the cardholder's billing address.
State or region of the billing address.
Postal or ZIP code for the billing address.
Two-letter country code representing the country of the billing address (ISO 3166-1 alpha-2).
List Cards
Retrieve a paginated list of all cards. Use query parameters to filter by status, type, or customer.
Query Parameters
Filter cards by their current status (e.g., active, frozen, terminated).
Filter by card type. Accepted values are virtual or physical.
Filter cards belonging to a specific customer.
Number of results to return per page. Defaults to 20, maximum 100.
Number of results to skip before returning records. Used for pagination. Defaults to 0.
Fund Card
Add funds to a card's balance. The currency must match the card's denominated currency.
Path Parameters
The unique identifier of the card to fund.
Body Parameters
The amount to add to the card balance as a decimal string (e.g., "500.00").
Currency code for the funding operation. Must match the card's currency.
A human-readable description for this funding transaction.
Your internal reference identifier for this transaction. Used for idempotency and reconciliation.
Response
Identifier of the card that was funded.
The operation type. Value is fund for this endpoint.
The amount that was added to the card balance.
Currency code of the funding operation.
The updated card balance after the funding operation.
Unique identifier for this funding transaction.
The reference identifier provided in the request.
ISO 8601 timestamp of when the funding transaction was created.
Withdraw from Card
Remove funds from a card's balance back to your account. Useful for reclaiming unused funds or adjusting card balances.
Path Parameters
The unique identifier of the card to withdraw funds from.
Body Parameters
The amount to withdraw from the card balance as a decimal string (e.g., "200.00").
Currency code for the withdrawal. Must match the card's currency.
A human-readable description for this withdrawal transaction.
Your internal reference identifier for this transaction.
Response
The response is identical to that of Fund Card. Refer to the Fund Card Response section for field explanations.
Freeze Card
Temporarily suspend a card to prevent any new transactions. The card can be unfrozen later to restore its active state. Useful for responding to suspected fraud or temporary suspension needs.
Path Parameters
The unique identifier of the card to freeze.
Body Parameters
An optional reason for freezing the card. Stored for audit purposes.
Response
Identifier of the card that was frozen.
Updated card status. Value is frozen after this operation.
ISO 8601 timestamp of when the card was frozen.
The reason provided for freezing the card, if supplied.
Unfreeze Card
Restore a frozen card to an active state, allowing it to process new transactions again. No request body is required.
Path Parameters
Indicates whether the request to unfreeze the card was successful or not.
A human-readable message describing the result of the request.
The unique identifier of the card that has been successfully unfrozen.
The current status of the card after the operation. In this case, it will be set to active.
The date and time the card was unfrozen, returned in ISO 8601 format.
Terminate Card
Permanently terminate a card. This action is irreversible. Any remaining balance on the card will be returned to your account.
Path Parameters
The unique identifier of the card to terminate.
Body Parameters
An optional reason for terminating the card. Stored for audit and compliance purposes.
Response
Identifier of the card that was terminated.
Updated card status. Value is terminated after this operation.
The balance that was on the card at the time of termination.
Indicates whether the remaining balance was returned to your account.
ISO 8601 timestamp of when the card was terminated.
The reason provided for terminating the card, if supplied.
Update Spending Limits
Update the spending limits and merchant restrictions on a card. All fields are optional — only the fields you include will be updated.
Path Parameters
The unique identifier of the card whose spending limits are being updated.
Body Parameters
Maximum amount allowed per individual transaction as a decimal string.
Maximum total spending allowed per day as a decimal string.
Maximum total spending allowed per week as a decimal string.
Maximum total spending allowed per month as a decimal string.
List of allowed MCC (Merchant Category Code) categories. Transactions at merchants outside these categories will be declined.
List of blocked MCC categories. Transactions at merchants in these categories will be declined.
Whitelist of specific merchant IDs. When set, only transactions at these merchants are allowed.
Blacklist of specific merchant IDs. Transactions at these merchants will be declined.
Response
Identifier of the card whose spending limits were updated.
The operation type. Value is update_spending_limits for this endpoint.
The full set of updated spending limits, including single_transaction, daily, weekly, monthly, allowed_categories, blocked_categories, allowed_merchants, and blocked_merchants.
ISO 8601 timestamp of when the spending limits were last updated.
Get Cards by Customer
Retrieve all cards belonging to a specific customer.
Path Parameters
Indicates whether the API request was successful or failed.
A human-readable message describing the result of the request.
A list of cards associated with the specified customer.
The unique identifier of the card.
The unique identifier of the customer who owns the card.
The type of card issued to the customer (e.g., virtual or physical).
The card network brand associated with the card (e.g., Visa or Mastercard).
The last four digits of the card number used for identification.
The currency the card operates in.
The current status of the card (e.g., active, inactive, blocked).
The current available balance on the card.
The date and time when the card was created, returned in ISO 8601 format.
The total number of cards returned in the response.