Virtual Cards
Creating Virtual Card
The Brails virtual cards API allows you to offer Virtual Visa USD cards flexibly, with additional capabilities such as getting real-time card payment details, issuing cards on the fly, freezing/unfreezing cards and setting spending limits.
Live
To create a card, a user has to be registered as a card user (opens in a new tab) in our card section; this requires basic KYC details of your users.
We support all countries and have different ID types for different countries. Here is the list:
| 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: bvnnumber is a required field for Nigerian users.
🚧 Card Issuing There are some onboarding steps that need to be completed
before you can issue cards. Access to this API has to be pre-approved. Contact us at onboarding@onbrails.com requesting API access to cards if you need access to this API.
After successful registration of a card user, a card is created by sending the user's email and type of card (visa) to the create_card endpoint (opens in a new tab).
A cardType of virtual or giftcard is required.
Development
While on development mode, there's no need to register a user who has to go through the KYC process. You get started by creating a virtual card and using the cards immediately.
To create a virtual card on the sandbox, you need to provide additional information like firstName and lastName.
After creating a card, it is set up in progress. A webhook is sent after successfully creating a card - virtualcard.created.success and in the case of a failure - virtualcard.created.failed.
Use the fetch card endpoint (opens in a new tab) to get the full details of the card.
Top Up Card
Business wallets are not attached to users' cards. To fund or add money to a card, a top-up (opens in a new tab) transaction will be made from the business USD wallet to the user's card.
Withdrawal
Withdrawals (opens in a new tab) is the only internal debit transaction on a card. When withdrawals are made on a card, the amount withdrawn is sent to the business' USD wallet.
Freeze Card
Cards can be frozen(i.e. deactivated) to pause new transactions, primarily for security issues or financial purposes. Freezing of a card will pause all transactions except withdrawal.
Unfreeze Card
Unfreezing a card to resume transactions on a frozen card is also possible.
Terminate Card
Terminating a card stops any further use of the card by a user. On card termination, any funds on the card is moved to the user's USD wallet.
Card Transactions
Card Transactions include top-up, withdrawal and debit actions performed with users' cards. Businesses can view transactions via the API or on the dashboard:
Webhook Events
Most actions on virtual cards are pending actions, and on completion, a webhook is sent.
The following are virtual cards webhook events:
| Event Name | Description |
|---|---|
virtualcard.transaction.debit | Sent on every debit transaction on a card |
virtualcard.transaction.reversed | Sent on reversal of a card transaction |
virtualcard.transaction.declined.frozen | Sent when a card has been frozen |
virtualcard.transaction.declined.terminated | Sent when a card has been terminated |
Once subscribed to these events, they will be sent to your Webhook URL. Webhook events should be verified and tested before production. You can see more about webhooks here.
Card Issuing Fees
Card Creation $1 for every newly issued card Top Up $1 if funding is below $100 and 1% if funding is equal to or above $100 Chargeback $50 flat rate Termination no fee is charged for the termination of cards; you get back the balance on the card Card Declined $1 for automatic termination after 3 Insufficient funds Transactions Cross Border Fees A cross-border fee is charged when payment is made to shops outside the US. 3% + $0.5 of amount
These fees apply to our Visa Virtual USD cards.
| Action | Cost |
|---|---|
| Card Creation | $1 for every newly issued card |
| Top Up | $1 if funding is below $100 and 1% if funding is equal to or above $100 |
| Chargeback | $50 flat rate |
| Termination | no fee is charged for the termination of cards; you get back the balance on the card |
| Card Declined | $1 for automatic termination after 3 Insufficient funds Transactions |
| Cross Border Fees | A cross-border fee is charged when payment is made to shops outside the US. 3% + $0.5 of amount |