Demo

This environment lets you get started with our API before even creating an account. Head to our Demo Environment. Go to settings and grab the API Key/Secret to try a cURL post or use the following.

curl --request GET \ 
          --url 'https://demo.checkbook.io/v3/check' \
          --header "Accept: application/json" \
          --header 'Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8
          

🚧

Demo Keys

Use the following Authorization value for the "Header Auth" in the interactive docs to test the requests:

d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8

You can also click on this link to refresh the API reference and have the Demo Keys pre-populated.

Sandbox

This environment lets you get started with developing your application without having to send out any real checks or do direct deposits. To begin, login here, go to settings, and in the developer tab, switch to the sandbox environment. Now go to settings and grab the key/secret required to make calls to this environment. The URL and authorization header will be different than the demo cURL POST seen previously.

curl --request GET \ 
--url 'https://api.sandbox.checkbook.io/v3/check' \
--header "Accept: application/json" \
--header 'Authorization: YOUR_SANDBOX_API_KEY:YOUR_SANDBOX_SECRET_KEY

Production

Once you're ready to take your application live, simply remove sandbox from the request url and change your authorization keys found here.

curl --request GET \ 
--url 'https://api.checkbook.io/v3/check' \
--header "Accept: application/json" \
--header 'Authorization: YOUR_API_KEY:YOUR_SECRET_KEY

When sending data across the Internet, there are many times when the unexpected happen. For example, a check could get created in our system, but due to a network issue the API response never gets back to the originator.

Our API supports idempotency so you can safely retry your requests without having to worry about a duplicate operation. User, bank account, check and invoice creation all support the Idempotency-Key header as part of the POST request.

This should be a unique key (it can be a counter, timestamp, UUID, etc) no longer than 255 characters that will not be re-used with that particular POST endpoint. 
If you make the same request with the same idempotent key, no new resource will be created on our end, but you will receive the same response as the first time. 
However, if you re-use an idempotent key with different parameters, the idempotent key will be ignored.

For example, if you create a new user with the email address [email protected], you will receive a response containing the keys for the new user. If this request has a header of Idempotency-Key: 1 and you repeat the same request (creating a user with email address [email protected]), you will receive the same API keys as in the initial request.

However, if you create a new user, [email protected], with a header of Idempotency-Key: 1 , a new user with a new set of API keys is created, even though the idempotent key was reused.

Another important detail is that the idempotent key only lasts for 3 minutes. 
So if you repeat the same request and reuse the idempotent key after more than 3 minutes, then the request will be considered as a new one and the idempotent key will be ignored.

Status Update Notification

If you would like to receive notifications when the status of a check has been updated, you can specify a webhooks url in your developer settings. When the status of a check is updated, you will receive a POST request to the specified url containing the id of the check that has been updated and its new status.

All of the webhooks notifications are signed with your unique webhooks key (from your developer settings) allowing you to verify that the request was sent from Checkbook.io and was not tampered with.

{
            'status': <check status>,
            'id': <check id>,
            'type':  "CHECK" | "INVOICE"
            }
            

❗️

Webhooks key by environment

The webhooks key is different in each environment. You need to use your Sandbox key in the Sandbox environment and your Production key in the Production environment.

Signature

Each webhooks POST request comes with an additional Signature field, which can be found in the HTTP headers. The signature will look something like:

Signature: nonce=1243549809,signature=4ee9758fc0bceb3ca1a2fe397fbd125364cfffdb04296fa118dab9778a4b3ce3
					

In order to verify the signature, you will concatenate the request body (the string value of the JSON payload) with the nonce value (i.e. 1243549809 in the above example). You will then compute a HMAC with the SHA256 hash function, where your webhooks key is the signing key, and the request body + nonce string is your message. The output of this HMAC should match the value of the signature field.

Example

For example, the signature in the example above (i.e. 4ee9758fc0bceb3ca1a2fe397 fbd125364cfffdb04296fa118dab9778a4b3ce3 ) is computed from the following values:

body: '{"status": "PAID", "id": "ed0af5fb335c47dd8eb53199ba50f5c4", "type": "CHECK"}'
          nonce: 1243549809
          webhooks key: '335b5728e25b47e88995fce207bff380'
          

Virtual Card Notification

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. See Authorize Virtual Card Transactions for more info. 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.

IP White List

Your application must be able to reach Checkbook's domain names for it to function properly and depending on how your integration operates, you may need to whitelist them. To help your integration operate securely, it must also verify that it’s communicating with our servers through one of our IP addresses listed below.

📘

Production (api.checkbook.io)

99.83.192.53
75.2.12.84

📘

Sandbox (api.sandbox.checkbook.io)

76.223.87.18
13.248.217.122

If your integration also receives webhooks from Checkbook, you should ensure these events originate from one of our IP addresses (the same for Production and Sandbox).

📘

Webhooks IP addresses

52.10.180.255
54.70.79.20

Status Update Notification

If you would like to receive notifications when the status of a check has been updated, you can specify a webhooks url in your developer settings. When the status of a check is updated, you will receive a POST request to the specified url containing the id of the check that has been updated and its new status.