checkscanner

Check scanner server for Magtek and RDM check readers. It connects to the devices, extracts MICR data and check images, and serves them through a web interface and a JWT-authenticated REST API.

Requirements

• Python 3.6+
• pip 21.3.1+ (required on Python 3.6 to resolve pre-built wheels)
• GNU screen (optional, for checkscanner screen)

Installation

Update pip, then install the package:

pip install --upgrade pip
pip install checkscanner

To upgrade an existing install:

pip install --upgrade checkscanner

Setup

Pick a directory to run the server from. Config files and the database are created there, so always run checkscanner from the same directory.

mkdir checkscanner && cd checkscanner
checkscanner setup        # add -i to edit the config interactively first

Setup creates anything that is missing:

Setup also runs automatically before the server and admin console start.

Usage

Start the server, then open the web interface at http://localhost:8000/:

checkscanner

Server options can be passed directly, e.g. checkscanner --port 9000. Run checkscanner server --help for the full list.

Warnings and errors go to the console. Add --debug (or debug = true in config.toml) to see everything. Setup turns on a log file at logs/checkscanner.log, which gets info and above (everything with debug). Change or remove log_file in config.toml, or pass --log-file; the file rotates at 5 MB and keeps 5 old copies. To read the log file from the web interface, set ui_logs = true in config.toml or turn on "Allow viewing logs in the web UI" on the Settings page (off by default); admins then get a Logs page.

Magtek readers upload check images over FTP. The FTP server only starts when a Magtek reader connects, and its settings are optional: without ftp_user/ftp_pass in auth.toml it uses check-reader and a random password, which is sent to the reader on connect.

Open the interactive admin console:

checkscanner-cli

The admin console is an arrow-key menu for viewing server status, managing users and scanner profiles, editing config, regenerating auth keys, getting a bearer token, and starting the server (optionally restarting it when it stops).

Commands

Every admin console action is also available as a checkscanner subcommand. Run checkscanner --help or checkscanner <command> --help for details.

checkscanner server [options]   # Start the server (same as no arguments)
checkscanner setup [-i]         # Create missing config/, server.db and admin user (-i: edit config first)
checkscanner status             # Show config, database and connection status
checkscanner admin              # Open the admin console (same as checkscanner-cli)

checkscanner user list|add|passwd|delete
checkscanner profile list|add|delete
checkscanner config show|edit|rotate-keys
checkscanner screen ls|start|attach|logs|stop|restart
checkscanner token <username>[:<password>]   # or -u <username> [-p <password>]

Running in screen

To keep the server running after you log out, start it in a detached GNU screen session:

checkscanner screen                     # Start a session named "checkscanner"
checkscanner screen front --port 9000   # Start a session named "front" with server options
checkscanner screen ls                  # List running sessions, their state and directory
checkscanner screen logs front [-n 100] # Show recent output without attaching
checkscanner screen attach front        # Attach (detach again with Ctrl+A D)
checkscanner screen restart front       # Restart with the same options and directory
checkscanner screen stop front          # Stop a session (--all stops every session)

The session name defaults to checkscanner for every subcommand. Sessions show as checkscanner-<name> in screen -ls.

Scanning checks

1. Log in to the web interface with the admin credentials from admin_credentials.txt.
2. Add a scanner profile (web interface or checkscanner profile add) with the device's host and type.
3. Connect to the scanner and scan checks. Only one user can be connected to a given scanner at a time.

Supported devices:

API

Swagger UI is available at http://localhost:8000/docs while the server is running. Authenticate with POST /token (or checkscanner token <username>) and send the returned JWT as Authorization: Bearer <token>.