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 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:
| Countries | 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 [email protected] 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. 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 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 transaction will be made from the business USD wallet to the user's card.
Withdrawal
Withdrawals 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.
Time Restriction
Freeze and Unfreeze actions have 5-minute time restrictions. That is, they are only effective after 5 minutes.
Dealing with dollar amounts
Every amount field in all card endpoints are to be entered in cents.For example, $5 is written as 500. $1=100 cents.
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 | 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
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. 2.5% + $0.5 of amount |
| Unsettled authorization | An unsettled authorization fee is charged when payment fails due to insufficient funds on the user's card. Domestic (payments within the United States) = $0.015 International (payments outside of the United States) = $0.32. |