Checkbook.io Node.js API Library

1.0.0 verified Sat Apr 25 auth: no javascript

A Node.js library for integrating with the Checkbook.io API to send digital, physical, and direct checks, manage invoices and subscriptions, and handle ACH payments. Version 1.0.0 is stable with a callback-based API. Requires Node >=4, no external runtime dependencies. Key differentiators: supports multiple check types (digital, physical, direct), CSV batch sending, idempotency keys, and OAuth bearer tokens. Release cadence is unknown. Alternatives include direct REST calls or other libraries, but this is the official Checkbook.io wrapper.

Common errors

error TypeError: Checkbook is not a constructor ↓

cause Using import instead of require with CommonJS package.

fix

Use const CheckbookAPI = require('checkbook-api');

error Error: Invalid API credentials ↓

cause Using demo credentials without setting env: 'demo'.

fix

Add env: 'demo' to the constructor options.

error UnhandledPromiseRejectionWarning: TypeError: callback is not a function ↓

cause Calling a method without a callback function.

fix

Provide a callback function as the last argument.

Warnings

gotcha All API methods use callbacks, not promises. Use util.promisify or wrap for async/await. ↓

fix Wrap with new Promise: new Promise((resolve, reject) => Checkbook.checks.sendDigitalCheck(params, (err, res) => err ? reject(err) : resolve(res)))

gotcha Environment parameter 'env' defaults to production if omitted, but demo sandbox keys only work with env: 'demo' or 'sandbox'. ↓

fix Always specify env when using test credentials: env: 'demo'

gotcha OAuth bearer token is set as 'bearer' property, not 'api_key' and 'api_secret'. ↓

fix Use bearer in constructor: new CheckbookAPI({ bearer: '...', env: 'demo' })

gotcha Idempotency key is optional third argument; passing it as part of params will be ignored. ↓

fix Call method with three arguments: sendDigitalCheck(params, callback, idempotencyKey)

Install

npm install checkbook-api-ts

yarn add checkbook-api-ts

pnpm add checkbook-api-ts

Imports

CheckbookAPI

wrong

import checkbook from 'checkbook-api';

correct

const checkbook = require('checkbook-api');

Package uses CommonJS; no default export for ESM.

CheckbookAPI constructor

wrong

const Checkbook = new Checkbook();

correct

const Checkbook = new CheckbookAPI({ api_key: '...', api_secret: '...' });

Constructor requires api_key and api_secret (or bearer) object.

checks.sendDigitalCheck

wrong

Checkbook.sendDigitalCheck(params, callback);

correct

Checkbook.checks.sendDigitalCheck(params, callback);

Methods are namespaced under endpoints like Checkbook.checks.

Quickstart

Initializes the Checkbook.io client with demo credentials and sends a digital check via callback.

const CheckbookAPI = require('checkbook-api');
const Checkbook = new CheckbookAPI({
  api_key: 'd6aa2703655f4ba2af2a56202961ca86',
  api_secret: 'dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8',
  env: 'demo'
});
Checkbook.checks.sendDigitalCheck({
  name: 'Widgets Inc.',
  recipient: 'widgets@example.com',
  description: 'Test Send Check',
  amount: 10.00
}, function(err, res) {
  if (err) console.log('Error:', err);
  else console.log('Response:', res);
});