Virtual Card
Send Payments
Virtual Card
Overview
Virtual cards are the future! They offer security, privacy, and help those who are underbanked. It’s a 16 digit card which can be used for online purchasing, bills, and can even be added to a phone wallet like Apple Pay or Samsung Pay for use in stores. We also offer Just-In-Time (JIT) funding for having more control over the process while capturing unused funds.
The API reference for sending a Virtual Card can be found here. The interactive form allows you to test the API endpoint in our demo environment right from the reference page.
Request
curl --request POST \
--url https://demo.checkbook.io/v3/account/vcc \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"address":{"line_1":"1234 N. 1st Street","city":"San Francisco","state":"CA","zip":"12345"}}'
Response
{
"card_number":"4622941100000004"
"expiration_date":"2021-10-14"
"date":"2019-06-03 13:37:41"
"id":"0ac44e5679964cb9bc7f97966dc56a73"
}
In order to deposit a check to the new Virtual Card, an API call needs to be made to the Deposit a check endpoint by specifying in the account
field the id
of the Virtual Card.
Authorize transactions
We offer you the possibilty to allow / deny specific transactions for a virtual card in real time. You need to set a webhook for "Virtual Cards URL" in the Developer Settings, which will allow you to receive a callback when a new transaction is initiated on a virtual card.
The webhook you defined will receive a POST call from our servers with a payload containing the following values:
{
"amount": "the transaction amount",
"user_id": "id of the user associated with the virtual card",
"account_id": "virtual card id",
"recipient": "merchant description"
}
If the status code
of the webhook response is 2XX
, then it is considered that you approved the transaction. If not, the transaction is denied. For example, if your server responds with a 200
status code to the webhook request, then it means the transaction was approved. If on the other hand it responds with a 400
status code, then the transaction was denied.
PCI Compliance
If you want to store the Virtual Card info on your servers, you will need to comply with the Payment Card Industry Data Security Standards (PCI DSS). You can also reduce your PCI obligations by leveraging our hosted iframe solution documented below. You can include this iframe in your side to display the Virtual Card info.

Here is an example of a simple page that embeds an iframe for displaying the Virtual Card info:
<html>
<head>
<script src="https://app.checkbook.io/embed/vcc.js"></script>
</head>
<body>
<div>
<div>
<div id="container" style="width: 600px; margin: auto"></div>
</div>
</div>
<script type="text/javascript">
CheckbookVccDetails({
env: 'PROD',
card_id: '21577e853f9642dda8f8558458f70246',
signature: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjYXJkX2lkIjoiMjE1NzdlODUzZjk2NDJkZGE4Zjg1NTg0NThmNzAyNDYiLCJleHBpcmF0aW9uIjoiMjAyMS0wNC0yNyAwNTo0Njo0MC4xMjgwNTMifQ.62Hci1WUZZ9D0HJ8uM-c18e2EJB1b1cXrwvP8DdFIzo'
}).render('#container');
</script>
</body>
</html>
The CheckbookVccDetails
takes 3 parameters:
env
which can be eitherPROD
orSANDBOX
. If you useSANDBOX
the script will need to be loaded from https://sandbox.checkbook.io/embed/vcc.jscard_id
which is the id of the Virtual Card account (returned when creating the Virtual Card).signature
which is a JWT that encodes using the secret key and the SHA256 algorithm a payload of the following format:
{
"id": string,
"exp": int
}
where id
is the card's ID and exp
is an optional expiration time as a UTC UNIX timestamp (an int) specifying when the JWT should be expired/invalidated. Here is an example of payload:
{
"id": "21577e853f9642dda8f8558458f70246",
"exp": 1371720939
}
Card is issued by Pathward® N.A., Member FDIC, pursuant to a license from Visa USA Inc. Everywhere Visa debit cards are accepted within the United States. No ATM or cash access.
Create and fund a Virtual Card via API
To create and fund a virtual card via the API there are some prerequisites:
Prerequisites:
- Marketplace Functionality Enabled
- Prefund/Custodial Account
- API access
Instructions:
PASS IN: Specify a USER_ID - this can be any string you'd like.
RETURNED: Store the API key and secret (marketplace owner keys)
- Create Virtual Card within the user from (1)
PASS IN: Use the API Key:Secret from (1)
RETURNED: Store the ID that is returned
- Get Prefund Account ID from Get Bank Accounts endpoint.
PASS IN: Use marketplace owner/master account API credentials
RETURNED: Store the ID of the bank account with a non-NULL ‘balance’ this is the prefund account.
- Create Digital Check from the master account to recipient being user_id from (1)
PASS IN:
Use marketplace owner/master account API credentials
Recipient: user_id from (1)
Account: ID of the prefund account from (3).
RETURNED:
Store check_id (ID)
- Deposit the payment into the Virtual Card
PASS IN:
Use User's API credentials from (1)
Account: ID of virtual card from (2)
Check_id: check_id from (4)
Done! You've successfully created and funded a virtual card.
Note for Apple/Google Wallets:
In order to add the cards to an Apple/Google wallet, there is a verification code that gets sent to the email associated with a card. This can be any email.
To add an email when creating a card, add this parameter to the payload on the Add Card endpoint from Step 1:
{
“email”: STRING
}
Updated 26 days ago