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.
Register Card User
You need to onboard a card user before issuing cards for them.
Register Card User Parameters
A unique identifier for a previously registered user in your system. It could be an email address or user id.
The government-issued ID number (e.g., National ID, Passport number) provided by the customer for KYC verification.
Type of identification document, such as BVN, NIN, or PASSPORT, indicating which scheme issued the ID number.
Customer’s given name, used for personalization and identity matching.
Customer’s family name or surname, used alongside firstName for full legal name.
Name of the customer’s country of residence, used to determine regional compliance rules.
Customer’s mobile or landline phone number for two-factor authentication and notifications.
City of the customer’s primary address, used for geographic profiling and correspondence.
State or region of the customer’s address, used for location validation and regulatory compliance.
Postal code of the customer’s address, used for mailing and region-specific services.
First line of the customer’s street address (e.g., house number and street name).
The name or number of the building or residence, if applicable (e.g., apartment name).
Bank Verification Number; required when the customer is a Nigerian citizen for additional verification.
URL or base64-encoded image of the customer’s face (selfie), used for photo-ID matching.
Customer’s date of birth in YYYY-MM-DD format; required specifically for Ghanaian customers to meet local KYC standards.
URL or base64-encoded scan/photo of the customer’s ID document (e.g., passport, NIN card).
Register Card User Request
The full API endpoint to which the request should be sent.
Specifies the expected response format. Usually set to 'application/json'.
Indicates the format of the request body. Should be 'application/json' for this endpoint.
Update Card User
You can update card user information
Update Card User Body Parameters
A unique identifier for a previously registered user in your system. It could be an email address or user id.
The government-issued ID number (e.g., National ID, Passport number) provided by the customer for KYC verification.
Type of identification document, such as BVN, NIN, or PASSPORT, indicating which scheme issued the ID number.
Customer’s given name, used for personalization and identity matching.
Customer’s family name or surname, used alongside firstName for full legal name.
Name of the customer’s country of residence, used to determine regional compliance rules.
Customer’s mobile or landline phone number for two-factor authentication and notifications.
City of the customer’s primary address, used for geographic profiling and correspondence.
State or region of the customer’s address, used for location validation and regulatory compliance.
Postal code of the customer’s address, used for mailing and region-specific services.
First line of the customer’s street address (e.g., house number and street name).
The name or number of the building or residence, if applicable (e.g., apartment name).
Bank Verification Number; required when the customer is a Nigerian citizen for additional verification.
URL or base64-encoded image of the customer’s face (selfie), used for photo-ID matching.
Customer’s date of birth in YYYY-MM-DD format; required specifically for Ghanaian customers to meet local KYC standards.
URL or base64-encoded scan/photo of the customer’s ID document (e.g., passport, NIN card).
Update Card User Request
The full API endpoint to which the request should be sent.
Specifies the expected response format. Usually set to 'application/json'.
Indicates the format of the request body. Should be 'application/json' for this endpoint.
A unique identifier for the card user. Required when updating or retrieving user-specific virtual card details.
Create Card
create a new card for a customer
Create Card Body Parameters
The following fields are used when creating a virtual card. Some fields are only required in sandbox mode or under certain conditions.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
The brand of the card to be issued. Required only if you're creating a Visa card (e.g., 'VISA').
The type of virtual card to issue. Defaults to 'visa' if not specified.
A unique transaction reference for tracking and idempotency. Helps avoid duplicate card creation.
The initial funding amount for the virtual card in fiat currency (e.g., '100' for $100).
Customer’s first name. This is required only for sandbox environments to simulate a real user.
Customer’s last name. This is also only needed when using the sandbox environment.
Create Card Request
The full API endpoint to initiate the virtual card creation request.
Specifies the expected response format, usually set to 'application/json'.
Indicates the format of the request body, should be 'application/json'.
Create Card Response
Indicates if the card creation request was successfully initiated.
A description of the response, useful for confirming the result of the request.
The unique identifier for the newly created virtual card.
The timestamp indicating when the card creation was initiated.
The timestamp of the most recent update to the card creation record.
The type of card issued, such as 'virtual'.
The brand of the card, e.g., 'visa' or 'mastercard'.
Unique ID of the user to whom the card belongs.
The reference string used during card creation to track this request.
Current status of the card creation process. For example: 'pending', 'successful', or 'failed'.
Represents the customer's ID in the system. May be null if not yet assigned.
Top Up Card
Add funds to virtual card
Top Up Card Body Parameters
The amount (in cents) to add to the card. For example, 1000 represents $10.00.
The unique identifier of the virtual card to be topped up.
A unique reference string for tracking and idempotency of the transaction.
Top Up Card Request
The HTTP method used to initiate the request to the API endpoint.
The full API endpoint to initiate the virtual card creation request.
Specifies the expected response format, usually set to 'application/json'.
Indicates the format of the request body, should be 'application/json'.
Top Up Card Responses
Indicates whether the top-up request was successfully acknowledged by the API. A value of `true` means the request was valid and is being processed.
Provides a human-readable description of the top-up response. This may include status updates such as 'top-up in progress' or error messages if the request failed.
A unique identifier assigned to the top-up transaction. This ID can be used to track or query the status of the transaction in future API calls.
The timestamp (in ISO 8601 format) when the top-up request was created. Useful for audit trails and chronological sorting.
The timestamp (in ISO 8601 format) representing the most recent update to the top-up transaction status, such as when it changed from 'pending' to 'success'.
The value of the top-up in whole currency units (e.g., 10 for $10). Represents the user-visible amount being added to the card.
The exact amount added to the card in the smallest currency unit (e.g., cents). Used to ensure financial precision, especially in calculations.
Indicates the type of transaction. Typically this will be 'credit' for top-ups, meaning funds are being added to the card.
Specifies the method used for the transaction. In this context, 'topup' signifies that the card was funded via the top-up endpoint.
Represents the current lifecycle state of the transaction, such as 'pending', 'success', or 'failed'. Can be used to track progress in asynchronous flows.
The currency code (e.g., 'usd') in which the top-up was made. Ensures compatibility with cards that may support multiple currencies.
A custom identifier or metadata field passed during the top-up request. Useful for reconciling transactions in internal systems.
The unique identifier of the virtual card that received the top-up. Use this ID to look up card details or perform additional operations on the card.
List Cards
Get all virtual cards under your business
List Cards Query Params
Determines the sort direction of the returned results. Accepted values are typically (ascending) to show oldest entries first, or 'desc' (descending) to show the most recent entries first. Useful when sorting by timestamps or IDs.
Specifies which page of results to retrieve from the paginated response. Use in combination with 'take' to navigate through large datasets. Page numbering typically starts at 1.
Defines the number of items to return per page. This helps limit the response size and improve performance. Common values include 10, 20, or 50 depending on the endpoint.
List Cards Responses
Indicates whether the API request was successful. A value of true means the request was processed without error.
A human-readable message summarizing the outcome of the API request, useful for debugging and user feedback.
A unique identifier assigned to the virtual card. This ID is used for referencing the card in future API operations.
The exact date and time when the virtual card was created, in ISO 8601 format (e.g., 2023-03-02T15:58:17.775Z).
The most recent date and time the virtual card was updated. This can reflect changes like status or metadata updates.
The last four digits of the virtual card number, typically used for card identification and verification.
The name associated with the virtual card, often reflecting the user or purpose of the card.
Indicates the type of card issued. For virtual cards, this will usually be 'virtual'.
The card network brand such as 'VISA' or 'MasterCard'. This determines where the card can be accepted.
The full expiration timestamp of the card, including the date and time it will no longer be valid.
A formatted string showing the expiration month and year of the card (e.g., 12/2026).
The operational state of the card such as 'active', 'frozen', or 'terminated'. Determines if the card can be used.
A custom identifier or metadata string provided during card creation to help with internal tracking or reconciliation.
Shows the result of the card creation process. A value like 'success' or 'pending' reflects its state after issuance.
The UUID of the customer associated with the card. Useful for grouping cards under a single user identity.
The current page number in the paginated response. Useful when navigating large sets of cards.
The number of items (cards) requested per page in a paginated API call.
The total number of card items returned on the current page.
The total number of pages available for the query, based on the take and itemCount values.
Boolean value indicating if there is a page before the current one. Useful for paginated navigation.
Boolean value indicating if there is another page of data after the current one.
List Card Users
Fetch all users who have been issued cards
List Card Users Query Params
Defines the sorting order of the returned results. Accepts either 'asc' for ascending or 'desc' for descending. Defaults to 'asc'.
Specifies the page number of the paginated results to return. Used for navigating through large datasets.
The number of items to return per page. Useful for controlling pagination and reducing payload size.
List Card Users Request
The full API endpoint to retrieve virtual card users.
Indicates the expected response format. Typically set to 'application/json'.
List Card Users Responses
Indicates whether the API call was successful. A value of 'true' means the request completed without errors.
A descriptive message returned by the server that provides context about the result of the API call.
A globally unique identifier assigned to each card user. Used for referencing the user in future requests.
The exact date and time when the card user was registered in the system, in ISO 8601 format.
The most recent timestamp when any part of the card user’s information was modified.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
The user's given name used during registration or KYC verification.
The user's surname or family name used in registration.
The identification number from the submitted government-issued ID (e.g., passport or national ID).
The type of identification provided, such as PASSPORT, NIN, or BVN. Used for KYC compliance.
The user’s mobile number, used for contact and sometimes for additional verification steps.
URL pointing to the uploaded photo of the user. If not provided, it may be null.
The internal identifier linking the card user to their main customer profile in the system.
Primary line of the card user's residential address.
City where the card user lives. Used for location-based KYC checks and address verification.
State or region of residence, particularly relevant for countries with subdivisions like Nigeria or the US.
Postal or ZIP code that corresponds to the card user’s residential area.
The name of the country where the card user resides (e.g., Nigeria, Ghana).
Bank Verification Number — required for Nigerian users to validate their financial identity.
Descriptive part of the user’s address, such as house number, apartment name, or unit identifier.
URL linking to the image of the ID document provided during registration.
Indicates whether the user has passed Know Your Customer (KYC) verification. If verification hasn’t occurred, this may be null.
The current page in the paginated list of results. Useful for navigating large datasets.
The number of results returned per page. Controls the size of the dataset in paginated responses.
Total number of individual card users returned by the current query.
Total number of pages available based on the current pagination settings.
True if a page exists before the current one in the result set. Helpful for pagination navigation.
True if there are more pages available after the current page.
Fetch Card User
Fetch a card users
Fetch Card User Path Params
A unique identifier assigned to a registered card user during the virtual card onboarding process. This ID is required in the URL path to retrieve, update, or perform actions specific to that card user.
Fetch Card User Request
The full API endpoint for the request, including the path parameter.
Specifies the expected response format. Usually set to 'application/json'.
Fetch Card User Responses
Indicates whether the API request was processed successfully. A value of `true` confirms success, while `false` indicates a failure or error in the request.
A human-readable message returned by the server describing the result of the operation, useful for debugging or displaying information to the end user.
A universally unique identifier automatically generated for the virtual card user. This ID can be used to perform future operations on this user.
The exact timestamp (in ISO 8601 format) when the card user was initially created in the system.
The latest timestamp indicating when any data related to this card user was last modified.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
The user's first name as provided during onboarding or card registration. Helps personalize interactions or identify users.
The last name or surname of the card user. Combined with first name for full identification.
The identification number associated with the user's KYC document (e.g., passport number, NIN). Used for verification and regulatory compliance.
Specifies the type of ID provided by the user (e.g., PASSPORT, NIN, BVN). Ensures proper parsing and validation during KYC checks.
The mobile or contact phone number provided by the card user. May be used for OTPs or transaction alerts.
A URL pointing to the user’s photo or selfie, often required as part of KYC validation. May be null if not provided.
An internal ID that uniquely represents the customer entity associated with this card user. Useful for linking multiple resources under one profile.
The primary line of the user’s residential or business address. Commonly contains house/flat number and street name.
The city portion of the user’s address. Helps in identifying the geographical location of the user.
The state, region, or province in which the user resides. Important for regional compliance and reporting.
A postal or ZIP code that corresponds to the user's address. Used for geolocation and address validation.
The country of residence of the card user. This affects regulatory rules, KYC requirements, and currency usage.
Bank Verification Number (specific to Nigerian users). Used for advanced identity verification through central banking systems.
Optional field representing the specific house name or number. Useful for granular delivery or location accuracy.
A URL pointing to the scanned or uploaded image of the user’s ID document. Required for document-based identity verification.
Indicates whether the user has successfully passed the Know Your Customer (KYC) process. true means verified, false or null means not verified or still in review.
Fetch Card
Get details of a particular card
Path Params
Path parameter representing the unique identifier of the virtual card you want to fetch details for.
Fetch Card User Request
The HTTP method used for the request. In this case, 'GET'.
A cURL command example to execute the API request from the terminal.
Specifies the expected response format. Typically set to 'application/json'.
Fetch Card User Response
Indicates whether the API call was successful. A value of true confirms successful retrieval, while false indicates an error or failure in the process.
Human-readable summary of the API response, typically used for logging, debugging, or user display.
A universally unique identifier representing the virtual card. Useful for referencing or fetching this specific card in future operations.
Timestamp when the virtual card was initially created. Useful for tracking and auditing purposes.
Timestamp of the most recent update to the card's information or status.
The current monetary balance available on the virtual card. Expressed in the card's currency.
The full 16-digit number of the virtual card. Typically only visible in sandbox or secure environments due to PCI compliance.
The last four digits of the card number. Safe to display and commonly used for identifying cards without exposing full details.
Name printed or associated with the card, often representing the cardholder or intended usage.
Specifies the nature of the card. Expected value is 'virtual' to indicate it’s not a physical card.
Brand of the card provider such as 'Visa', 'Mastercard', etc. Determines network rules and acceptance.
3-digit security code located on the back of the card. Used for verification during online transactions. Only exposed in secure environments.
Exact expiration date and time of the virtual card in ISO format. After this timestamp, the card becomes invalid.
Indicates the current state of the card such as 'active', 'frozen', or 'terminated'. Determines usability.
The unique ID of the user who owns or was issued this virtual card. Used to reference user details.
Formatted expiration date in MM/YYYY. Useful for display in user interfaces and card validation forms.
Client-provided unique identifier used to track or reference the card in internal systems or reconciliation processes.
Result of the card creation attempt. A value such as 'success' confirms it was issued correctly.
If available, this is the system-generated ID linking the card to a registered customer. May be null for test data or incomplete records.
Email address of the individual or entity the card is associated with. Helps in user identification and notification delivery.
City provided in the billing address. Often required for verification during transactions or card issuance.
Full street portion of the billing address, including house number and street name.
Full country name where the billing address is located. Used for regional compliance checks.
Postal or ZIP code in the billing address. Used in verification and matching processes.
Two-letter ISO country code (e.g., 'US' for United States). Useful for internationalization and compliance checks.
List Transactions on Card
List all the transactions for a given card
List Transactions on Card Path Params
A path parameter representing the unique identifier of the virtual card. This ID is used to fetch detailed information about a specific virtual card.
List Transactions on Card Query Params
Specifies the sort order for the results. Accepted values are 'ASC' (ascending) or 'DESC' (descending). Defaults to 'ASC' if not provided.
Specifies the current page of results for paginated responses. Used in combination with 'take' to navigate through result sets.
Defines the number of records to return per page. Helps control response size in paginated endpoints.
List Transactions on Card Request
The full API endpoint for the request, including the path parameter.
Specifies the expected response format. Must be set to 'application/json' to receive a JSON response.
List Transactions on Card Responses
Indicates whether the API request was successful.
Describes the outcome of the transaction fetch operation.
Unique identifier of the card transaction.
Timestamp when the transaction was created.
Timestamp when the transaction was last updated.
The amount involved in the transaction (in major currency unit).
The amount in cents, used for precision in financial calculations.
Transaction type such as 'credit' or 'debit'.
Describes how the transaction was made (e.g., 'topup', 'withdrawal').
Additional information or description about the transaction if provided.
Current status of the transaction (e.g., 'success', 'failed').
Currency in which the transaction was made (e.g., 'usd').
A unique reference to identify the transaction.
The ID of the virtual card associated with this transaction.
Current page of the paginated response.
Number of items returned per page.
Total number of transactions returned.
Total number of pages available.
Indicates if there is a previous page of results.
Indicates if there is a next page of results.
List Card Transactions
List all card transactions under your business
List Card Transactions Query Params
The sort direction of results. Accepts 'ASC' (ascending) or 'DESC' (descending). Defaults to 'ASC'.
Specifies the current page number of paginated results. Starts at 1.
The number of transactions to return per page. Controls pagination limit.
List Transactions On Card Request
The full API endpoint for the request, including the path parameter.
Specifies the expected response format. Must be set to 'application/json' to receive a JSON response.
List Transactions On Card Response
Indicates whether the API request was successfully processed. If true, the data field contains the expected response; otherwise, check the message for details.
A short human-readable summary of the request's result. This can be used for logs or UI messages.
The unique identifier for the card transaction. Useful for tracking or referencing a specific transaction.
The timestamp when the transaction was created. Use this to display transaction history chronologically.
The timestamp when the transaction record was last updated. Helpful when checking if the status has changed.
The total amount of the transaction in standard units (e.g., '500' for 500 USD).
Amount expressed in the smallest currency unit (e.g., '500' cents = $5.00 USD). Often used for precision in financial calculations.
Type of transaction. Typically 'credit' for funds added to the card, or 'debit' for withdrawals or payments.
The method or source of the transaction, such as 'topup' for adding funds or 'withdrawal' for usage.
Optional description or notes attached to the transaction. May be null if not provided.
The current status of the transaction. Common values include 'success', 'pending', or 'failed'.
Currency code (e.g., 'usd') indicating the currency in which the transaction was made.
Unique string identifier that can be used to trace or reconcile the transaction across systems.
The ID of the card this transaction was performed on. Useful when filtering transactions per card.
The current page of the paginated response. Used in combination with 'take' to navigate results.
Number of records returned per page. Set this when requesting paginated data to limit or expand the batch size.
Total number of transaction records returned by the current query.
The total number of pages available for the given query, based on 'take' and total items.
If true, it means there is a previous page of results before the current one.
If true, it indicates more data is available and another page can be fetched.
Card Withdrawal
Withdraw funds from a card
Card Withdrawal Request
The amount to be charged to the virtual card in the smallest currency unit (e.g., cents). For example, 1000 = $10.00.
The unique ID of the virtual card to be charged. It must be a valid UUID representing an existing card.
A unique identifier for the transaction to ensure idempotency and easy tracking across systems.
Card Withdrawal Responses
Indicates whether the API request was successfully received and processed. A value of true means the request was accepted.
Human-readable response indicating the current state of the request. In this case, it confirms that the withdrawal is in progress.
The unique identifier of the transaction record. Useful for tracking or querying the specific charge attempt.
The timestamp indicating when the transaction was created. Follows the ISO 8601 date-time format.
The timestamp of the last update to the transaction. Will change if the transaction status is updated.
The monetary amount involved in the transaction, expressed in the main currency unit (e.g., 5 for $5).
The transaction amount in the smallest currency unit (e.g., cents). For example, 500 cents equals $5.00.
credit or debit. In this case, credit indicates the card is being credited (e.g., via a withdrawal request).
The nature of the transaction. withdrawal signifies funds are being removed from the card.
The current state of the transaction. Possible values include pending, success, or failed.
The currency code for the transaction, using ISO 4217 (e.g., usd for U.S. dollars).
A unique reference string associated with the transaction. Useful for reconciliation and tracking across systems.
The ID of the virtual card involved in this transaction. Can be used to query further details about the card.
Freeze Card
Block a card
Freeze Card Request
Specifies the response format expected by the client. Should be set to application/json.
Specifies the media type of the request payload. Must be application/json.
The unique identifier of the virtual card to be frozen. This ID is required to target the correct card.
Freeze Card Request
Indicates whether the request to freeze the card was successful. Typically `true` if the operation succeeded.
A short human-readable message confirming the result of the freeze operation.
The unique identifier for the frozen card. This ID can be used to fetch card details or perform other actions.
The exact timestamp of when the card was initially created. Useful for historical tracking.
Timestamp of the most recent update to the card, such as the freeze event.
Current available balance on the card at the time of freezing, usually in the smallest currency unit (e.g., cents).
Full card number of the virtual card. This is typically returned only in secure or sandbox environments for testing.
The last four digits of the card number. Often used to identify cards in logs or UI without exposing full card details.
Name displayed on the card or associated with the user for reference or verification.
Describes the type of card. For virtual cards, the value will usually be 'virtual'.
The issuing card brand such as Visa, Mastercard, etc., which can affect acceptance and processing rules.
Card Verification Value (CVV) used for additional card-not-present transaction security. Visible only in secure contexts.
Exact expiration date and time of the card in ISO 8601 format. Indicates when the card will no longer be valid.
Current operational status of the card. After a freeze request, this should show as 'frozen'.
The expiration date of the card formatted as MM/YYYY. Commonly used for UI display or third-party integrations.
A custom or system-generated identifier associated with this card for tracking or correlation.
The result status when the card was first created. Helps with auditing or debugging initial setup.
The unique identifier of the customer associated with this card. Useful for linking cards to accounts.
The city portion of the card’s billing address. Often required during card verification processes.
Street information of the card’s billing address. Typically matches the address used during registration.
Postal or ZIP code associated with the billing address. Can be used for validation in some transactions.
Two-letter country code (ISO 3166-1 alpha-2) for the billing address. Used for regional processing logic.
Full country name of the billing address. Used for display and verification purposes.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
Unfreeze Card
Unblock a frozen card.
Unfreeze Card Request
Specifies the response format expected by the client. Should be set to application/json.
Specifies the media type of the request payload. Must be application/json.
The unique identifier of the virtual card to be unfrozen. This ID is required to target the correct card.
Unfreeze Card Response
Indicates whether the request to unfreeze the card was successful. Typically `true` if the operation succeeded.
A short human-readable message confirming the result of the unfreeze operation.
The unique identifier for the unfrozen card. This ID can be used to fetch card details or perform other actions.
The exact timestamp of when the card was initially created. Useful for historical tracking.
Timestamp of the most recent update to the card, such as the unfreeze event.
Current available balance on the card at the time of unfreezing, usually in the smallest currency unit (e.g., cents).
Full card number of the virtual card. This is typically returned only in secure or sandbox environments for testing.
The last four digits of the card number. Often used to identify cards in logs or UI without exposing full card details.
Name displayed on the card or associated with the user for reference or verification.
Describes the type of card. For virtual cards, the value will usually be 'virtual'.
The issuing card brand such as Visa, Mastercard, etc., which can affect acceptance and processing rules.
Card Verification Value (CVV) used for additional card-not-present transaction security. Visible only in secure contexts.
Exact expiration date and time of the card in ISO 8601 format. Indicates when the card will no longer be valid.
Current operational status of the card. After an unfreeze request, this should show as 'active'.
The expiration date of the card formatted as MM/YYYY. Commonly used for UI display or third-party integrations.
A custom or system-generated identifier associated with this card for tracking or correlation.
The result status when the card was first created. Helps with auditing or debugging initial setup.
The unique identifier of the customer associated with this card. Useful for linking cards to accounts.
The city portion of the card’s billing address. Often required during card verification processes.
Street information of the card’s billing address. Typically matches the address used during registration.
Postal or ZIP code associated with the billing address. Can be used for validation in some transactions.
Two-letter country code (ISO 3166-1 alpha-2) for the billing address. Used for regional processing logic.
Full country name of the billing address. Used for display and verification purposes.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
Mock Transaction
Mock a virtual card transaction. Only available in sandbox environments for testing purposes.
Mock Transaction Request
Indicates the response format the client expects. Should be set to application/json.
Indicates the format of the request body. Should be application/json.
The unique identifier of the virtual card to mock a transaction against. Must be a valid card ID from your sandbox environment.
The amount to deduct or add to the card. Represented as a string to allow flexible formatting in test environments.
Defines the type of transaction. Can be deduct (to simulate a withdrawal) or credit (to simulate a top-up). Defaults to deduct.
Mock Transaction Response
true if the mock transaction was successfully created and processed by the sandbox server.
Human-readable message indicating the result of the mock operation, such as 'successfully mocked card transaction'.
Terminate Card
Permanently deactivate a virtual card. Once a card is terminated, it can no longer be used for transactions or reactivated.
Terminate Card Request
Indicates the response format the client expects. Should be set to `application/json`.
Specifies the format of the request body. Must be set to `application/json`.
The unique identifier of the virtual card to be terminated. This ensures the correct card is selected.
Terminate Card Response
Indicates whether the termination request was successfully processed by the API. A value of `true` means the operation completed without error.
A human-readable description of the result. This helps confirm that the termination action was acknowledged and executed.
A universally unique identifier assigned to the terminated card. Useful for referencing or performing follow-up operations on the same card.
The original creation timestamp of the virtual card. Can be used to understand the card's lifespan before termination.
Timestamp of the last update to the card object. In this case, it reflects the moment the card was terminated.
The remaining balance on the card at the time it was terminated. Typically used to confirm that no funds remain or to trigger a refund.
The full 16-digit virtual card number. Displayed only in secure environments or sandboxes for testing purposes.
The last four digits of the card number. Often used for identifying the card in user interfaces or audit logs without exposing the full number.
The display name or alias associated with the card, typically reflecting the name of the cardholder.
Indicates the type of the card, e.g., virtual. This helps differentiate it from other card products like physical cards.
The card scheme brand (e.g., VISA, Mastercard) that issued the virtual card. Determines where and how the card can be used.
The 3-digit CVV security code associated with the card. Only available in secure or sandbox environments for testing.
The full expiration timestamp of the card in ISO 8601 format. Shows the card’s original intended lifespan.
Current status of the card object. After termination, this should read terminated, meaning the card is permanently deactivated.
Formatted expiration date in MM/YYYY format, used for readability in UI or card input fields.
A unique identifier or tag used to reference the card externally, often provided during card creation.
Status message that reflects the outcome of the initial card creation process. This remains unchanged post-termination.
A unique identifier for the customer who owns the card. Helps link the card to a user account or CRM record.
City portion of the cardholder’s billing address. May be required for verification during transactions.
Street-level detail of the billing address. This should match the address used during card registration or verification.
ZIP or postal code from the billing address. Required in some countries for authorization checks.
Two-letter ISO 3166-1 alpha-2 country code (e.g., 'US' for United States). Used for regional validation.
Full name of the country for the billing address. Used for display purposes or country-based logic.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
Enable Airline Payment
This endpoint allows you to enable or disable airline-related payments for a specific virtual card.
Enable Airline Payment Request
Specifies the response format expected by the client. Should be set to application/json.
Specifies the media type of the request payload. Must be application/json.
The unique identifier of the virtual card that should be updated. This ensures the airline payment setting is applied to the correct card.
Set to true to allow airline-related transactions on this card or false to disable them. Use this to control merchant category access for airline payments.
Enable Airline Payment Response
Indicates whether the request was successful. If true, the airline payment setting was updated correctly.
A message from the server confirming the outcome of the request. Typically states if airline payments have been enabled or disabled.