KHPAY CLI

Official command-line tool for KHPAY merchants and developers. Zero dependencies — just Node.js 18+.

Install

npm install -g khpay

Quick start

khpay login                              # paste your ak_… key (Dashboard → Settings → API Keys)
khpay whoami                             # verify auth
khpay health                             # public health check (no auth)
khpay qr generate --amount=5.00 --note="Order #123"
khpay qr check txn_xxx                    # poll payment status
khpay tx list --status=paid --limit=20   # recent paid transactions
khpay stats --period=month               # aggregated stats

Config lives in ~/.khpay/config.json (chmod 0600). You can also use env vars:

export KHPAY_API_KEY=ak_...
export KHPAY_BASE_URL=https://khpay.site/api/v1

Commands

Account

| Command | Description | |---|---| | khpay login | Save API key to ~/.khpay/config.json | | khpay logout | Remove saved credentials | | khpay whoami | Show current merchant + key | | khpay me | Full account / plan / usage info | | khpay health | Public API health check (no auth) | | khpay config | Print current config |

Payments (ABA QR)

| Command | Description | |---|---| | khpay qr generate --amount=5 [--note= --currency=USD --callback-url= --success-url= --cancel-url=] [--test] | Create a QR payment | | khpay qr check <transaction_id> | Check payment status | | khpay qr expire <transaction_id> | Expire a pending transaction | | khpay qr batch <payments.json> | Batch-create up to 100 payments |

payments.json is either an array of { "amount": 5, "currency": "USD", "note": "…" } objects or { "payments": [ … ] }.

Bakong KHQR

| Command | Description | |---|---| | khpay bakong generate --account-id=name@bank --merchant-name="My Shop" --amount=5 [--type=individual\|merchant --static] | Generate a KHQR string + MD5 | | khpay bakong check <transaction_id> / --md5=<hash> | Check KHQR payment status | | khpay bakong decode <qr-string> | Decode & validate a KHQR string | | khpay bakong transactions [<id>] [--status= --limit=] | List / fetch Bakong transactions |

Transactions

| Command | Description | |---|---| | khpay tx list [--status= --from= --to= --page= --limit=] | List transactions | | khpay tx get <transaction_id> | Transaction details | | khpay tx tag <transaction_id> <tag> [tag…] | Add tags | | khpay tx tags <transaction_id> | List tags | | khpay stats [--period=today\|week\|month\|year\|all] | Statistics summary |

Webhooks

| Command | Description | |---|---| | khpay webhook list | List webhooks | | khpay webhook create <https-url> [--events=payment.paid,payment.failed] | Create webhook | | khpay webhook get <id> | Show one webhook | | khpay webhook update <id> [--url= --events= --active=0\|1] | Update webhook | | khpay webhook delete <id> | Delete webhook | | khpay webhook test <id> | Send a test delivery | | khpay webhook logs [--event= --page= --limit=] | Delivery history |

API keys

| Command | Description | |---|---| | khpay keys list | List additional API keys | | khpay keys create <name> [--expires=days] | Create a key | | khpay keys rotate [--expires=days] | Rotate primary key (invalidates current) | | khpay keys delete <id> | Delete a key |

Scheduled payments

| Command | Description | |---|---| | khpay scheduled list [--active] | List schedules | | khpay scheduled create --amount= --frequency=daily\|weekly\|monthly [--note= --start-at= --max-runs=] | Create schedule | | khpay scheduled cancel <id> | Deactivate schedule |

Observability

| Command | Description | |---|---| | khpay logs [--status=N --limit=N] | List recent API calls | | khpay inspect <log-id> | Full request/response for one log row | | khpay test <success\|decline\|gateway-down\|fraud> | Fire a test-mode charge |

Other

| Command | Description | |---|---| | khpay currencies | Supported currencies + rates | | khpay subscriptions | Current subscription | | khpay -v / --version | Print CLI version | | khpay help | Show all commands |

Test-mode magic amounts

khpay test <scenario> sends X-Test-Mode: true and a magic amount that the gateway short-circuits — no real QR, no quota, no money moves:

| Amount | Scenario | Outcome | |-------:|----------|---------| | 1 | success | paid | | 2 | decline | declined | | 3 | gateway-down | 502 | | 4 | fraud | fraud-block |

Authentication

All authenticated requests send Authorization: Bearer ak_…. Read-only keys may only call GET endpoints; refund-scoped keys are required for refunds.

License

MIT — © KHPAY