NAV
python ruby php node

Authentication

import base64
import hashlib
import hmac

def authorization_header(endpoint, verb, content_type, timestamp, public_key, private_key):
    """Generate Authroization header for Checkbook.io API requests

    Args:
        endpoint (str)- API endpoint (e.g. /v2/check)
        timestamp (str)- timestamp in HTTP Date header
        verb (str)- HTTP verb [GET, POST, PUT, DELETE]
        content_type (str)- HTTP content type (typically application/json for POST and empty for GET)
        public_key (str)- public API key
        private_key (str)- private API key
    """
    message = verb + content_type + timestamp + endpoint
    dig = hmac.new(private_key, msg=str(message), digestmod=hashlib.sha256).digest()
    sig = base64.b64encode(dig).decode()
    return '%s:%s' % (public_key, sig)
require 'openssl'
require 'base64'

def authorization_header(endpoint, verb, content_type, timestamp, public_key, private_key)
    #Generate Authroization header for Checkbook.io API requests
    #
    #Args:
    #    endpoint (str)- API endpoint (e.g. /v2/check)
    #    timestamp (str)- timestamp in HTTP Date header
    #    verb (str)- HTTP verb [GET, POST, PUT, DELETE]
    #    content_type (str)- HTTP content type (typically application/json for POST and empty for GET)
    #    public_key (str)- public API key
    #    private_key (str)- private API key
    message = verb + content_type + timestamp + endpoint
    dig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), private_key, message)
    sig = Base64.strict_encode64(dig)
    return "#{public_key}:#{sig}"
end
/**
 *Generate Authroization header for Checkbook.io API requests
 *
 *Args:
 *    endpoint (str)- API endpoint (e.g. /v2/check)
 *    timestamp (str)- timestamp in HTTP Date header
 *    verb (str)- HTTP verb [GET, POST, PUT, DELETE]
 *    content_type (str)- HTTP content type (typically application/json for POST and empty for GET)
 *    public_key (str)- public API key
 *    private_key (str)- private API key
 */
function authorization_header($endpoint, $verb, $content_type, $timestamp, $public_key, $private_key) {
    $message = $verb . $content_type . $timestamp . $endpoint;
    $dig = hash_hmac('sha256', $message, $private_key, true);
    $sig = base64_encode($dig);
    return $public_key . ":" . $sig;
}
const crypto = require('crypto');

/**
 *Generate Authroization header for Checkbook.io API requests
 *
 *Args:
 *    endpoint (str)- API endpoint (e.g. /v2/check)
 *    timestamp (str)- timestamp in HTTP Date header
 *    verb (str)- HTTP verb [GET, POST, PUT, DELETE]
 *    content_type (str)- HTTP content type (typically application/json for POST and empty for GET)
 *    public_key (str)- public API key
 *    private_key (str)- private API key
 */
function authorization_header(endpoint, verb, content_type, timestamp, public_key, private_key) {

    var message = verb + content_type + timestamp + endpoint;
    var hmac = crypto.createHmac('sha256', private_key);
    return public_key + ":" + hmac.update(message).digest("base64");
}

All endpoints must be signed with a private api key. 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:Signature

Developers with access to our api are issued a public and private access key when they register. The signature element is a HMAC-SHA256 of selected elements from the request, and so the signature part of the Authorization header will vary from request to request. The selected elements from the request are the HTTP method, Date, Content-Type and path. With this in mind, the signature will look something like:

Base64(HMAC-SHA256(PrivateKey, Selected elements))

Where the selected elements are:

HTTP method (all CAPS) + Content-Type + Date + Path

For example, if we are making a json-encoded POST request to https://checkbook.io/v2/check at 2016-07-11 02:12:19.419709 with the secret key sUperSeCREtKEY the selected elements will look like:

POSTapplication/json2016-07-11 02:12:19.419709/v2/check

and the resulting signature should come out to be:

zSr6wLiAHhXZQ54PCbu/4z9t95+rj5u6Dj+nnvI+uX8=

Sandbox

We provide a sandbox environment for testing and development.

All requests to 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.

API Endpoints

Check

Checks are what we specialize in. Our users send checks to both individuals and businesses. Checks in our system can be assigned a variety of statuses (UNPAID, PAID, IN_PROCESS, VOID, EXPIRED, PRINTED, MAILED). Checks remain in the UNPAID state until the recipient prints the check or adds a bank account. Once the bank account is verified, the check moves to the IN_PROCESS state. This means that our system has created a money-transfer transaction for this check. This process involves debiting the sender’s account, and crediting the recipient’s account. Once the recipients bank account has been credited, the paid parameter will return YES.

Create digital check

Example request

import requests
import datetime
import json

public_key = 'PUBLIC_KEY'
private_key = 'PRIVATE_KEY'
date = datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S.%f')
headers = {'Content-Type': 'application/json',
           'Date': date,
           'Authorization': authorization_header('/v2/check/digital', 'POST', 'application/json',
                                                 date, public_key, private_key)}
data = {'amount': 1.23, 'first_name': 'James', 'last_name': 'Smith',
        'recipient': 'jsmith@example.com', 'check_number': 1001,
        'description': 'Cleaning services payment'}
requests.post('https://checkbook.io/v2/check/digital', headers=headers, data=json.dumps(data))

Example response (201)

{
    "id": "12345678123456781234567812345678",
    "date": "2014-01-01 12:15:15.123456",
    "check_num": 1001,
    "description": "Cleaning services payment",
    "status": "IN_PROCESS",
    "amount": 1.23,
    "token": "87654321876543218765432187654321",
    "paid": "YES",
    "recipient": "jsmith@example.com",
    "name": "James Smith"
}

New checks may be sent to either an individual or a business. If the check is sent to an individual, the first_name and last_name fields must be populated. Otherwise, the first_name and last_name fields can be omitted, and the business field must be populated. If the sender wishes to set the check number on the check, a number can be passed in using the check_number field. Otherwise, we will begin numbering checks at 1001 (and will increment the number for each successive check).

HTTP Request

POST https://checkbook.io/v2/check/digital

Arguments

Parameter Type Required Description
amount float Required Amount for check
business* string Optional Recipient’s business name
check_number integer Optional Check number for check
description string Optional Message to appear in the memo field
first_name* string Optional Recipient’s first name
last_name* string Optional Recipient’s last name
recipient string Required Recipient’s email address
*If sending checks to an individual, first_name and last name are required and business is omitted. If sending checks to a business, business is required and first_name and last name are omitted. Also all the name fields i.e. first_name, last_name and business_name cannot be NULL and must have atleast 2 characters if they are present

Cancel check

Example request

import requests
import datetime

public_key = 'PUBLIC_KEY'
private_key = 'PRIVATE_KEY'
date = datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S.%f')
headers = {'Date': date,
           'Authorization': authorization_header('/v2/check/cancel/12345678123456781234567812345678', 'GET', '',
                                                 date, public_key, private_key)}
requests.get('https://checkbook.io/v2/check/cancel/12345678123456781234567812345678', headers=headers)

Example response (200)

HTTP Request

GET https://checkbook.io/v2/check/cancel/<ID>

URL Parameters

Parameter Description
ID The ID of the check to cancel

List all checks

Example request

import requests
import datetime

public_key = 'PUBLIC_KEY'
private_key = 'PRIVATE_KEY'
date = datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S.%f')
headers = {'Date': date,
           'Authorization': authorization_header('/v2/check', 'GET', '',
                                                 date, public_key, private_key)}
requests.get('https://checkbook.io/v2/check', headers=headers)

HTTP Request

GET https://checkbook.io/v2/check

Example response (200)

[
    {
        "id": "65432178123456781234567812345678",
        "date": "2014-01-02 13:14:15.234567",
        "check_num": 1002,
        "description": "January rent",
        "status": "PENDING",
        "amount": 1027.00,
        "token": "23456781876543218765432187654321",
        "paid": "NO",
        "address": "rent@example.com",
        "name": "Apartment Company Inc."
    },
    {
        "id": "12345678123456781234567812345678",
        "date": "2014-01-01 12:15:15.123456",
        "check_num": 1001,
        "description": "Cleaning services payment",
        "status": "PAID",
        "amount": 1.23,
        "token": "87654321876543218765432187654321",
        "paid": "YES",
        "address": "jsmith@example.com",
        "name": "James Smith"
    }
]

View check details

Example request

import requests
import datetime

public_key = 'PUBLIC_KEY'
private_key = 'PRIVATE_KEY'
date = datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S.%f')
headers = {'Date': date,
           'Authorization': authorization_header('/v2/check/12345678123456781234567812345678', 'GET', '',
                                                 date, public_key, private_key)}
requests.get('https://checkbook.io/v2/check/12345678123456781234567812345678', headers=headers)

Example response (200)

{
    "id": "12345678123456781234567812345678",
    "date": "2014-01-01 12:15:15.123456",
    "check_num": 1001,
    "description": "Cleaning services payment",
    "status": "PAID",
    "amount": 1.23,
    "token": "87654321876543218765432187654321",
    "paid": "YES",
    "address": "jsmith@example.com",
    "name": "James Smith"
}

HTTP Request

GET https://checkbook.io/v2/check/<ID>

URL Parameters

Parameter Description
ID The ID of the check to retrieve

Invoice

Checkbook users can also send invoices to request payment from others. Recipients of the invoice can then easily pay the invoices using Digital Checks™.

Create invoice

New invoices may be sent to either an individual or a business. If the invoice is sent to an individual, the first_name and last_name fields must be populated. Otherwise, the first_name and last_name fields can be omitted, and the business field must be populated.

HTTP Request

POST https://checkbook.io/v2/invoice

Example response (201)

{
   "id": "12345678123456781234567812345678",
   "date": "2014-01-01 12:15:15.123456",
   "invoice_num": 1001,
   "email": "designer@example.com",
   "description": "Website design",
   "status": "UNPAID",
   "amount": 1.23,
   "type": "outgoing",
   "name": "Widgets Inc."
}

Arguments

Parameter Type Required Description
amount float Required Amount for invoice
attachment string Optional Base64 encoded PDF file (included in invoice email)
business string Optional Recipient’s business name
description string Required Description field for invoice
email string Required Recipient’s email address
first_name string Optional Recipient’s first name
last_name string Optional Recipient’s last name

Cancel invoice

HTTP Request

GET https://checkbook.io/v2/invoice/cancel/<ID>

Example response (200)

URL Parameters

Parameter Description
ID The ID of the invoice to cancel

List all invoices

HTTP Request

POST https://checkbook.io/v2/invoice

Example response (200)

[
    {
        "id": "65432178123456781234567812345678",
        "date": "2014-01-02 13:14:15.234567",
        "invoice_num": 1002,
        "email": "consulting@example.com",
        "description": "Consulting services",
        "status": "UNPAID",
        "amount": 1000.00,
        "type": "outgoing",
        "name": "Consulting Inc."
    },
    {
        "id": "12345678123456781234567812345678",
        "date": "2014-01-01 12:15:15.123456",
        "invoice_num": 1001,
        "email": "designer@example.com",
        "description": "Website design",
        "status": "UNPAID",
        "amount": 235.00,
        "type": "incoming",
        "name": "John Smith"
    }
]

List invoice details

HTTP Request

POST https://checkbook.io/v2/invoice/<ID>

Example response (200)

{
    "id": "12345678123456781234567812345678",
    "date": "2014-01-01 12:15:15.123456",
    "invoice_num": 1001,
    "email": "designer@example.com",
    "description": "Website design",
    "status": "UNPAID",
    "amount": 235.00,
    "type": "incoming",
    "name": "John Smith"
}

URL Parameters

Parameter Description
ID The ID of the invoice to retrieve

Subscription

Subscriptions are created to send recurring digital checks and invoices. These subscriptions can recur weekly or monthly and can have a fixed duration (e.g. 3 weeks), or can be unlimited. Additionally, users can specify periods for which they would like to skip the recuring digital check or invoice. If a subscription is set to recur at the end of a month (e.g. January 30), but the next month has fewer days, the subscription will recur on the last day of the month (e.g. February 28 in common years).

Create check subscription

HTTP Request

POST https://checkbook.io/v2/subscription/check

Example response (201)

{
  "id": "65432178123456781234567812345678",
  "date": "2014-01-02 13:14:15.234567",
  "type": "CHECK",
  "interval": "MONTHLY",
  "amount": 1.23,
  "recipient": "Widgets Inc.",
  "address": "jsmith@example.com",
  "description": "Monthly widget payment",
  "account": "c221a2345457460a833289b627048b1d",
  "duration": 12,
  "name": "Recurring Check #1"
}

Arguments

Parameter Type Required Description
amount float Required Amount for recurring check
business string Optional Recipient’s business name
description string Optional Message to appear in the memo field
duration integer Optional Total number of checks to send (defaults to infinite)
first_name string Optional Recipient’s first name
last_name string Optional Recipient’s last name
name string Optional Name for subscription
interval enum Required Recurring interval for subscription [MONTHLY, WEEKLY]
recipient string Required Recipient’s email address

Create invoice subscription

HTTP Request

POST https://checkbook.io/v2/subscription/invoice

Example response (201)

{
  "id": "65432178123456781234567812345678",
  "date": "2014-01-02 13:14:15.234567",
  "type": "INVOICE",
  "interval": "MONTHLY",
  "amount": 1.23,
  "recipient": "Widgets Inc.",
  "address": "jsmith@example.com",
  "description": "Monthly widget invoice",
  "account": "c221a2345457460a833289b627048b1d",
  "duration": 12,
  "name": "Recurring Invoice #1"
}

Arguments

Parameter Type Required Description
amount float Required Amount for recurring invoice
business string Optional Recipient’s business name
description string Required Description field for invoice
duration integer Optional Total number of invoices to send (defaults to infinite)
first_name string Optional Recipient’s first name
last_name string Optional Recipient’s last name
name string Optional Name for subscription
interval enum Required Recurring interval for subscription [MONTHLY, WEEKLY]
recipient string Required Recipient’s email address

Update subscription

Some subscriptions may be skipped. For example, if the user has an infinitely recurring check set up, but would like to skip the fith and eighth payments, [5, 8] can be specified using the skip parameter.

HTTP Request

PUT https://checkbook.io/v2/subscription/<ID>

Example response (200)

URL Parameters

Parameter Description
ID The ID of the subscription to update

Arguments

Parameter Type Required Description
skip array Required List of subscriptions to skip

Delete subscription

HTTP Request

DELETE https://checkbook.io/v2/subscription/<ID>

Example response (200)

URL Parameters

Parameter Description
ID The ID of the subscription to cancel

List all subscriptions

HTTP Request

GET https://checkbook.io/v2/subscription

Example response (200)

{   
    "subscriptions":    [
        {
            "id": "65432178123456781234567812345678",
            "date": "2014-01-02 13:14:15.234567",
            "type": "INVOICE",
            "interval": "MONTHLY",
            "amount": 1027.00,
            "recipient": "John Doe",
            "address": "renter@example.com",
            "description": "Monthly rent",
            "account": "c221a2345457460a833289b627048b1d",
            "duration": -1,
            "skipped": [],
            "name": "Apartment #000 Rent"
        },
        {
            "id": "12345678123456781234567812345678",
            "date": "2014-01-01 12:15:15.123456",
            "type": "CHECK",
            "interval": "WEEKLY",
            "amount": 25,
            "recipient": "Johnny Smith",
            "address": "jsmith@example.com",
            "description": "Summer allowance",
            "account": "f942d22f8bbd4ce084897c55fda7e909",
            "duration": 10,
            "skipped": [3, 7],
            "name": "Johnny's allowance"
        },
    ]
}

List subscription details

HTTP Request

GET https://checkbook.io/v2/subscription/<ID>

Example response (200)

{
  "id": "65432178123456781234567812345678",
  "date": "2014-01-02 13:14:15.234567",
  "type": "INVOICE",
  "interval": "MONTHLY",
  "amount": 1027,
  "recipient": "John Doe",
  "address": "renter@example.com",
  "description": "Monthly rent",
  "account": "c221a2345457460a833289b627048b1d",
  "duration": -1,
  "skipped": [],
  "name": "Apartment #000 Rent"
}

URL Parameters

Parameter Description
ID The ID of the subscription to retrieve

API Clients

Accounting Seed

Checkbook provides a seamless turn-key connection to the Accounting Seed General Ledger though the Cash Disbursements object. In a single click, organizations can submit and process a check online all through one business management platform. With Checkbook and Accounting Seed issuing a payment and sending a check has never been easier! Check out our Accounting Seed integration for more details

QuickBooks

You can use Digital Checks™ to send money and pay bills within QuickBooks with the Checkbook app. When creating a check in Quickbooks, make sure to check ‘Print Later’ and will automatically send your payment.

Web Browser

<form id="checkbook_io" method="POST">
          <input type="hidden" id="checkbook_var"
            data-key="PUBLISHABLE KEY"
            data-amount='100'
            data-name="Merchant Name"
            data-for="Merchant Name"
            data-description="Your item's description"
            data-user-email ='buyer_email_address@example.com'
            data-redirect-url ="https://example.com/callback"            
            data-firstName ='Buyer First Name'
            data-lastName ="Buyer Last Name"/>
          <script src="https://www.checkbook.io/static/api/v1/checkbook.js" class="checkbook-button" id="checkbook_api_js">
          </script>
</form>

If you already have a website up and running, and would rather interact with HTML, check out our embedded (iframe) and custom (HTML) forms. If you’re using a Shopping Cart we also have plugins for Wordpress and Magento. For more information, check out our Github page.

Errors

The Checkbook API uses the following error codes:

Error Code Meaning
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.