PayFast MCP Server

The first MCP server for the PayFast South African payment gateway

A Model Context Protocol (MCP) server that enables AI assistants to interact with the PayFast payment gateway API. This server provides tools for managing transactions, subscriptions, refunds, and credit card operations with built-in safety through Human-in-the-Loop (HITL) confirmation for sensitive operations.

Overview

This MCP server bridges AI assistants like Claude with PayFast, South Africa's leading payment gateway. It enables natural language interaction with PayFast's API while maintaining security and safety through validation and confirmation patterns.

What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to securely interact with external tools and data sources. MCP servers expose functionality as "tools" that AI models can discover and use.

What is PayFast?

PayFast is South Africa's most popular payment gateway, supporting multiple payment methods including credit cards, instant EFT, SnapScan, Zapper, and more. It's trusted by thousands of South African businesses for secure online payments.

Who is this for?

• Developers building payment integrations with AI assistance

• E-commerce businesses managing PayFast transactions through AI workflows

• Financial teams needing AI-powered payment operations and reporting

• Anyone wanting to interact with PayFast using natural language through Claude or other MCP-compatible AI assistants

Features

Comprehensive Tool Suite

The server provides 13 tools organized by category:

Connectivity (1 tool)

• ping: Test API connectivity and validate credentials

Transactions (3 tools)

• transaction.fetch: Retrieve details of a specific transaction

• transaction.history: Get transaction history with date filtering and pagination

• transaction.charge: Process charges on tokenized credit cards

Subscriptions (6 tools)

• subscription.fetch: Retrieve subscription details

• subscription.pause: Temporarily pause a subscription for specified billing cycles

• subscription.unpause: Resume a paused subscription

• subscription.cancel: Permanently cancel a subscription

• subscription.update: Update subscription parameters (amount, cycles, frequency, run date)

• subscription.adhoc: Process one-time ad-hoc charges on subscriptions

Refunds (2 tools)

• refund.create: Create refunds for transactions

• refund.fetch: Retrieve refund details and status

Credit Cards (1 tool)

• creditcard.fetch: Query credit card transaction details

Safety & Security Features

• Human-in-the-Loop (HITL) Confirmation: High-risk operations (charges, refunds, subscription changes) require explicit confirmation before execution

• Input Validation: All tool parameters validated using Zod schemas

• Secure Credential Handling: Credentials never logged or exposed in responses

• Environment Support: Separate sandbox and production environments

• Comprehensive Logging: Structured logging to stderr (never stdout) for debugging

• Error Handling: Graceful error handling with detailed error messages

Technical Highlights

• Built with TypeScript for type safety

• Uses the official @modelcontextprotocol/sdk

• Zod validation for all inputs

• Comprehensive test suite (unit and integration tests)

• Clean architecture with separation of concerns

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ installed (download)

• A PayFast merchant account - Sign up at payfast.co.za

• PayFast sandbox credentials for testing - Get them at sandbox.payfast.co.za

• An MCP-compatible client such as:

  • Claude Desktop

  • Cursor IDE

  • Any other MCP-compatible application

Installation

From Source

From npm (Coming Soon)

Once published to npm, you'll be able to run:

Configuration

1. Get PayFast Credentials

Sandbox (for testing):

1. Create a sandbox account at sandbox.payfast.co.za

2. Navigate to Settings > Integration

3. Copy your Merchant ID and Merchant Key

4. Generate a passphrase in the security settings

Production:

1. Log in to your PayFast account at payfast.co.za

2. Navigate to Settings > Integration

3. Copy your live Merchant ID and Merchant Key

4. Generate a passphrase in the security settings

Warning: Always test with sandbox credentials first. Never use production credentials during development.

2. Create Environment Configuration

Create a .env file in the project root (or configure environment variables in your MCP client):

Important: Add .env to your .gitignore to prevent committing credentials to version control.

Usage with Claude Desktop

Add the PayFast MCP server to your Claude Desktop configuration:

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration

Replace:

• The args path with the absolute path to your built index.js file

• The credential values with your actual PayFast credentials

• Use "sandbox" for testing and "production" for live transactions

Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

Verify Connection

In Claude Desktop, you can verify the server is working:

Claude will use the ping tool to verify connectivity.

Usage with Cursor IDE

Cursor IDE also supports MCP servers. Add the configuration to Cursor's settings:

Configuration File Location

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Configuration

Update the paths and credentials as described above for Claude Desktop.

Available Tools Reference

Human-in-the-Loop (HITL) Confirmation

High-risk operations that involve financial transactions require explicit confirmation to prevent accidental charges or refunds.

How It Works

1. First Call (Request): Call a high-risk tool without the confirmed parameter

2. Confirmation Response: The tool returns details about what will happen and asks for confirmation

3. Second Call (Execution): Call the same tool again with confirmed: true to execute the action

Example Flow

Step 1: Initial Request (without confirmation)

Claude calls:

Step 2: Confirmation Request Response

Step 3: Confirmed Execution

User confirms, and Claude calls again:

Step 4: Success Response

Operations Requiring Confirmation

The following operations require confirmed: true:

• transaction.charge: Creates real payment charges

• subscription.pause: Pauses billing (impacts revenue)

• subscription.unpause: Resumes billing (may charge customer)

• subscription.cancel: Permanently stops subscription (cannot be undone)

• subscription.update: Changes billing parameters (affects future charges)

• subscription.adhoc: Creates immediate charge

• refund.create: Returns money to customer (may be irreversible)

Development

Running in Development Mode

Running Tests

Debugging with MCP Inspector

The MCP Inspector is a debugging tool for MCP servers:

This opens a web interface where you can:

• Test tools interactively

• View request/response payloads

• Debug connection issues

• Inspect server capabilities

Project Structure

Key Architectural Decisions

1. Separation of Concerns: Tools, services, and utilities are cleanly separated

2. Type Safety: Full TypeScript coverage with Zod runtime validation

3. STDIO Transport: Uses standard input/output for MCP communication

4. Structured Logging: All logs go to stderr (stdout reserved for MCP protocol)

5. Error Handling: Comprehensive error catching and standardized error responses

6. Configuration: Environment-based configuration with validation

Security Considerations

Credential Safety

• Never commit credentials: Always use .env files and add them to .gitignore

• No credential logging: The server never logs merchant IDs, keys, or passphrases

• Environment separation: Use sandbox for development, production only when ready

• Secure storage: MCP clients should store credentials securely

Human-in-the-Loop Protection

• Financial operations protected: All charges, refunds, and subscription changes require confirmation

• Clear warnings: Confirmation messages explain exactly what will happen

• Two-step process: Prevents accidental execution through AI misunderstanding

API Security

• Signature verification: All PayFast API calls include MD5 signatures

• HTTPS only: All API communication over secure connections

• Input validation: Zod schemas validate all input parameters

• Error sanitization: Error messages don't expose sensitive data

Best Practices

1. Test in sandbox first: Always test with sandbox credentials before production

2. Monitor logs: Review stderr logs for errors and warnings

3. Limit permissions: Use API credentials with minimal required permissions

4. Regular audits: Periodically review PayFast transaction logs

5. Update dependencies: Keep the MCP SDK and other dependencies up to date

Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

If you encounter a bug or have a feature request:

1. Check if the issue already exists in GitHub Issues

2. Create a new issue with:

   • Clear description of the problem or feature

   • Steps to reproduce (for bugs)

   • Expected vs actual behavior

   • Environment details (OS, Node version, MCP client)

Pull Requests

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass (npm run test:all)

6. Commit your changes (git commit -m 'Add amazing feature')

7. Push to the branch (git push origin feature/amazing-feature)

8. Open a Pull Request

Development Guidelines

• Follow the existing code style (TypeScript, ESLint)

• Add JSDoc comments for public functions

• Include unit tests for new features

• Update documentation as needed

• Keep commits atomic and well-described

Roadmap

Future enhancements planned:

• Add webhook support for payment notifications

• Implement payment link generation

• Add batch operation tools

• Support for additional payment methods (EFT, SnapScan, etc.)

• Enhanced reporting and analytics tools

• Automated reconciliation helpers

• Support for PayFast Checkout API

• CLI tool for direct command-line usage

License

This project is licensed under the MIT License - see below for details:

Support

• Documentation: modelcontextprotocol.io

• PayFast API Docs: developers.payfast.co.za

• Issues: GitHub Issues

• Discussions: GitHub Discussions

Acknowledgments

• Built with the Model Context Protocol SDK

• Powered by PayFast

• Inspired by the MCP community

Made with care for the South African developer community