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!

Sending checks and requesting funds With your existing Checkbook.io account, you can easily send checks and request payments using one simple POST call to our check and invoice endpoints. We have two different endpoints for checks (one for paper checks that are mailed via USPS, and one for digital checks that are delivered via email) and one endpoint for invoices (invoices are only delivered via email).

Sending checks and requesting funds on behalf of other users There are times when it may be useful to make or receive payments on behalf of another user. With our OAuth API, other users can easily grant you access to send or receive checks on their behalf. Once access has been granted, the access token will be securely sent to a callback url on your server.

Marketplace For developers who want complete control over the entire experience, this option may best fit your needs. For our marketplace solution, we give you the endpoints and let you control the UI/UX for all payments within your marketplace. For this integration, there are a few steps that will need to performed before merchants within your marketplace can send payments:

  1. You will first need to onboard your marketplace users. These users will be unique to your business, so if they already have a checkbook.io account, or they visit https://checkbook.io and sign up for an account, this will be a separate account from the marketplace account.
  2. To onboard these users, you will create a POST request to /v3/user (https://www.checkbook.io/docs/api#user), supplying a user_id for the user, and the user’s name. The response from this api call will include the new user’s api key and api secret. For additional further requests to onboard/send money on behalf of this user, you will use their api keys.
  3. Next, you will need to add a bank for the new user (https://www.checkbook.io/docs/api#bank). If you know the user’s routing and account number, you can add their account with a POST request to /v3/bank. This will create a pending bank account. This means that we will generate microdeposit transactions to the user’s account to verify ownership. These typically show up the next business day, but may show up the same business day. The bank account can then be verified by POSTing the microdeposit amounts to /v3/bank/verify
  4. Once a verified bank account has been added for the marketplace user, payments can be sent between users of the marketplace by inserting the user_id in the <recipient> field of the /v3/check/digital POST request

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 and https://sandbox.checkbook.io (instead of https://checkbook.io) 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.