Debugging Paystack with the Paystack CLI

The Paystack CLI is distributed as an npm package. You need Node.js 14 or later installed on your machine.

# Install globally
npm install -g paystack-cli

# Verify installation
paystack --version

# Authenticate with your secret key
paystack auth:login

When you run auth:login, it prompts for your secret key. Use your test secret key during development (starts with sk_test_). The CLI stores your key locally so you do not need to re-enter it for every command.

If you work across multiple Paystack accounts or need to switch between test and live environments, set up profiles:

# Set up named profiles
paystack auth:login --profile test
paystack auth:login --profile live

# Use a specific profile for a command
paystack transaction:list --profile test

On Linux and macOS, the credentials are stored in ~/.config/paystack-cli/. Make sure this directory is excluded from any backup or sync tools that might expose your keys. Never commit these credentials to version control.

The most common debugging task is looking up a specific transaction. Instead of opening the Dashboard and navigating to the transaction page, run one command:

# Look up by reference
paystack transaction:get --reference order_abc123_1721500000

# Look up by transaction ID
paystack transaction:get --id 3456789012

# List recent transactions
paystack transaction:list --perPage 10

# Filter by status
paystack transaction:list --status failed --perPage 20

# Filter by date range
paystack transaction:list --from 2026-07-01 --to 2026-07-20

The output shows the transaction status, amount (in the major currency unit, not kobo), channel, gateway response, customer email, and timestamps. For a failed transaction, the gateway_response field tells you exactly what the bank said.

You can pipe the output to other tools. For example, to quickly count failed transactions today:

# Pipe to jq for JSON processing
paystack transaction:list --status failed --from 2026-07-20 --format json | jq '.data | length'

This is significantly faster than the Dashboard when you need to check multiple transactions in quick succession, like when a customer reports an issue and you want to see their recent payment attempts.

The webhook:listen command is the CLI's most valuable feature for development. It creates a secure tunnel between Paystack's servers and your local machine, forwarding webhook events to your localhost endpoint.

# Forward webhooks to your local server on port 3000
paystack webhook:listen --forward-to http://localhost:3000/api/webhooks/paystack

# Specify a different port
paystack webhook:listen --forward-to http://localhost:8000/webhooks/paystack

When you run this command, the CLI outputs a temporary webhook URL. It also automatically configures your Paystack test account to send webhooks to this URL for the duration of the session. When you stop the CLI (Ctrl+C), it restores your previous webhook URL.

Every incoming webhook is displayed in the terminal with its event type, a summary of the payload, and the HTTP status code your server returned. This gives you real-time visibility into the webhook flow:

# Example output
[2026-07-20 14:32:01] charge.success --> http://localhost:3000/api/webhooks/paystack [200 OK]
[2026-07-20 14:32:15] transfer.success --> http://localhost:3000/api/webhooks/paystack [200 OK]
[2026-07-20 14:33:42] charge.success --> http://localhost:3000/api/webhooks/paystack [500 Internal Server Error]

If your server returns a non-200 status, you see it immediately. No more wondering "did the webhook arrive?" or checking logs in a separate terminal. The feedback loop is instant.

This replaces ngrok, Cloudflare Tunnel, or localtunnel for Paystack webhook testing. One fewer tool to install and configure.

Transfer debugging is where the CLI saves the most time. When a payout fails, you need to check the transfer status, the recipient details, and your available balance. The CLI lets you do all three without leaving the terminal.

# Check a specific transfer
paystack transfer:get --id TRF_abc123def456

# Check transfer by reference
paystack transfer:get --reference payout_july_001

# List recent transfers with their statuses
paystack transfer:list --perPage 10

# Check a recipient's details (bank account info)
paystack recipient:get --id RCP_xyz789

# Check your available balance
paystack balance

For failed transfers, the output includes the failure reason from the bank. Common reasons include invalid account number, account name mismatch, and bank system unavailable. Seeing this data immediately in your terminal lets you diagnose and communicate the issue to the customer without delay.

A practical debugging workflow for a failed payout looks like this:

# Step 1: Check the transfer status and failure reason
paystack transfer:get --reference payout_july_001

# Step 2: Verify the recipient's bank details are correct
paystack recipient:get --id RCP_xyz789

# Step 3: Check if you have sufficient balance for a retry
paystack balance

# Step 4: If details are correct and balance is sufficient, retry
paystack transfer:initiate --amount 50000 --recipient RCP_xyz789 --reason "Retry payout_july_001"

The entire investigation takes under a minute. The same process through the Dashboard involves loading multiple pages and clicking through several screens.

Customer lookup. When a customer contacts support, look them up by email to see all their associated transactions:

paystack customer:get --email customer@example.com

Resolving bank accounts. Before creating a transfer recipient, verify the account number resolves to the expected name:

paystack resolve:account --account_number 0123456789 --bank_code 058

Listing banks. Get the list of supported banks and their codes (useful for building bank selection dropdowns):

paystack bank:list --country nigeria
paystack bank:list --country ghana
paystack bank:list --country kenya

Checking subscription status. Debug subscription billing issues by looking up a specific subscription:

paystack subscription:get --id SUB_abc123
paystack subscription:list --customer customer@example.com

Every command accepts a --format json flag for machine-readable output. This is useful for scripting or piping data to other tools.

Use the CLI when: You are actively debugging a specific issue and want fast lookups. You are developing locally and need webhooks forwarded to localhost. You are in a terminal-centric workflow and context-switching to a browser slows you down.

Use the Dashboard when: You need visual charts and analytics (transaction volume over time, success rate trends). You need to update business settings (webhook URLs, bank account details, team member access). You are a non-technical team member reviewing payments.

Use direct API calls when: You are building automated systems (reconciliation scripts, monitoring alerts, admin tools). You need to integrate payment data into your application. You are running batch operations that require loops and conditional logic.

In practice, most developers use all three. The CLI for quick debugging during development, the Dashboard for settings and visual overviews, and direct API calls for production automation. The CLI does not replace the other tools. It fills the gap between "I need to check something quickly" and "I need to build a script for this."

The CLI stores your secret key on disk. This is convenient but creates a security surface you need to manage.

Never use live keys on shared machines. If you are working on a shared development server or a CI machine, do not authenticate the CLI with live keys. Use test keys only, or pass the key per-command using an environment variable:

# Pass key via environment variable instead of storing it
PAYSTACK_SECRET_KEY=sk_test_xxx paystack transaction:get --reference order_123

Rotate keys if a machine is compromised. If a development machine with stored CLI credentials is lost or compromised, immediately rotate your Paystack secret key from the Dashboard. Then re-authenticate the CLI on your new or cleaned machine.

Use test mode by default. Make your test profile the default. Only switch to live mode when you specifically need to inspect live data. This prevents accidental operations against real money.

Be careful with transfer commands. The CLI can initiate transfers. A typo in the amount or recipient when using the live profile sends real money to a real bank account. Double-check the profile before running any write operation.

After installing and authenticating, run through this checklist to confirm everything is working:

1. Version check: Run paystack --version. If it returns a version number, the installation succeeded.
2. Authentication check: Run paystack transaction:list --perPage 1. If it returns data (even an empty list), your key is valid and stored correctly.
3. Webhook tunnel check: Start paystack webhook:listen --forward-to http://localhost:3000/test, then initiate a test transaction from another terminal or the Dashboard. Confirm the webhook event appears in the CLI output.
4. JSON output check: Run paystack transaction:list --perPage 1 --format json and confirm the output is valid JSON. This verifies that scripting workflows will work.

If any step fails, the most common causes are: Node.js version too old (need 14+), incorrect secret key, or network firewall blocking the tunnel connection. Fix the root cause before relying on the CLI for debugging.