# CLI

The ZevPay CLI lets you manage payments, test webhooks, and verify transactions from your terminal.

## Installation

```bash
npm install -g @zevpay/cli
```

Or use without installing:

```bash
npx @zevpay/cli <command>
```

Requires Node.js 18+.

## Authentication

```bash
zevpay login sk_test_your_secret_key
```

The key is stored locally. You can also use the `ZEVPAY_SECRET_KEY` environment variable.

```bash
export ZEVPAY_SECRET_KEY=sk_test_your_secret_key
```

## Commands

### verify

Verify a checkout session and display its status.

```bash
zevpay verify ses_abc123
```

```
  Checkout Session

  Session ID       ses_abc123
  Reference        REF-001
  Status           completed
  Amount           ₦5,000.00
  Currency         NGN
  Email            customer@example.com
  Payment Method   bank_transfer
  Paid At          3/11/2026, 2:30:00 PM
```

Add `--json` for raw JSON output:

```bash
zevpay verify ses_abc123 --json
```

### banks

List supported banks.

```bash
zevpay banks                  # List all
zevpay banks --search access  # Filter by name
zevpay banks --json           # Raw JSON
```

### resolve

Resolve a bank account (name enquiry).

```bash
zevpay resolve 0123456789 044
```

```
  Account Details

  Account Name     John Doe
  Account Number   0123456789
  Bank Code        044
```

### balance

Show your wallet balance.

```bash
zevpay balance
```

```
  Wallet Balance (test mode)

  ₦50,000.00 NGN
```

## Webhook testing

The CLI provides two commands for testing webhooks locally — similar to the Stripe CLI workflow.

### listen

Start a local HTTP server that receives webhook events. Configure this URL as your webhook endpoint in the [ZevPay Dashboard](https://dashboard.zevpaycheckout.com).

First, save your webhook secret:

```bash
zevpay webhook-secret whsec_your_secret
```

Then start listening:

```bash
zevpay listen                              # Listen on port 4242
zevpay listen -p 8080                      # Custom port
zevpay listen -f http://localhost:3000/api/webhooks  # Forward to your app
```

Output:

```
  ZevPay Webhook Listener

  Endpoint  http://localhost:4242/
  Forward   http://localhost:3000/api/webhooks
  Status    Ready — waiting for events

  ->  3/11/2026, 2:30:00 PM  charge.success  [sig verified]
      ref=TEST-A1B2C3D4  amount=500000  status=completed
      forwarded -> 200 OK
```

The listener verifies the `x-zevpay-signature` header and optionally forwards events to your application.

### trigger

Send a test webhook event with a valid signature to your listener or application.

```bash
zevpay trigger charge.success                              # To localhost:4242
zevpay trigger transfer.success -u http://localhost:3000/webhooks
```

Available event types:

| Event | Description |
|-------|-------------|
| `charge.success` | Successful payment |
| `transfer.success` | Successful transfer |
| `transfer.failed` | Failed transfer |
| `transfer.reversed` | Reversed transfer |
| `invoice.created` | Invoice created |
| `invoice.paid` | Invoice paid |

### Typical webhook testing workflow

```bash
# Terminal 1: Start your app
npm run dev

# Terminal 2: Start the webhook listener, forwarding to your app
zevpay listen -f http://localhost:3000/api/webhooks

# Terminal 3: Trigger test events
zevpay trigger charge.success
zevpay trigger transfer.failed
```

## Environment variables

| Variable | Description |
|----------|-------------|
| `ZEVPAY_SECRET_KEY` | API secret key (alternative to `zevpay login`) |
| `ZEVPAY_WEBHOOK_SECRET` | Webhook signing secret (alternative to `zevpay webhook-secret`) |

## Resources

- [API Reference](/api/overview) — Full endpoint documentation
- [Node.js SDK](/sdks/nodejs) — Underlying server-side SDK
- [Webhook Events](/webhooks/events) — All event types
- [npm](https://www.npmjs.com/package/@zevpay/cli) — Package registry