Overview


Thanks for checking out our API (no pun intended)! Our API allows developers to send checks and invoices with ease. Although there are a variety of different use cases where Checkbook can be used, we will briefly describe three different scenarios to get you started but before this, please understand the differences between our sandbox, production and test environments.

If you wish to implement our API, sandbox can be used to be used to test API calls. The sandbox url required for the API call is: https://sandbox.checkbook.io/v3/ {endpoints}. Once you’re ready to deploy your application with our API, the sandbox url can be replaced with the production url: https://checkbook.io/v3/ {endpoints}. When switching from sandbox to production, your authorization keys will need to be switched. For sandbox keys, go to: https://sandbox.checkbook.io/account/settings and click the developer tab. For production keys, go to: https://checkbook.io/account/settings and click the developer tab. If you don’t understand this now, don’t worry! Continue reading through our documentation and we will guide you again soon!

Authentication


All endpoints must be include an authorization header. We use the standard HTTP Authorization header to pass authentication information. (The name of the standard header is unfortunate because it carries authentication information, not authorization.) Under the authentication scheme, the Authorization header has the following form:

Authorization: Key:Secret

Developers with access to our api are issued an api key and api secret when they register. These can be found on your developer settings page at: https://checkbook.io/account/settings and click the Developer tab

Error Codes


The Checkbook API uses the following error codes:

400 Bad Request – Your request is invalid

401 Unauthorized – Your API key is wrong

403 Forbidden – You do not have permission to access the requested endpoint

404 Not Found – The specified endpoint could not be found

405 Method Not Allowed – You tried to access an endpoint with an invalid method

429 Too Many Requests – You’re sending too many requests! Slow down!

500 Internal Server Error – We had a problem with our server. Try again later.

503 Service Unavailable – We’re temporarially offline for maintanance. 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 'foo@example.com‘, 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 'foo@example.com‘), you will receive the same api keys as in the initial request. However, if you create a new user, bar@example.com, 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

Webhooks


If you would like to receive notifications when the status of a check has been updated, you can specify a webhook url in your developer profile: https://checkbook.io/account/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:

{‘id’: <check id>, ‘status’: <check status>}

Testing


We provide a sandbox environment for testing and development.

All requests to https://demo.checkbook.io/v3/ and https://sandbox.checkbook.io/v3/ (instead of https://checkbook.io/v3/) are for testing purposes, and will not result in the debit or credit of funds from bank accounts. https://demo.checkbook.io allows you to test out our system without signing up using a public set of api keys, while sandbox allows you to test our system using your own account.