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

$3

``bash
npm install -g @toneflix/paystack-cli
`

$3

`bash
pnpm add -g @toneflix/paystack-cli
`

$3

`bash
yarn global add @toneflix/paystack-cli
`

After installation, verify the CLI is installed correctly:

`bash
paystack-cli --version
`

Quick Start

1. Initialize the CLI

`bash
paystack-cli init
`

2. Login to your Paystack account

`bash
paystack-cli login
`

3. Start using Paystack API commands

`bash
# 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

$3

The CLI uses your Paystack account credentials for authentication:

`bash
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).

$3

To logout and clear your session:

`bash
paystack-cli logout
`

$3

- 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

$3

#### init

Initialize the Paystack CLI application and setup the local database.

`bash
paystack-cli init
`

#### login

Authenticate with your Paystack account.

`bash
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.

`bash
paystack-cli logout
`

#### config

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

`bash
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

$3

#### webhook listen

Start a local webhook listener using ngrok tunneling.

`bash
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:

`bash


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.

`bash
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:

`bash


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
`

$3

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

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

API Resources

The CLI provides access to the following Paystack resources:

$3

Manage payment transactions.

`bash


Initialize a transaction

paystack-cli transaction:initialize --email=customer@email.com --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=user@example.com --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=user@example.com --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
`

$3

Manage customer information.

`bash


Create customer

paystack-cli customer:create --email=user@example.com --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
`

$3

Create and manage subscription plans.

`bash


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
`

$3

Manage customer subscriptions.

`bash


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
`

$3

Handle money transfers.

`bash


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
`

$3

Manage transfer recipients.

`bash


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
`

$3

Manage split payment subaccounts.

`bash


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
`

$3

Create and manage payment pages.

`bash


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
`

$3

Manage payment requests and invoices.

`bash


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
`

$3

Handle card charges and tokenization.

`bash


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=user@example.com --amount=10000
`

$3

Manage bulk charge operations.

`bash


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
`

$3

Process refunds for transactions.

`bash


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
`

$3

Get bank information.

`bash


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
`

$3

View settlement information.

`bash


Fetch settlements


paystack-cli settlement:fetch --from=2024-01-01 --to=2024-12-31 --subaccount=ACCT_xxx
`

$3

Manage integration settings.

`bash


Fetch payment session timeout

paystack-cli integration:fetch

Update payment session timeout

paystack-cli integration:update --timeout=600
`

$3

Check account balance.

`bash


Check balance

paystack-cli balance:check

View balance ledger

paystack-cli balance:balance
`

$3

Verify customer information.

`bash


Resolve verification


paystack-cli verifications:resolve --verification_type=truecaller --phone=08012345678
`

$3

Card information lookup.

`bash


Resolve card BIN


paystack-cli decision:resolve --bin=123456
`

$3

Manage invoices.

`bash


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:

`bash
paystack-cli config
`

$3

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

$3

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

$3

1. Configure ngrok token (first time only):

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

2. Start webhook listener:
`bash
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

$3

Send test webhook events:

`bash


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
`

$3

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

Examples

$3

`bash


1. Initialize transaction

paystack-cli transaction:initialize \
--email=customer@example.com \
--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
`

$3

`bash


1. Create a plan

paystack-cli plan:create \
--name="Monthly Premium" \
--amount=50000 \
--interval=monthly

2. Create customer

paystack-cli customer:create \
--email=subscriber@example.com \
--first_name=John \
--last_name=Doe

3. Create subscription

paystack-cli subscription:create \
--customer=CUS_xxx \
--plan=PLN_xxx
`

$3

`bash


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

$3

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

$3

`bash


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
`

$3

`md
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
`

$3

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

Troubleshooting

$3

1. "You're not signed in" error

`bash


Solution: Login first


paystack-cli login
`

2. "Session expired" error

`bash


Solution: Login again


paystack-cli logout
paystack-cli login
`

3. Webhook listener not working

`bash


Solution: Check ngrok token is configured

paystack-cli config

Select "Ngrok Auth Token" and enter your token from ngrok.com

`

4. Command not found

`bash


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

`bash


Solution: Use sudo for global installation


sudo npm install -g @toneflix/paystack-cli
`

$3

Enable debug mode to see detailed error information:

`bash
paystack-cli config


Select "Debug Mode" and choose "true"


`

$3

For any command, you can get help by running:

`bash
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

$3

- 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: support@toneflix.net
- 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