uqpay-cli

uqpay-cli

SDK/CLI 3.1.0 retains the complete 4.0.0 feature set under the 3.x version line. Review contract migration guidance before upgrading.

The official UQPAY CLI tool — built for humans and AI Agents. Covers Banking, Card Issuing, and Payment APIs with 100+ commands and 6 AI Agent Skills.

Install · Quick Start · AI Agent Skills · Commands · Advanced · Contributing

Why uqpay-cli?

• Agent-Native Design — 6 structured Skills out of the box, AI Agents can operate UQPAY APIs with zero extra setup
• Wide Coverage — 3 business domains (Banking, Issuing, Payment), 100+ commands, Connect & Simulator included
• Zero Type Hassle — All values default to strings, number fields auto-converted per API spec — just type -d amount=100 and it works
• Open Source — MIT license, npm install and go
• Up and Running in 1 Minute — Set credentials, start calling APIs
• Cross-Platform — macOS, Linux, Windows (amd64 & arm64)

Features

Installation

From npm (recommended)

Requires Node.js 22+ for the npm installer. The installed uqpay binary does not require Node.js at runtime.

# Install CLI
npm install -g @uqpay/cli

# Install AI Agent Skills (required for AI Agent usage)
npx skills add uqpay/uqpay-cli -y -g

From source

Requires Go 1.21+.

git clone https://github.com/uqpay/uqpay-cli.git
cd uqpay-cli
make install

# Install AI Agent Skills (required for AI Agent usage)
npx skills add uqpay/uqpay-cli -y -g

Enable tab completion (optional)

uqpay setup-completion
source ~/.zshrc  # or ~/.bashrc

Quick Start

# 1. Configure credentials (one-time)
uqpay config set client-id YOUR_CLIENT_ID
uqpay config set api-key YOUR_API_KEY
uqpay config set env sandbox

# 2. Start using
uqpay banking balance list
uqpay issuing card list
uqpay payment intent list

Virtual Account applications are tracked separately from issued bank details:

# Submit one application. Omit payment_method to evaluate LOCAL and SWIFT.
uqpay banking virtual-account create \
  --idempotency-key va-application-001 \
  -d country=SG -d currency=USD -d nickname=Collections

# List application summaries, then retrieve the complete current application.
uqpay banking virtual-account application list --page-num 1 --page-size 50
uqpay banking virtual-account application retrieve <application-id> -o json

# Existing command: list issued Virtual Account bank details, not applications.
uqpay banking virtual-account list --page-num 1 --page-size 50

For connected accounts, add --on-behalf-of <account-id> to all three flows. Reuse an idempotency key only for the same normalized Create request. Create returns HTTP 200 application data; usable bank details arrive asynchronously.

For all mutating commands, the CLI keeps one x-idempotency-key across safe HTTP retries such as token refresh and rate limiting. If a connection failure, response-read failure, or HTTP 5xx response leaves the remote result uncertain, the CLI does not automatically replay the write. JSON output reports error: "reconcile_required" together with method, path, and idempotency_key; inspect the corresponding resource before deciding whether to submit another logical request.

Successful Gateway Create and Retrieve application data and each List summary include required account_id and direct_id fields. account_id is the UUID of the account that owns the application. direct_id is an ordinary string: "0" for a main account and the main account ID for a connected account. The CLI does not validate or transform either field; -o json preserves them as received.

The CLI does not parse or type webhook deliveries. Use a customer webhook handler or an SDK verifier for that flow.

Or inline without config file:

uqpay --env sandbox --client-id ID --api-key KEY banking balance list

Quick Start (AI Agent)

# Step 1 — Install
npm install -g @uqpay/cli
npx skills add uqpay/uqpay-cli -y -g

# Step 2 — Configure (provide credentials from UQPAY dashboard)
uqpay config set client-id <CLIENT_ID>
uqpay config set api-key <API_KEY>
uqpay config set env sandbox

# Step 3 — Verify
uqpay banking balance list

Agent Skills

Located in skills/, these provide structured guides for AI Agents to operate UQPAY APIs correctly.

Command Structure

uqpay <domain> <resource> <action> [flags]

Domains

uqpay banking balance list           # Banking API
uqpay issuing card list              # Issuing API
uqpay payment intent list            # Payment API

Other Commands

uqpay account list                   # Connected accounts (Connect API)
uqpay config get                     # CLI configuration
uqpay file upload ./doc.pdf          # File upload
uqpay simulate deposit -d ...        # Sandbox simulator
uqpay setup-completion               # Install shell tab-completion

Shortcuts

Top-level aliases for common resources:

uqpay beneficiary list               # = uqpay banking beneficiary list
uqpay card list                      # = uqpay issuing card list
uqpay payout list                    # = uqpay banking payout list
uqpay conversion list                # = uqpay banking conversion list
uqpay cardholder list                # = uqpay issuing cardholder list
uqpay exchange-rate list             # = uqpay banking exchange-rate list

Data Passing

Read operations use flags, write operations use -d key=value:

# Read (GET)
uqpay banking beneficiary list --page-num 2 --page-size 20

# Write (POST) — dot notation for nested objects
uqpay banking beneficiary create \
  -d entity_type=INDIVIDUAL \
  -d first_name=John \
  -d last_name=Doe \
  -d bank_details.swift_code=DBSSSGSG \
  -d bank_details.account_number=1234567890

All values are strings by default. Number fields (like amount in card recharge) are auto-converted — no prefix needed.

Advanced Usage

Output Formats

uqpay banking balance list              # table (default)
uqpay banking balance list -o json      # JSON
uqpay banking balance list -o yaml      # YAML

Debug Mode

uqpay --debug banking balance list      # Print HTTP request/response details

Sub-Account Operations

uqpay --on-behalf-of <account-id> banking balance list

File Encoding

# Pure base64 (issuing identity documents)
-d identity.front_file=@./passport.jpg

# Data URI (connect account documents)
-d "certification[0]=@+./cert.png"

Environment Variables

Contributing

Contributions welcome! Please submit an Issue or Pull Request.

License

MIT

Contract migration notes

See PIN, RFI, deposit simulation and settlement contracts for request changes and response interpretation.