As a developer, your most powerful tools - from basic bash commands, to version control and deployment tools - sit in your terminal. The Paystack CLI to makes it easier to set up, test, and manage your Paystack integrations right from that very same terminal.
With the CLI, you can:
- Ping your preset webhook URL with sample event data
- Tunnel Paystack events directly to your local server without installing third party software
- Set up sample applications with fully integrated payment channels
- Interact with Paystack API
- Interpret Paystack API Errors
Paystack requires Node.js v16+ to run, To install with npm, run
$ npm install -g @paystack-oss/dev-cli
Check that your installation was successful by running
$ paystack --version
The output should look like
> @paystack-oss/dev-cli/1.0.0-nightly.0 darwin-x64 node-v16.14.0
Now that you’re all setup, to access your Paystack account and execute commands, run
$ paystack login
You’ll be required to enter your credentials and choose the business you want to execute commands on its behalf.
Run $ paystack —help to see a list of all commands you can use on the CLI. By default, all commands are run in test mode. To switch to live, append --domain live to the end of your command.
Read on for more information on what you can do with the CLI.
Whenever actions are carried out on your Paystack account, we trigger events which your application can listen and respond to. Before now, to implement webhook routes like these, you had to:
- Ping your preset webhook URL with sample event data
- Login to your Paystack Dashboard and set the webhook URL
- Make a test payment or transfer
- Review logs
- Repeat
The CLI lets you listen to real-time webhook events on your integration and reduces all these steps are reduced to running a single command —
$ paystack webhook listen localhost:8080/webhook
This command tunnels all your test webhook events to your local server running on port 8080, making it possible for you to run end-to-end tests on your Paystack integration while in development mode.
You can also run health checks on your webhook URL by sending a sample webhook payload to your server. To do this, run:
$ paystack webhook ping --event transfer.success --domain test
Check our documentation for a list of supported events.
We’ve built several sample apps showcasing different use cases and how to integrate Paystack with different programming languages.
You can set up any of the sample apps on your local machine — To do this, run:
$ paystack sample sample_react ~/Work/Desktop
All Paystack public API endpoints are accessible via the Paystack CLI, and you can try out different API calls from the terminal before you start integrating. In this guide, you’ll learn how to
- Initialize a transaction and get a checkout URL.
- Verify a transaction
- Charge a saved card.
First, we’ll call the Initialize Transaction **API** to generate a checkout link. The command to do this is
$ paystack transaction initialize --email [email protected] --amount 10000 \
--callback_url https://paystack.com/docsYour output should look like this
Authorization URL created
{
authorization_url: 'https://checkout.paystack.com/sf69sk0l6d5iuqm',
access_code: 'sf69sk0l6d5iuqm',
reference: 'kpu5vxesc5'
}Great! We’ve created the transaction and can grab the authorization_url from the terminal and open it in a browser to complete the transaction.
Now that’s done, let’s verify the transaction by running
$ paystack transaction verify --reference kpu5vxesc5
Your output should look like this
Verification successful
{
id: 1693453689,
domain: 'test',
status: 'success',
reference: 'kpu5vxesc5',
amount: 10000,
metadata: '',
log: {
...
},
fees: 150,
authorization: {
authorization_code: 'AUTH_5uy1wm1940',
bin: '408408',
last4: '4081',
exp_month: '12',
exp_year: '2030',
channel: 'card',
card_type: 'visa ',
bank: 'TEST BANK',
country_code: 'NG',
brand: 'visa',
reusable: true,
signature: 'SIG_oIPc9Xyv8RuejFCaUi4i',
account_name: null
},
customer: {
...
email: '[email protected]',
customer_code: 'CUS_gnguwml5r732p7y',
...
},
plan: null,
split: {},
order_id: null,
paidAt: '2022-03-18T14:56:20.000Z',
createdAt: '2022-03-18T14:54:51.000Z',
requested_amount: 10000,
...
}So far, so good! Now one more thing, we want to recurringly charge the card that was used for this transaction. To do that, we’ll need the customer’s email and authorization code from the verify transaction response. Grab those from customer.email and authorization.authorization_code in the JSON response respectively.
The command to run will be:
$ paystack transaction charge_authorization --email [email protected] \
--authorization_code AUTH_5uy1wm1940 --amount 1000Output from this command should look like
Charge attempted
{
amount: 10000,
currency: 'NGN',
transaction_date: '2022-03-21T15:25:01.000Z',
status: 'success',
reference: 'h5ijyl88fau8b1l',
domain: 'test',
metadata: '',
gateway_response: 'Approved',
message: null,
channel: 'card',
ip_address: null,
log: null,
fees: 150,
authorization: {
authorization_code: 'AUTH_5uy1wm1940',
bin: '408408',
last4: '4081',
exp_month: '12',
exp_year: '2030',
channel: 'card',
card_type: 'visa ',
bank: 'TEST BANK',
country_code: 'NG',
brand: 'visa',
reusable: true,
signature: 'SIG_oIPc9Xyv8RuejFCaUi4i',
account_name: null
},
customer: {
id: 8072602,
first_name: null,
last_name: null,
email: '[email protected]',
customer_code: 'CUS_gnguwml5r732p7y',
phone: null,
metadata: null,
risk_action: 'deny',
international_format_phone: null
},
plan: null,
id: 1700095471
}... and boom! we’re done.
You can test out all other public endpoints from the CLI. Request body and query parameters should be passed as flags to the command, for example, the Create Customer API requires and email param, and optional phone, first_name and last_name params, we can represent this as a command line argument in the following format:
$ paystack customer create --email [email protected] --first_name Jane --last_name DoeUse our API reference to check the required parameters for any of the endpoints.
$ npm uninstall -g @paystack-oss/dev-cli