API Basics

Documentation | Checkbook

Authorization

All endpoints must include an Authorization header. We use the standard HTTP Authorization header to pass authentication information.

These can be found under on the Settings page. Choose the Developer tab from the menu panel and take note of the API Key and API Secret provided.

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.

Go to the Send a Check page on Checkbook.io

❗️

API Keys by Environments

The API keys are different in each environment.You need to use your Sandbox keys in the Sandbox environment and your Production keys in the Production environment. Click on the GO TO SANDBOX button to switch to the Sandbox environment and get the API keys.

Environments

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

https://api.sandbox.checkbook.io/v3/

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

https://api.checkbook.io/v3/

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.sandbox.checkbook.io/v3/check' \ --header "Accept: application/json" \ --header 'Authorization: YOUR_SANDBOX_API_KEY:YOUR_SANDBOX_SECRET_KEY

Error Codes

CodeMessageDetails
400Bad RequestYour request is invalid
401UnauthorizedYour API key is wrong
403ForbiddenYou do not have permission to access the requested endpoint
404Not FoundThe specified endpoint could not be found
405Method Not AllowedYou tried to access an endpoint with an invalid method
429Too Many RequestsYou’re sending too many requests! Slow down!
500Internal Server ErrorWe had a problem with our server. Try again later.
503Service UnavailableWe’re temporarily offline for maintenance. Please try again later.

Idempotent Requests

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.

Webhooks

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 Credit 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 Credit 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

Payment Statuses

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.

Digital Payment Statuses

Direct Deposit ACH/EFT

Use Case 1 - Elected Direct Deposit ACH/EFT

ACH Direct Deposit option was selected by recipient.

UNPAIDIN PROCESSPAID
Check email was sent but no action has been taken by the recipientRecipient elected to have funds deposited and entered their bank account informationFinal status. The payment has been successfully sent to the recipient's bank account

Use Case 2 - Direct Deposit ACH/EFT

Recipient bank information was included at the time of payment creation.

IN PROCESSPAID
All necessary information has been included at the time of payment creation. Payment is pending depositFinal status. The payment has been successfully sent to the recipient's bank account

Failed Status

Failed ACH payments will result in a notification to both the sender and recipient. In most cases ACH returns are caused by misentering or entering the wrong account information. Recipients will be able to submit a new credit destination. Once submitted the payment will reset to

IN PROCESS and attempt to credit again.

Void Process

Direct Deposit ACH payments can only be voided while IN PROCESS before settlement is run at 2pm and 5pm PST daily. For manual exceptions Checkbook can void payments.

Instant Pay (OCT)

Use Case 1 - Elected Instant Pay

Instant Pay option was selected by recipient.

UNPAIDIN PROCESS*PAID
Check email was sent but no action has been taken by the recipientRecipient elected to have funds deposited instantly and entered their debit card informationFinal status. The payment has been successfully sent to the recipient's debit account

Use Case 2 - Direct Deposit Instant Pay

Recipient bank information was included at the time of payment creation.

IN PROCESS*PAID
All necessary information has been included at the time of payment creation. Payment is pending depositFinal status. The payment has been successfully sent to the recipient's debit account

*Instant payments are sent instantly and therefore may only be IN PROCESS for a few seconds

Failed Status

Failed Instant Payments will result in a notification to both the sender and recipient. In most cases OCT returns are caused by misentering or entering the wrong card information. Recipients will be able to submit a new credit destination. Once submitted the payment will reset to IN PROCESS and attempt to credit again.

Void Process

Due to the nature of Instant Payments, they can not be voided unless the status is UNPAID. For manual exceptions Checkbook can void Instant Payments.

Expired Status

The status of EXPIRED is an end state, expired payments can not be acted upon and must be re-issued.

Physical Payment Statuses

Mailed Checks

Use Case 1 - Elected Mail

Mailed check option was selected by recipient

UNPAIDIN PROCESSMAILED
Check email was sent but no action has been taken by the recipientMailed check option was selected by the recipient. The check has been added to the print queue and will be printed in the next batch to be mailed*Final status. The check has been successfully printed and mailed

Use Case 2 - Direct Mail

Check was entered as a mailed check i.e. physical address was supplied at the time of check creation as opposed to an email address.

IN PROCESSMAILED
Mailed check option was selected by the recipient. The check will now be printed in the next batch to be mailed*Final status. The check has been successfully printed and mailed

*Checks are printed in a window from 12-2pm PST and mailed same day via USPS First Class Mail

Void Process

Mailed checks can not be voided from the checkbook dashboard. Payors wishing to void a mailed check must place a stop payment with their bank. For records and reconciliation purposes Checkbook can change the status to void.

Printed Checks

UNPAIDPRINTED
Check email was sent but no action has been taken by the recipientFinal status. The recipient selected to print the check and downloaded the print PDF. Print PDF's can only be viewed 5 times before getting locked. Contact Checkbook to reset counter if necessary.

Void Process

Printed checks can not be voided from the checkbook dashboard. Payors wishing to void a printed check must place a stop payment with their bank. For records and reconciliation purposes Checkbook can change the status to VOID.