hanzo-checkout

Checkout.js is an embeddable checkout widget for taking payments and pre-orders on any website.

Hanzo Checkout.js - Embeddable Payment Widget

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-commerce.md, hanzo/hanzo-commerce-api.md

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 |

Related Skills

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)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: checkout, payments, ecommerce, widget, stripe, paypal Prerequisites: Hanzo API key, browser environment