⚡ BursaPay CLI (bursapay-cli)

Official BursaPay Developer CLI for real-time webhook tunneling, signature verification, sandbox mock data generation, IP allowlist testing, and log replaying.

💻 Installation

# Run directly via npx (zero-install)
npx bursapay-cli listen --forward-to http://localhost:8000/webhooks/

# Or install globally
npm install -g bursapay-cli

Requires Node.js >= 16.

🚀 Commands Reference

bursapay login / logout

Save your secret API key locally so you don't need --api-key every time.

bursapay login                                   # interactive prompt
bursapay login --api-key sk_test_xxx...          # pass key directly
bursapay logout                                  # remove saved key

Your API key is stored as plain-text JSON at ~/.bursapay/config.json. Keep this machine secure.

bursapay config

View or clear local CLI configuration stored at ~/.bursapay/config.json.

bursapay config               # display current config
bursapay config --json        # output config as JSON
bursapay config --clear       # delete config file

bursapay listen

Tunnel real-time webhook events from your BursaPay account to your local server via SSE.

bursapay listen --forward-to http://localhost:5000/webhooks/bursapay

# With filters and log file
bursapay listen \
  --forward-to http://localhost:5000/webhooks/ \
  --filter payment.success,refund.completed \
  --since 30m \
  --log-file ./events.jsonl

# Machine-readable NDJSON output (one JSON line per event)
bursapay listen --forward-to http://localhost:5000/webhooks/ --json

Options: | Flag | Description | Default | |---|---|---| | --forward-to <url> | Local URL to forward webhooks to | http://localhost:8000/webhook/test/ | | --filter <events> | Comma-separated event types to forward | All events | | --since <time> | Deliver missed events from 10m, 1h, 2d, or ISO timestamp | None | | --log-file <path> | Append all received events to a .jsonl file | None | | --json | Output each event as a JSON line to stdout (NDJSON) | false |

bursapay trigger

Simulate a webhook delivery. Pings the server pipeline first, then forwards to your local server.

bursapay trigger payment.success --forward-to http://localhost:5000/webhooks/

# Supported event types:
#   payment.success, payment.failed, refund.completed,
#   virtual_account.credited, subscription.charged,
#   transfer.success, dispute.created

# JSON output for scripting
bursapay trigger payment.success --json

bursapay verify

Inspect and verify HMAC SHA-256 webhook signatures locally.

# Interactive prompt
bursapay verify

# Direct flags
bursapay verify \
  --signature "t=1786213041,v1=8da6669d..." \
  --timestamp 1786213041 \
  --body '{"event":"payment.success"}' \
  --secret whsec_test_secret_xxxx

# JSON output for CI/CD pipelines
bursapay verify \
  --signature "v1=8da6..." \
  --body '{"event":"payment.success"}' \
  --secret whsec_xxxx \
  --json

In --json mode all required flags (--signature, --body, --secret) must be passed — interactive prompts are skipped.

bursapay mock

Generate sandbox test data: cards, virtual accounts, USSD codes, and customers.

bursapay mock card        # Visa, Mastercard, Verve, 3DS, error cards
bursapay mock account     # Virtual bank accounts
bursapay mock ussd        # USSD string codes
bursapay mock customer    # Mock customer data
bursapay mock             # All of the above

# Full JSON suite for test scripts
bursapay mock --json

bursapay ip

Show your current public IP and check it against your BursaPay API allowlist rules.

bursapay ip               # human-readable output
bursapay ip --json        # machine-readable JSON (for deploy scripts)

bursapay replay

Replay a saved .jsonl log file back to your local server with staggered delays.

bursapay replay \
  --log-file ./events.jsonl \
  --forward-to http://localhost:5000/webhooks/ \
  --delay 200

# Full JSON summary output
bursapay replay --log-file ./events.jsonl --json

bursapay status

Check server health, API key validity, and environment mode.

bursapay status           # human-readable
bursapay status --json    # machine-readable JSON

bursapay version / help

bursapay version
bursapay help

⚙ Global Flags Reference

| Flag | Type | Description | Default | |---|---|---|---| | --forward-to <url> | string | Local HTTP endpoint to forward webhooks to | http://localhost:8000/webhook/test/ | | --api-key <key> | string | BursaPay secret API key (sk_test_...) | $BURSAPAY_SECRET_KEY or saved config | | --secret <key> | string | Webhook signing secret (whsec_...) | $BURSAPAY_WEBHOOK_SECRET | | --server <url> | string | BursaPay Gateway API server URL | http://127.0.0.1:8000 | | --env <mode> | string | Environment mode: test or live | test | | --filter <list> | string | Comma-separated list of event types to forward | All events | | --since <time> | string | Deliver events since 10m, 1h, 2d, or ISO 8601 timestamp | None | | --log-file <path> | string | File path to append or replay .jsonl event logs | None | | --delay <ms> | number | Delay between replayed events in milliseconds | 100 | | --json | boolean | Output machine-readable JSON / NDJSON | false | | --clear | boolean | Used with bursapay config to delete local config | false |

📄 License

Distributed under the MIT License. Copyright © BursaPay Team.