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:
Country | Accepted Documents |
---|---|
Nigeria | vNIN , PASSPORT , DRIVERS_LICENSE , PVC |
Ghana | PASSPORT , DRIVERS_LICENSE , VOTERS_ID |
Kenya | PASSPORT , NATIONAL_ID |
Senegal | NATIONAL_ID , ECOWAS_ID |
Other Countries | NATIONAL_ID |
Note: For Nigerian users, the bvn
number is required.
Card Issuing
Before issuing cards, there are onboarding steps that need to be completed. Access to this API must be approved. Please contact us at onboarding@onbrails.com to request access.
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.
Time Restriction
It takes 5 minutes for Freeze and Unfreeze actions to take effect.
Dealing with Dollar Amounts
Amounts should be entered in cents. For example, $1 = 100 cents.
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:
Actions | Visa | MasterCard |
---|---|---|
Top Up | ✅ | ✅ |
Withdrawal | ✅ | ✅ |
Freeze | ✅ | ✅ |
Unfreeze | ✅ | ✅ |
Card Issuing Fees
These fees apply to both MasterCard and Visa Virtual USD cards:
Action | Cost |
---|---|
Card Creation | $1 for every newly issued card |
Top Up | $1 if the top-up is below $100, and 1% if the top-up is $100 or more |
Chargeback | $50 flat rate |
Termination | No fee is charged for card termination; remaining balance is returned to the user |
Card Declined | $1 for automatic termination after three failed transactions due to insufficient funds |
Cross Border Fees | A 3% + $0.50 fee applies for payments made to shops outside the US |