paystack-mcp

MCP (Model Context Protocol) server for the Paystack API. Enables AI assistants like Claude to interact with Paystack's payment infrastructure for African businesses.

Overview

This MCP server wraps the Paystack REST API, providing 121 tools across 13 categories covering transactions, customers, transfers, subscriptions, refunds, disputes, and more. It uses bearer token authentication with your Paystack secret key.

Features

• Transactions - Initialize, verify, list, fetch, charge authorization, partial debit, timeline, totals, export
• Charges - Create charges (card, bank, USSD, mobile money, EFT), submit PIN/OTP/phone/birthday/address, bulk charges
• Customers - Create, list, fetch, update, validate identity, set risk action, manage authorizations
• Transfers - Create recipients, initiate/finalize/verify transfers, bulk transfers, OTP management
• Plans & Subscriptions - Create/manage plans, subscribe customers, enable/disable subscriptions
• Subaccounts & Splits - Create subaccounts, configure transaction splits
• Payment Requests - Create/manage invoices, send notifications, finalize, archive
• Products & Pages - Create products, payment pages, check slug availability
• Balance & Settlements - Fetch balance, view ledger, list settlements
• Refunds & Disputes - Create refunds, manage disputes, add evidence, resolve
• Dedicated Virtual Accounts - Create/manage dedicated bank accounts for customers
• Terminals - Manage physical and virtual payment terminals
• Bank & Miscellaneous - List banks, resolve accounts, validate accounts, resolve card BIN, list countries

Prerequisites

• Node.js 18+
• A Paystack account with API access
• Your Paystack secret key (starts with sk_test_ for test mode or sk_live_ for live mode)

Get your API keys from the Paystack Dashboard.

Installation

Using npx (recommended)

npx paystack-mcp

Global install

npm install -g paystack-mcp
paystack-mcp

Build from source

git clone https://github.com/samaxbytez/paystack-mcp.git
cd paystack-mcp
npm install
npm run build

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PAYSTACK_SECRET_KEY | Yes | Your Paystack secret key (sk_test_xxx or sk_live_xxx) |

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paystack": {
      "command": "npx",
      "args": ["-y", "paystack-mcp"],
      "env": {
        "PAYSTACK_SECRET_KEY": "sk_test_your_key_here"
      }
    }
  }
}

Claude Code

Add to your .mcp.json file:

{
  "mcpServers": {
    "paystack": {
      "command": "npx",
      "args": ["-y", "paystack-mcp"],
      "env": {
        "PAYSTACK_SECRET_KEY": "sk_test_your_key_here"
      }
    }
  }
}

Architecture

paystack-mcp/
├── src/
│   ├── index.ts                    # Entry point, server setup
│   ├── client.ts                   # Paystack API HTTP client
│   ├── utils.ts                    # Shared utilities
│   ├── client.test.ts              # Client tests
│   ├── utils.test.ts               # Utils tests
│   └── tools/
│       ├── transaction.ts          # Transaction tools (9)
│       ├── charge.ts               # Charge & bulk charge tools (12)
│       ├── customer.ts             # Customer tools (7)
│       ├── transfer.ts             # Transfer & recipient tools (17)
│       ├── plan-subscription.ts    # Plan & subscription tools (12)
│       ├── subaccount-split.ts     # Subaccount & split tools (11)
│       ├── payment-request.ts      # Payment request tools (9)
│       ├── product-page.ts         # Product & page tools (10)
│       ├── balance-settlement.ts   # Balance & settlement tools (4)
│       ├── refund-dispute.ts       # Refund & dispute tools (10)
│       ├── dedicated-account.ts    # Dedicated virtual account tools (6)
│       ├── bank-misc.ts            # Bank, misc & integration tools (9)
│       ├── terminal.ts             # Terminal tools (8)
│       └── tools.test.ts           # Tool handler tests
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── eslint.config.js
├── .prettierrc
├── .env.example
├── smithery.yaml
├── LICENSE
└── README.md

Tools Reference

Transaction Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_initialize_transaction | Initialize a new transaction | POST /transaction/initialize | | paystack_verify_transaction | Verify a transaction by reference | GET /transaction/verify/{reference} | | paystack_list_transactions | List transactions with filters | GET /transaction | | paystack_fetch_transaction | Fetch a transaction by ID | GET /transaction/{id} | | paystack_charge_authorization | Charge a reusable authorization | POST /transaction/charge_authorization | | paystack_transaction_timeline | Fetch transaction timeline | GET /transaction/timeline/{id} | | paystack_transaction_totals | Get transaction totals | GET /transaction/totals | | paystack_export_transactions | Export transactions | GET /transaction/export | | paystack_partial_debit | Partial debit from a customer | POST /transaction/partial_debit |

Charge Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_create_charge | Create a charge (card, bank, USSD, mobile money) | POST /charge | | paystack_submit_pin | Submit PIN for a charge | POST /charge/submit_pin | | paystack_submit_otp | Submit OTP for a charge | POST /charge/submit_otp | | paystack_submit_phone | Submit phone for a charge | POST /charge/submit_phone | | paystack_submit_birthday | Submit birthday for a charge | POST /charge/submit_birthday | | paystack_submit_address | Submit address for verification | POST /charge/submit_address | | paystack_check_pending_charge | Check pending charge status | GET /charge/{reference} | | paystack_initiate_bulk_charge | Initiate bulk charge | POST /bulkcharge | | paystack_list_bulk_charge_batches | List bulk charge batches | GET /bulkcharge | | paystack_fetch_bulk_charge_batch | Fetch a batch | GET /bulkcharge/{code} | | paystack_pause_bulk_charge | Pause a batch | GET /bulkcharge/pause/{code} | | paystack_resume_bulk_charge | Resume a batch | GET /bulkcharge/resume/{code} |

Customer Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_create_customer | Create a customer | POST /customer | | paystack_list_customers | List customers | GET /customer | | paystack_fetch_customer | Fetch customer details | GET /customer/{code} | | paystack_update_customer | Update customer | PUT /customer/{code} | | paystack_set_risk_action | Whitelist/blacklist customer | POST /customer/set_risk_action | | paystack_validate_customer | Validate customer identity | POST /customer/{code}/identification | | paystack_deactivate_authorization | Deactivate an authorization | POST /customer/authorization/deactivate |

Transfer Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_create_transfer_recipient | Create transfer recipient | POST /transferrecipient | | paystack_list_transfer_recipients | List recipients | GET /transferrecipient | | paystack_fetch_transfer_recipient | Fetch recipient | GET /transferrecipient/{code} | | paystack_update_transfer_recipient | Update recipient | PUT /transferrecipient/{code} | | paystack_delete_transfer_recipient | Delete recipient | DELETE /transferrecipient/{code} | | paystack_initiate_transfer | Initiate a transfer | POST /transfer | | paystack_list_transfers | List transfers | GET /transfer | | paystack_fetch_transfer | Fetch transfer details | GET /transfer/{code} | | paystack_verify_transfer | Verify transfer status | GET /transfer/verify/{reference} | | paystack_finalize_transfer | Finalize transfer with OTP | POST /transfer/finalize_transfer | | paystack_initiate_bulk_transfer | Initiate bulk transfer | POST /transfer/bulk | | paystack_export_transfers | Export transfers | GET /transfer/export |

Balance & Settlement Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_fetch_balance | Fetch integration balance | GET /balance | | paystack_balance_ledger | Fetch balance ledger | GET /balance/ledger | | paystack_list_settlements | List settlements | GET /settlement | | paystack_fetch_settlement_transactions | Fetch settlement transactions | GET /settlement/{id}/transactions |

Bank & Miscellaneous Tools

| Tool | Description | API Endpoint | |------|-------------|--------------| | paystack_list_banks | List supported banks | GET /bank | | paystack_resolve_account_number | Resolve account number | GET /bank/resolve | | paystack_validate_bank_account | Validate bank account | POST /bank/validate | | paystack_resolve_card_bin | Resolve card BIN | GET /decision/bin/{bin} | | paystack_list_countries | List supported countries | GET /country | | paystack_list_states | List states for AVS | GET /address_verification/states |

Example Prompts

• "Initialize a transaction for [email protected] for 5000 NGN"
• "List all successful transactions from the last 7 days"
• "Create a transfer recipient for bank account 0123456789 at GTBank"
• "Transfer 10000 NGN to recipient RCP_abc123 from my balance"
• "Check my Paystack balance"
• "Create a monthly subscription plan called 'Pro' for 5000 NGN"
• "Resolve the account number 0123456789 at bank code 058"
• "List all disputes awaiting merchant feedback"
• "Create a refund for transaction TRX_abc123"
• "List all banks in Nigeria that support bank transfers"

Development

# Install dependencies
npm install

# Type check
npm run type-check

# Run tests
npm test

# Watch tests
npm run test:watch

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

Adding New Tools

1. Create a new file in src/tools/ or add to an existing category file
2. Follow the pattern: register function takes (server, client) and calls server.registerTool()
3. Always use logToolCall() first, wrap API calls in try-catch with errorResponse()
4. Import and register in src/index.ts
5. Add tests in src/tools/tools.test.ts

Troubleshooting

"Missing required environment variable: PAYSTACK_SECRET_KEY"

Set the PAYSTACK_SECRET_KEY environment variable with your Paystack secret key.

"Paystack API error (401): unknown - Invalid key"

Your secret key is invalid. Check that you're using the correct key from your Paystack dashboard.

"Paystack API error (400): validation_error"

The request parameters are invalid. Check the tool's parameter descriptions for correct formats.

Amount format

Paystack uses the smallest currency unit. For NGN, amounts are in kobo (100 kobo = 1 NGN). So 5000 NGN = 500000.

Test vs Live mode

Use sk_test_xxx keys for test mode and sk_live_xxx for live mode. Test mode does not process real payments.

Connection errors

Ensure your network can reach https://api.paystack.co. The server requires outbound HTTPS access.

License

MIT