The PayFast MCP Server enables AI assistants to securely manage payment transactions, subscriptions, and refunds through the PayFast payment gateway.
Connectivity
ping— Test API connectivity and verify credentials
Transaction Management
transaction.fetch— Retrieve details of a specific transaction by payment IDtransaction.history— Query transaction history with optional date range filtering and paginationtransaction.charge— Process a charge on a tokenized card
Subscription Management
subscription.fetch— Get subscription details by tokensubscription.pause— Pause a subscription for a specified number of billing cyclessubscription.unpause— Resume a paused subscriptionsubscription.cancel— Permanently cancel a subscriptionsubscription.update— Update subscription parameters like amount, cycles, frequency, or run datesubscription.adhoc— Process a one-time ad-hoc charge on an existing subscription
Refund Processing
refund.query— Check refund availability and amounts before creating a refundrefund.create— Process a full or partial refund for a transactionrefund.fetch— Retrieve refund transaction history and available balance
Credit Card Queries
creditcard.fetch— Query credit card transaction details for a specific payment
⚠️ High-risk operations (canceling/pausing/updating subscriptions, creating refunds, ad-hoc charges) require explicit confirmation before execution.
The server supports sandbox mode for safe testing and uses environment variables for secure credential management.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PayFast MCP ServerShow my transaction history from the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
payfast-mcp
A Model Context Protocol (MCP) server for PayFast, South Africa's leading payment gateway. Enables AI assistants like Claude to securely interact with your PayFast merchant account.
Features
Transaction management — fetch transaction details, query history, process tokenized charges
Subscription management — fetch, pause, unpause, cancel, update, and ad-hoc charge subscriptions
Refund processing — create refunds (full or partial) and query refund status
Credit card queries — look up credit card transaction details
Sandbox support — defaults to sandbox mode for safe testing
Secure by design — credentials via environment variables only, sensitive data never logged
Available Tools
Tool | Description | Risk |
| Test API connectivity | Low |
| Get transaction by ID | Low |
| Query transaction history | Low |
| Charge a stored token | Medium |
| Get subscription details | Low |
| Pause a subscription | High |
| Resume a subscription | Medium |
| Cancel a subscription | High |
| Update subscription terms | High |
| Ad-hoc subscription charge | High |
| Process a refund | High |
| Get refund details | Low |
| Query card transaction | Low |
High-risk operations require human approval before execution.
Quick Start
Prerequisites
Node.js 18+
A PayFast merchant account (sandbox or production)
Installation
npm install -g payfast-mcpOr run directly with npx:
npx payfast-mcpConfiguration
Set the following environment variables:
Variable | Required | Description |
| Yes | Your PayFast Merchant ID |
| Yes | Your PayFast Merchant Key |
| Yes | Your PayFast API Passphrase |
| No |
|
You can also create a .env file in your working directory.
Claude Desktop
Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"payfast": {
"command": "npx",
"args": ["-y", "payfast-mcp"],
"env": {
"PAYFAST_MERCHANT_ID": "your-merchant-id",
"PAYFAST_MERCHANT_KEY": "your-merchant-key",
"PAYFAST_PASSPHRASE": "your-passphrase",
"PAYFAST_ENVIRONMENT": "sandbox"
}
}
}
}Claude Code
Add to your Claude Code settings:
claude mcp add payfast \
-e PAYFAST_MERCHANT_ID=your-merchant-id \
-e PAYFAST_MERCHANT_KEY=your-merchant-key \
-e PAYFAST_PASSPHRASE=your-passphrase \
-e PAYFAST_ENVIRONMENT=sandbox \
-- npx -y payfast-mcpCursor
Add to your Cursor MCP config (.cursor/mcp.json for project-level, or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"payfast": {
"command": "npx",
"args": ["-y", "payfast-mcp"],
"env": {
"PAYFAST_MERCHANT_ID": "your-merchant-id",
"PAYFAST_MERCHANT_KEY": "your-merchant-key",
"PAYFAST_PASSPHRASE": "your-passphrase",
"PAYFAST_ENVIRONMENT": "sandbox"
}
}
}
}Codex
Add via the Codex CLI:
codex mcp add payfast \
--env PAYFAST_MERCHANT_ID=your-merchant-id \
--env PAYFAST_MERCHANT_KEY=your-merchant-key \
--env PAYFAST_PASSPHRASE=your-passphrase \
--env PAYFAST_ENVIRONMENT=sandbox \
-- npx -y payfast-mcpOr add directly to ~/.codex/config.toml:
[mcp_servers.payfast]
command = "npx"
args = ["-y", "payfast-mcp"]
[mcp_servers.payfast.env]
PAYFAST_MERCHANT_ID = "your-merchant-id"
PAYFAST_MERCHANT_KEY = "your-merchant-key"
PAYFAST_PASSPHRASE = "your-passphrase"
PAYFAST_ENVIRONMENT = "sandbox"Development
# Clone the repo
git clone https://github.com/jpbester/payfast-mcp.git
cd payfast-mcp
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Run with MCP Inspector
npm run inspectLicense
MIT