Products


Welcome to Checkbook's API! Checkout our various products to explore their features:

Checks

Send a single check or a million, we have the solution for you.

Invoices

You can request a Digital Check too. Simply send an invoice.

Subscriptions

Send or request recurring scheduled payments automatically.

Marketpace

Facilitate payments between your vendors and customers.




Integrations


We offer pre-built integrations to help your business do more with Checkbook. No coding required!




API Integration Flow


Just like our product, our API is simple to use and understand. To a look at the flow before to get a high-level understanding.



Getting Started



Quick Start


Although there are a variety of different use cases where Checkbook can be used, we will briefly describe three different environments to get you started

  • Demo - https://demo.checkbook.io/v3/

    • 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'
      
  • Sandbox - https://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. Again here, 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.

  • Production - https://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.


Authentication


All endpoints must be include an authorization header. We use the standard HTTP Authorization header to pass authentication information. Under the authentication scheme, the Authorization header has the following form:

Authorization: Key:Secret

These can be found on your developer settings page and click the Developer tab


OAuth


If you wish to send requests on behalf of another user, this user will use OAuth in order to generate a key that may be used on their behalf. More information on OAuth can be found here.

To start this authentication process, your user will access our OAuth authorization endpoint, which can be found at Checkbook OAuth.

This url requires 4 query parameters which are:

client_id: Your client ID found in Developer Settings
response_type: response_code
scope: check
redirect_uri: Your callback url found in Developer Settings

Once the user confirms they wish to allow a third party to send checks on their behalf, their browser will be redirect to the callback URI that has been specified, along with an AUTHORIZATION_CODE: http://REDIRECT_URI?code=AUTHORIZATION_CODE

The AUTHORIZATION_CODE can exchanged for bearer tokens using the token endpoint at https://checkbook.io/oauth/token

This url accepts a POST request with the parameters:

client_id: CLIENT_ID
grant_type: authorization_code
scope: check
code: AUTHORIZATION_CODE
redirect_uri: REDIRECT_URI
client_secret: SECRET_KEY

You will need to replace CLIENT_ID with your client id, REDIRECT_URI with your callback uri, SECRET_KEY with your secret key found in Developer Settings and CODE with the access_token returned in the previous step. A successful request will return an access_token along with some other information:

{
    "access_token": BEARER_TOKEN,
    "token_type": "Bearer",
    "refresh_token": REFRESH_TOKEN,
    "scope": "check"
}

The BEARER_TOKEN is then sent to api requests in place of the secret key:

Authorization: bearer BEARER_TOKEN

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 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 '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 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>
}