Virtual Credit Card

Documentation | Checkbook

Overview

The API reference for sending a Virtual Credit Card can be found here. The interactive form allows you to test the API endpoint in our demo environment right from the reference page.

Recipients instantly receive their check via email and can choose to either deposit the check online or print for in person or mobile deposit. You can find more details about the deposit options here.

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 Credit 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 Credit 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 Credit 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 Credit Card info.

Here is an example of a simple page that embeds an iframe for displaying the Virtual Credit Card info:

<html>
    <head>
        <script src="https://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 either PROD or SANDBOX. If you use SANDBOX the script will need to be loaded from https://sandbox.checkbook.io/embed/vcc.js
  • card_id which is the id of the Virtual Credit Card account (returned when creating the Virtual Credit 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
}