Hanzo Checkout.js

Checkout.js is an embeddable checkout widget for taking payments and pre-orders on any website. It renders a modal overlay with payment collection (Stripe and PayPal), shipping address, tax/shippin...

Overview

Checkout.js is an embeddable checkout widget for taking payments and pre-orders on any website. It renders a modal overlay with payment collection (Stripe and PayPal), shipping address, tax/shipping rate calculation, promo codes, and a thank-you screen with social sharing. Written in CoffeeScript using Riot.js 3 for UI components and Jade templates. Communicates with the Hanzo Commerce API via hanzo.js (now crowdstart.js).

Tech Stack

Language: CoffeeScript (compiled to JS)

UI Framework: Riot.js 3.0.7

Templates: Jade (Pug predecessor)

Styles: Stylus (compiled to CSS)

Build: Cakefile (CoffeeScript-based task runner via shortcake)

Bundler: requisite (CommonJS bundler)

Tests: Mocha + Chai + Selenium WebDriver + PhantomJS

CI: Travis CI

npm package: checkout.js v2.1.21

OSS Base

Repo: github.com/hanzoai/checkout.js (branch: master, 96 stars).

When to use

Adding a drop-in checkout modal to any HTML page

Collecting payments via Stripe or PayPal without building a checkout flow

Crowdfunding or pre-order campaigns with product management via Hanzo API

Legacy Hanzo Commerce API integrations

Hard requirements

Hanzo API key (access token for the Commerce API)

Products created in the Hanzo Commerce API (referenced by ID or slug)

Stripe and/or PayPal credentials configured in Hanzo dashboard

Browser environment (not a Node.js server-side library)

Quick reference

Item	Value
npm package	`checkout.js`
Version	2.1.21
Default branch	`master`
License	BSD-3-Clause
Language	CoffeeScript
UI framework	Riot.js 3.0.7
API client	`hanzo.js` (aliased as `crowdstart.js`)
CDN	`cdn.rawgit.com/hanzoai/checkout.js/v2.1.21/checkout.min.js`
Repo	`github.com/hanzoai/checkout.js`

One-file quickstart

Script tag integration

<a class="btn" href="#checkout">Buy Now</a>

<script src="https://cdn.rawgit.com/hanzoai/checkout.js/v2.1.21/checkout.min.js"></script>
<script>
  var Checkout = window.Crowdstart.Checkout

  var checkout = new Checkout('your-hanzo-api-key', {
    config: {
      currency: 'usd',
      processors: { stripe: true, paypal: false },
      showPromoCode: true,
      termsUrl: 'https://example.com/terms'
    },
    order: {
      currency: 'usd',
      items: []
    },
    user: {
      email: '',
      firstName: '',
      lastName: ''
    },
    thankyou: {
      header: 'Thank You!',
      body: 'Check your email for the order confirmation.',
      twitter: 'hanaboroai',
      facebook: 'hanzoai'
    },
    theme: {
      background: 'white',
      calloutBackground: '#27AE60',
      fontFamily: "'Helvetica Neue', Helvetica, Arial, sans-serif",
      borderRadius: 5
    }
  })

  // Add items by product ID or slug
  checkout.setItem('84cRXBYs9jX7w', 1)
  checkout.setItem('doge-shirt', 2)

  // Open the widget
  document.querySelector('.btn').addEventListener('click', function(e) {
    e.preventDefault()
    checkout.open()
  })
</script>

npm install

npm install checkout.js

var Checkout = require('checkout.js')

var checkout = new Checkout('your-api-key', {
  config: { currency: 'usd' }
})
checkout.setItem('product-slug', 1)
checkout.open()

Core Concepts

Architecture

┌─────────────────────────────────────────────────┐
│  Browser Page                                    │
│                                                  │
│  ┌─────────────┐    ┌────────────────────────┐  │
│  │ Buy Button  │───>│  Checkout Modal (Riot)  │  │
│  │ href=#checkout   │                        │  │
│  └─────────────┘    │  ┌──────────────────┐  │  │
│                     │  │ Screen Manager   │  │  │
│                     │  │  - Payment       │  │  │
│                     │  │  - Shipping      │  │  │
│                     │  │  - Thank You     │  │  │
│                     │  └──────────────────┘  │  │
│                     └───────────┬────────────┘  │
│                                 │                │
│                     ┌───────────▼────────────┐  │
│                     │  hanzo.js API Client    │  │
│                     │  (Crowdstart SDK)       │  │
│                     └───────────┬────────────┘  │
│                                 │                │
└─────────────────────────────────┼────────────────┘
                                  │
                      ┌───────────▼────────────┐
                      │  Hanzo Commerce API     │
                      │  (api.hanzo.ai)         │
                      └────────────────────────┘

Checkout Flow (Screen Script)

The widget follows a three-step flow defined by script: ['payment', 'shipping', 'thankyou']:

Payment Screen - Credit card entry (Stripe) or PayPal button, email, name

Shipping Screen - Address form with country/state selectors, tax and shipping rate calculation

Thank You Screen - Confirmation message with social sharing buttons (Facebook, Twitter, Google+, Pinterest, email)

Key Classes

Checkout - Main entry point. Instantiate with API key + options. Methods: open(), setItem(id, qty), setUser(user), update(), on(), off(), one()

Widget - Root Riot.js tag that mounts the modal

ScreenManager - Controls navigation between payment/shipping/thankyou screens

Events - Event bus (via crowdcontrol) for inter-component communication

Configuration Objects

config - Payment processors, currency, promo code toggle, terms URL, call-to-action text

taxRates - Array of {taxRate, city, state, country} objects, matched in order (first match wins)

shippingRates - Array of {shippingRate, city, state, country} objects, same matching logic

theme - Colors (background, light, dark, error, progress, spinner), font family, border radius

thankyou - Header, body, social sharing handles (facebook, twitter, googlePlus, pinterest, email)

analytics - Pixel tracking URLs

test - Custom API endpoint, PayPal sandbox toggle

Dependencies

Package	Purpose
`hanzo.js` (crowdstart.js)	Hanzo Commerce API client
`riot` 3.0.7	Reactive UI components
`crowdcontrol`	Event system for Riot
`card` 2.1.1	Credit card input formatting
`style-inject`	Runtime CSS injection
`bebop`	Dev server with live reload

Directory structure

checkout.js/
  checkout.js           # Built bundle (1.1MB)
  checkout.min.js       # Minified bundle (245KB)
  checkout.css          # Built stylesheet (45KB)
  package.json          # npm config, v2.1.21
  Cakefile              # Build/test tasks
  bebop.coffee          # Dev server config
  src/
    index.coffee        # Main Checkout class
    events.coffee       # Event definitions
    data/
      countries.coffee  # Country list for shipping
      currencies.coffee # Supported currencies
      states.coffee     # US state list
    utils/
      analytics.coffee  # Tracking pixel helper
      country.coffee    # Country lookup
      currency.coffee   # Currency formatting
      input.coffee      # Input validation
      theme.coffee      # Dynamic theme injection
    views/
      widget.coffee     # Root Riot tag
      modal.coffee      # Modal overlay
      header.coffee     # Widget header
      screenmanager.coffee  # Screen navigation
      invoice.coffee    # Order summary
      lineitem.coffee   # Single line item
      confirm.coffee    # Order confirmation
      promo.coffee      # Promo code input
      tabs.coffee       # Payment method tabs
      controls/         # Form input controls
      screens/
        screen.coffee   # Base screen class
        payment.coffee  # Credit card / PayPal entry
        shipping.coffee # Address form
        thankyou.coffee # Post-purchase screen
        choose.coffee   # Payment method selection
        paypal.coffee   # PayPal-specific flow
  templates/            # Jade templates for each view
  css/                  # Stylus source files
  vendor/               # Vendored JS/CSS (select2)
  examples/
    basic/              # Basic HTML integration example
  test/
    test.coffee         # Selenium WebDriver tests
    widget.html         # Test harness HTML
    ci-config.coffee    # Cross-browser CI config

Troubleshooting

Issue	Cause	Solution
Widget does not open	Button href not `#checkout` or `open()` not called	Use `checkout.open()` or set button `href="#checkout"`
Products not loading	Invalid product ID/slug	Verify product exists in Hanzo Commerce API
Stripe not working	Stripe processor disabled in config	Set `config.processors.stripe: true`
PayPal sandbox	Test mode not enabled	Set `test.paypal: true` in options
Old Node.js version	Requires Node >= 4.0.0	Upgrade Node.js
Build fails	Missing CoffeeScript	Run `npm install` to get devDependencies

hanzo/hanzo-commerce.md - Hanzo Commerce frontend

hanzo/hanzo-commerce-api.md - Hanzo Commerce API backend

hanzo/hanzo-form.md - Form validation/submission library (same era)

On this page