Virtual Cards

Creating a Virtual Card

The Brails Virtual Cards API lets you issue Virtual Visa USD cards. You can also access real-time card payment details, create cards instantly, freeze/unfreeze cards, and set spending limits.

Live

To create a card, a user must be registered as a card user (opens in a new tab) in our system. This requires basic KYC details.

We support all countries and accept different ID types depending on the country:

Note: For Nigerian users, the bvn number is required.

After a user is successfully registered, you can create a card by sending their email and the card type (visa) to the create_card endpoint (opens in a new tab). You must specify if the card is virtual or a giftcard.

Development

In development mode, you don't need to register a user or complete KYC. You can start by creating and using virtual cards immediately.

To create a virtual card in the sandbox, you'll need to provide the user’s firstName and lastName.

Once the card creation process starts, a webhook will notify you of the result: virtualcard.created.success for success or virtualcard.created.failed for failure.

To view card details, use the fetch card endpoint (opens in a new tab).

Top-Up Card

Business wallets are not linked directly to user cards. To add money to a card, the business can make a top-up (opens in a new tab) transaction from its USD wallet to the user’s card.

Withdrawal

Withdrawals (opens in a new tab) are the only way to debit a card. When a withdrawal happens, the funds are moved to the business's USD wallet.

Freeze Card

You can freeze (deactivate) a card to stop new transactions, usually for security or financial reasons. Freezing stops all transactions except withdrawals.

Unfreeze Card

You can unfreeze a card to allow transactions to resume after it was frozen.

Terminate Card

Terminating a card means the user can no longer use it. Any remaining funds are transferred to the user’s USD wallet.

Card Transactions

Card transactions include top-ups, withdrawals, and debit/credit actions made with the user’s card. Businesses can see these transactions through the API or on the dashboard.

Card payments and refunds are done in two steps: Authorization and Settlement. During Authorization, the card provider checks if the transaction can proceed, and if approved, the funds are released to the merchant. The merchant then needs to complete a Settlement to confirm they’ve received the funds. If no Settlement is made within 7 to 14 business days, the funds are returned to the cardholder’s balance.

Because of this two-step process, two notifications may be sent for the same transaction: one for Authorization and one for Settlement. When calculating a user’s card balance, be sure to account for both. Ignoring this could make it seem like there are duplicate transactions and cause an incorrect balance. You can filter out Settlement transactions or use the real-time balance from the card details.

Cross-Border Fees in Card Payments

Sometimes, merchants settle funds in a different currency. This may lead to extra charges called Cross Border Fees.

A payment made to a US company in USD can still have Cross Border Fees if the company settles the payment outside the US and then moves it back. These fees include a 3% currency conversion fee and a $0.50 settlement fee per transaction.

Webhook Events

Most actions with virtual cards are pending until completed, after which a webhook is sent.

A virtualcard.transaction.debit event is triggered for every debit transaction. If a transaction is reversed, a virtualcard.transaction.reversed event is sent to your Webhook URL.

It’s important to verify and test Webhook events before moving to production. You can test Bitnob's Webhooks by following this setup (opens in a new tab).

Visa vs. MasterCard

We offer both MasterCard and Visa Cards. Visa Cards work almost everywhere. Here’s a comparison to help you choose:

Card Issuing Fees

These fees apply to both MasterCard and Visa Virtual USD cards: