Paystack CLI

The Paystack CLI helps you build, test, and manage your Paystack integration right from the terminal. Interact with the Paystack API, test webhooks locally, and manage your integration settings without leaving your command line.

View Documentation

Table of Contents

• Features
• Installation
• Quick Start
• Authentication
• Commands
  • Core Commands
  • API Commands
  • Webhook Commands
• Configuration
• Webhook Testing
• API Resources
• Examples
• Development
• Troubleshooting
• Contributing
• License

Features

Complete Paystack API Access - Access all Paystack API endpoints directly from your terminal

Secure Authentication - Login once and securely manage your Paystack integration

Local Webhook Testing - Test webhooks locally using ngrok integration

Configuration Management - Configure API settings, timeouts, and debug modes

Beautiful Output - Formatted JSON responses with colored output for better readability

Developer Friendly - Built with TypeScript for type safety and better DX

Installation

NPM

npm install -g @toneflix/paystack-cli

PNPM

pnpm add -g @toneflix/paystack-cli

Yarn

yarn global add @toneflix/paystack-cli

After installation, verify the CLI is installed correctly:

paystack-cli --version

Quick Start

1. Initialize the CLI

   paystack-cli init

2. Login to your Paystack account

   paystack-cli login

3. Start using Paystack API commands

   # List all transactions
   paystack-cli transaction:list
   
   # Fetch customer details
   paystack-cli customer:fetch --id=CUS_xxxxx
   
   # Create a new plan
   paystack-cli plan:create --name="Monthly Plan" --amount=5000 --interval=monthly

Authentication

Login

The CLI uses your Paystack account credentials for authentication:

paystack-cli login

You'll be prompted for:

• Email: Your Paystack account email
• Password: Your Paystack account password
• Remember: Option to save your email for future logins

After successful login, you'll select which integration to use (if you have multiple).

Logout

To logout and clear your session:

paystack-cli logout

Session Management

• Sessions automatically expire after the token timeout period
• You'll be prompted to login again when your session expires
• Login credentials are securely stored in a local SQLite database

Commands

Core Commands

init

Initialize the Paystack CLI application and setup the local database.

paystack-cli init

login

Authenticate with your Paystack account.

paystack-cli login

Options:

• Interactive prompts for email and password
• Option to remember email for faster login
• Automatic integration selection for accounts with multiple integrations

logout

Sign out and clear your authentication session.

paystack-cli logout

config

Configure CLI settings like API base URL, timeout duration, and debug mode.

paystack-cli config

Available configurations:

• API Base URL: Default Paystack API endpoint
• Timeout Duration: Request timeout in milliseconds
• Debug Mode: Enable/disable detailed error logging
• Ngrok Auth Token: Set ngrok authentication token for webhook testing

Webhook Commands

webhook listen

Start a local webhook listener using ngrok tunneling.

paystack-cli webhook listen [local_route]

Arguments:

• local_route (optional): Your local webhook endpoint (e.g., http://localhost:8080/webhook)

Options:

• --domain, -D: Specify domain to ping (test/live) [default: test]
• --forward, -F: Forward webhook to a specific URL

Example:

# Listen on default route
paystack-cli webhook listen

# Listen on specific route
paystack-cli webhook listen http://localhost:3000/api/webhook

# Listen with custom domain
paystack-cli webhook listen http://localhost:8080 --domain=live

webhook ping

Send a test webhook event to your configured webhook URL.

paystack-cli webhook ping

Options:

• --event, -E: Event type to simulate (charge.success, transfer.success, etc.)
• --domain, -D: Domain to ping (test/live) [default: test]
• --forward, -F: Forward to specific URL instead of saved webhook

Example:

# Test charge success event
paystack-cli webhook ping --event=charge.success

# Test transfer failed on live
paystack-cli webhook ping --event=transfer.failed --domain=live

API Commands

All Paystack API endpoints are available as commands. The general format is:

paystack-cli [resource]:[action] [options]

API Resources

The CLI provides access to the following Paystack resources:

Transactions

Manage payment transactions.

# Initialize a transaction
paystack-cli transaction:initialize [email protected] --amount=10000

# List all transactions
paystack-cli transaction:list --perPage=50 --page=1

# Verify a transaction
paystack-cli transaction:verify --reference=xyz123

# View transaction details
paystack-cli transaction:view --id=123456

# Charge authorization
paystack-cli transaction:charge --authorization_code=AUTH_xxx [email protected] --amount=5000

# Export transactions
paystack-cli transaction:export --from=2024-01-01 --to=2024-12-31

# Check authorization
paystack-cli transaction:check --authorization_code=AUTH_xxx [email protected] --amount=5000

# Get transaction totals
paystack-cli transaction:transaction --from=2024-01-01 --to=2024-12-31

# Fetch transaction
paystack-cli transaction:fetch --id=12345

Customers

Manage customer information.

# Create customer
paystack-cli customer:create [email protected] --first_name=John --last_name=Doe

# Update customer
paystack-cli customer:update --code=CUS_xxx --first_name=Jane

# Fetch customer
paystack-cli customer:fetch --code=CUS_xxx

# List customers
paystack-cli customer:list --perPage=20 --page=1

# Set risk action
paystack-cli customer:set_risk_action --customer=CUS_xxx --risk_action=allow

# Deactivate authorization
paystack-cli customer:deactivate --authorization_code=AUTH_xxx

Plans

Create and manage subscription plans.

# Create plan
paystack-cli plan:create --name="Premium Plan" --amount=50000 --interval=monthly

# Update plan
paystack-cli plan:update --code=PLN_xxx --amount=60000

# List plans
paystack-cli plan:list --interval=monthly --amount=50000

# Fetch plan
paystack-cli plan:fetch --code=PLN_xxx

Subscriptions

Manage customer subscriptions.

# Create subscription
paystack-cli subscription:create --customer=CUS_xxx --plan=PLN_xxx

# Disable subscription
paystack-cli subscription:disable --code=SUB_xxx --token=email_token

# Enable subscription
paystack-cli subscription:enable --code=SUB_xxx --token=email_token

# Fetch subscription
paystack-cli subscription:fetch --code=SUB_xxx

# List subscriptions
paystack-cli subscription:list --customer=CUS_xxx --plan=PLN_xxx

Transfers

Handle money transfers.

# Initiate transfer
paystack-cli transfer:initiate --source=balance --amount=10000 --recipient=RCP_xxx

# List transfers
paystack-cli transfer:list --perPage=50

# Verify transfer
paystack-cli transfer:verify --reference=TRF_xxx

# Finalize transfer
paystack-cli transfer:finalize --transfer_code=TRF_xxx --otp=123456

# Bulk transfer
paystack-cli transfer:initiate --transfers='[{"amount":10000,"recipient":"RCP_xxx"}]'

# Disable OTP
paystack-cli transfer:disable

# Enable OTP
paystack-cli transfer:enable

# Resend OTP
paystack-cli transfer:resend --transfer_code=TRF_xxx --reason=resend_otp

# Fetch transfer
paystack-cli transfer:fetch --code=TRF_xxx

Transfer Recipients

Manage transfer recipients.

# Create recipient
paystack-cli transferrecipient:create --type=nuban --name="John Doe" --account_number=0123456789 --bank_code=033

# Update recipient
paystack-cli transferrecipient:update --code=RCP_xxx --name="Jane Doe"

# Delete recipient
paystack-cli transferrecipient:delete --code=RCP_xxx

# List recipients
paystack-cli transferrecipient:list --perPage=50

Subaccounts

Manage split payment subaccounts.

# Create subaccount
paystack-cli subaccount:create --business_name="Vendor Co" --settlement_bank=033 --account_number=0123456789 --percentage_charge=10

# Update subaccount
paystack-cli subaccount:update --code=ACCT_xxx --business_name="New Name"

# Fetch subaccount
paystack-cli subaccount:fetch --code=ACCT_xxx

# List subaccounts
paystack-cli subaccount:list

Payment Pages

Create and manage payment pages.

# Create page
paystack-cli page:create --name="Donation Page" --amount=5000

# Update page
paystack-cli page:update --code=PAGE_xxx --name="New Page Name"

# Fetch page
paystack-cli page:fetch --code=PAGE_xxx

# List pages
paystack-cli page:list

# Check slug availability
paystack-cli page:check --slug=my-page

Payment Requests (Invoices)

Manage payment requests and invoices.

# Create payment request
paystack-cli paymentrequest:create --customer=CUS_xxx --amount=10000 --description="Invoice for services"

# List payment requests
paystack-cli paymentrequest:list

# Fetch payment request
paystack-cli paymentrequest:fetch --code=PRQ_xxx

# Update payment request
paystack-cli paymentrequest:update --code=PRQ_xxx --amount=15000

# Verify payment request
paystack-cli paymentrequest:verify --code=PRQ_xxx

# Send notification
paystack-cli paymentrequest:send --code=PRQ_xxx

# Finalize payment request
paystack-cli paymentrequest:finalize --code=PRQ_xxx

# View invoice
paystack-cli paymentrequest:invoice --code=PRQ_xxx

Charges

Handle card charges and tokenization.

# Submit OTP
paystack-cli charge:submit --otp=123456 --reference=ref_xxx

# Submit PIN
paystack-cli charge:submit --pin=1234 --reference=ref_xxx

# Submit birthday
paystack-cli charge:submit --birthday=1990-01-01 --reference=ref_xxx

# Submit phone
paystack-cli charge:submit --phone=08012345678 --reference=ref_xxx

# Tokenize charge
paystack-cli charge:tokenize --card=xxx

# Check pending charge
paystack-cli charge:check --reference=ref_xxx

# Charge
paystack-cli charge:charge [email protected] --amount=10000

Bulk Charges

Manage bulk charge operations.

# Initiate bulk charge
paystack-cli bulkcharge:initiate --charges='[{"authorization":"AUTH_xxx","amount":10000}]'

# Fetch bulk charge
paystack-cli bulkcharge:fetch --code=BCH_xxx

# Fetch bulk charge charges
paystack-cli bulkcharge:fetch --code=BCH_xxx

# Pause bulk charge
paystack-cli bulkcharge:pause --code=BCH_xxx

# Resume bulk charge
paystack-cli bulkcharge:resume --code=BCH_xxx

Refunds

Process refunds for transactions.

# Create refund
paystack-cli refund:create --transaction=TRX_xxx --amount=5000

# List refunds
paystack-cli refund:list --transaction=TRX_xxx

# Fetch refund
paystack-cli refund:fetch --code=RFD_xxx

Banks

Get bank information.

# List banks
paystack-cli bank:list --country=nigeria --use_cursor=true

# Resolve account number
paystack-cli bank:resolve --account_number=0123456789 --bank_code=033

# Resolve BVN
paystack-cli bank:resolve --bvn=12345678901

# Match BVN with account
paystack-cli bank:match --account_number=0123456789 --bank_code=033 --bvn=12345678901

Settlements

View settlement information.

# Fetch settlements
paystack-cli settlement:fetch --from=2024-01-01 --to=2024-12-31 --subaccount=ACCT_xxx

Integration

Manage integration settings.

# Fetch payment session timeout
paystack-cli integration:fetch

# Update payment session timeout
paystack-cli integration:update --timeout=600

Balance

Check account balance.

# Check balance
paystack-cli balance:check

# View balance ledger
paystack-cli balance:balance

Verifications

Verify customer information.

# Resolve verification
paystack-cli verifications:resolve --verification_type=truecaller --phone=08012345678

Decision

Card information lookup.

# Resolve card BIN
paystack-cli decision:resolve --bin=123456

Invoices

Manage invoices.

# Archive invoice
paystack-cli invoice:archive --code=INV_xxx

Configuration

The CLI stores configuration in a local database. Use the config command to modify settings:

paystack-cli config

Available Settings

1. API Base URL

   • Default: https://api.paystack.co
   • Change this to use a different Paystack API endpoint

2. Timeout Duration

   • Default: 3000ms
   • HTTP request timeout in milliseconds

3. Debug Mode

   • Default: false
   • Enable to see detailed error messages and stack traces

4. Ngrok Auth Token

   • Required for webhook testing
   • Get your token from ngrok.com

Environment Variables

You can also set configuration via environment variables:

• NGROK_AUTH_TOKEN: Your ngrok authentication token
• NGROK_DOMAIN: Custom ngrok domain (if you have a paid plan)

Webhook Testing

Setting Up

1. Configure ngrok token (first time only):

   paystack-cli config
   # Select "Ngrok Auth Token" and enter your token

2. Start webhook listener:

   paystack-cli webhook listen http://localhost:3000/webhook

The CLI will:

• Create an ngrok tunnel to your local server
• Update your Paystack webhook URL automatically
• Forward all webhook events to your local endpoint

Testing Webhooks

Send test webhook events:

# Test successful charge
paystack-cli webhook ping --event=charge.success

# Test transfer events
paystack-cli webhook ping --event=transfer.success
paystack-cli webhook ping --event=transfer.failed

# Test subscription event
paystack-cli webhook ping --event=subscription.create

Available Events

• charge.success - Successful payment
• transfer.success - Successful transfer
• transfer.failed - Failed transfer
• subscription.create - New subscription created

Examples

Complete Transaction Flow

# 1. Initialize transaction
paystack-cli transaction:initialize \
  [email protected] \
  --amount=50000 \
  --reference=ORDER_12345

# 2. After customer pays, verify transaction
paystack-cli transaction:verify --reference=ORDER_12345

# 3. View transaction details
paystack-cli transaction:view --id=123456

Subscription Management

# 1. Create a plan
paystack-cli plan:create \
  --name="Monthly Premium" \
  --amount=50000 \
  --interval=monthly

# 2. Create customer
paystack-cli customer:create \
  [email protected] \
  --first_name=John \
  --last_name=Doe

# 3. Create subscription
paystack-cli subscription:create \
  --customer=CUS_xxx \
  --plan=PLN_xxx

Transfer Workflow

# 1. Create transfer recipient
paystack-cli transferrecipient:create \
  --type=nuban \
  --name="Jane Doe" \
  --account_number=0123456789 \
  --bank_code=033

# 2. Initiate transfer
paystack-cli transfer:initiate \
  --source=balance \
  --amount=50000 \
  --recipient=RCP_xxx \
  --reason="Payment for services"

# 3. If OTP is required, finalize with OTP
paystack-cli transfer:finalize \
  --transfer_code=TRF_xxx \
  --otp=123456

Development

Prerequisites

• Node.js >= 18
• PNPM (recommended) or NPM

Setup

# Clone repository
git clone https://github.com/toneflix/paystack-cli.git
cd paystack-cli

# Install dependencies
pnpm install

# Run in development mode
pnpm runner [command]

# Build
pnpm build

# Run tests
pnpm test

Project Structure

paystack-cli/
├── src/
│ ├── Commands/ # CLI command classes
│ │ ├── Commands.ts # Dynamic API command generator
│ │ ├── InitCommand.ts
│ │ ├── LoginCommand.ts
│ │ ├── LogoutCommand.ts
│ │ ├── ConfigCommand.ts
│ │ └── WebhookCommand.ts
│ ├── Contracts/ # TypeScript interfaces
│ ├── paystack/ # Paystack API definitions
│ │ ├── apis.ts # All API endpoint schemas
│ │ └── webhooks.ts # Webhook event handlers
│ ├── utils/ # Utility functions
│ ├── cli.ts # Application entry point
│ ├── db.ts # Local database management
│ ├── helpers.ts # Helper functions
│ ├── hooks.ts # Custom hooks
│ └── Paystack.ts # Paystack API client
├── bin/ # Executable files
├── tests/ # Test files
└── package.json

Technology Stack

• Framework: H3ravel Musket - CLI framework
• Language: TypeScript
• Database: SQLite (via better-sqlite3)
• HTTP Client: Axios
• Tunneling: ngrok
• Build Tool: tsdown

Troubleshooting

Common Issues

1. "You're not signed in" error

# Solution: Login first
paystack-cli login

2. "Session expired" error

# Solution: Login again
paystack-cli logout
paystack-cli login

3. Webhook listener not working

# Solution: Check ngrok token is configured
paystack-cli config
# Select "Ngrok Auth Token" and enter your token from ngrok.com

4. Command not found

# Solution: Ensure CLI is installed globally
npm install -g @toneflix/paystack-cli
# Or reinstall
npm uninstall -g @toneflix/paystack-cli
npm install -g @toneflix/paystack-cli

5. Permission errors on macOS/Linux

# Solution: Use sudo for global installation
sudo npm install -g @toneflix/paystack-cli

Debug Mode

Enable debug mode to see detailed error information:

paystack-cli config
# Select "Debug Mode" and choose "true"

Getting Help

For any command, you can get help by running:

paystack-cli [command] --help

Or visit the Paystack API Documentation for API-specific information.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write TypeScript with proper type definitions
• Follow existing code style
• Add tests for new features
• Update documentation for API changes
• Ensure all tests pass before submitting PR

License

This project is licensed under the ISC License - see the LICENSE file for details.

Support

• Email: [email protected]
• Issues: GitHub Issues
• Docs: Paystack Documentation
• Community: Paystack Slack

Acknowledgments

• Built with H3ravel Musket
• Powered by Paystack
• Tunneling by ngrok
• Dev Server from H3

© Copyright 2026 - ToneFlix Technologies Limited