HitPay CLI

Command-line tool to manage payments, test webhooks, and generate QR codes from your terminal. Available for macOS, Linux, and Windows via npm.

The HitPay CLI is a command-line client for the HitPay API. Create payment requests, list charges, generate QR codes, and test webhooks end-to-end from your shell, scripts, and CI pipelines.

What’s Included

Account & Payments

Manage payment requests, charges, refunds, customers, invoices, subscriptions, beneficiaries, and transfers with a consistent hitpay <resource> <action> syntax.

Webhook Testing

hitpay listen tunnels your local server to the public internet and auto-registers a webhook endpoint. hitpay trigger simulates events without waiting for live traffic.

QR Codes in Terminal

hitpay qr create renders scannable QR codes directly in your terminal for PayNow, QRIS, PromptPay, GCash, DuitNow, and 50+ other methods across Southeast Asia.

Installation

1. Install the CLI

   Install globally with npm:

   npm install -g @hit-pay/cli
   

   Or run without installing:

   npx @hit-pay/cli --help
   

   Requires Node.js 18 or later.

2. Log in

   Interactive login (prompts for API key):

   hitpay login
   

   Or provide the key directly for non-interactive environments like CI:

   hitpay login --api-key sk-live-xxxxxxxxxxxx
   

   Get your API key from Dashboard → Settings → Payment Gateway → API Keys.

3. Verify

   Check you’re logged in and on the right environment:

   hitpay whoami
   

   Then run any command. For example, list recent charges:

   hitpay charge list
   

The CLI is in Beta (v0.1.0). If npm install -g @hit-pay/cli fails with a 404, install from source until the first npm publish:

git clone https://github.com/hit-pay/cli.git
cd cli && npm install && npm run build && npm link

Authentication & Config

Credentials are stored locally at ~/.hitpay/config.json with 0600 permissions. Inspect or update them with the config command:

hitpay config list
hitpay config set environment sandbox
hitpay config get currency

Environment variables

Override any stored config with env vars, useful for CI:

Variable	Description
HITPAY_API_KEY	API key; overrides ~/.hitpay/config.json
HITPAY_ENVIRONMENT	sandbox or production

Global flags

Available on every command:

Flag	Description
--env <environment>	One-shot environment override (e.g. --env production)
--json	Output raw JSON for piping to jq, scripts, or CI
--help	Show command help
--version	Print CLI version

The CLI defaults to sandbox. Run hitpay config set environment production (or pass --env production) only when you are ready to move real money.

Commands

Category	Commands
Account	login, logout, whoami, config set/get/list
Payment Requests	payment create, payment get, payment list, payment cancel
Charges	charge list, charge get, charge export
Refunds	refund
Customers	customer create/list/get/update/delete
Invoices	invoice create/list/delete
Subscriptions	plan create/list/get/delete, subscription create/list/get/cancel
Payouts	beneficiary create/list/delete, transfer estimate/create/list/get
QR Codes	qr create, methods
Webhooks (dev)	listen, trigger

Run hitpay <command> --help for full argument details on any command.

Webhook development flow

The CLI’s webhook tooling lets you build and test webhook handlers locally without ngrok setup or manual endpoint registration.

Forward live events to localhost

hitpay listen --forward-to http://localhost:3000/api/webhooks

This opens a secure tunnel, registers a temporary webhook endpoint with HitPay, and forwards every event to your local server. When you press Ctrl+C, the endpoint is cleaned up automatically.

Simulate events without live traffic

hitpay trigger charge.created
hitpay trigger --list   # show all supported event types

trigger posts a signed payload to whichever endpoint listen is currently forwarding, so you can exercise your handler’s signature verification, idempotency, and event routing without waiting for a real payment.

Usage Examples

Create a payment request

hitpay payment create \
  --amount 49.90 \
  --currency SGD \
  --email [e-mail] \
  --reference INV-2026-001

Returns the checkout URL and payment request ID. Add --json to parse the result in a script.

List & filter charges

hitpay charge list --status completed --limit 25 --json | jq '.data[].amount'

Combine with --env production to query the live account from a sandbox-configured machine without changing config.

Test a webhook handler

# Terminal 1: tunnel + auto-register endpoint
hitpay listen --forward-to http://localhost:3000/api/webhooks

# Terminal 2: simulate an event
hitpay trigger charge.created

Inspect the forwarded payload in your local server logs. The handler receives a real signed payload identical to production.

Generate a QR code

hitpay qr create --amount 100 --currency SGD --methods paynow

Renders the QR directly in your terminal. Scan with any PayNow-compatible banking app in Singapore.

Prerequisites

1. HitPay Account: create an account or use the sandbox environment
2. API Key: found in Settings → Payment Gateway → API Keys
3. Node.js 18 or later: check with node --version

Which AI tool should I use?

HitPay offers four AI tooling options that can be used together.

Tool	Use when you want to…
MCP Server	Query your sales, payouts, and transactions from Claude, signed in with your HitPay account
Claude Code Plugin	Build payment integrations with Claude Code using live API access and auto-triggered skills
Agent Skills	Generate HitPay integration code with Cursor, Copilot, Windsurf, or any AI assistant
CLI (this page)	Drive the API from your terminal, scripts, and CI pipelines, including webhook testing

Resources

GitHub Repository

View source, report issues, and contribute

HitPay MCP Server

Query your business data from an AI assistant

Claude Code Plugin

Live API access from inside Claude Code

Agent Skills

Skills for Cursor, Copilot, and Windsurf

API Reference

Full API documentation

Webhook Events

Handle payment notifications

Sandbox Guide

Test your integration

Feedback

Have suggestions or found an issue? Open an issue on GitHub.