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:
envwhich can be eitherPRODorSANDBOX. If you useSANDBOXthe script will need to be loaded from https://sandbox.checkbook.io/embed/vcc.jscard_idwhich is the id of the Virtual Card account (returned when creating the Virtual Card).signaturewhich 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.
Updated about 2 months ago