@4pay.online/payments-mcp

The MCP server a merchant runs. It gives an AI assistant the payment counter of 4pay.online — take a payment, send a payout, look one up, refund it — and nothing else.

Why this is a separate server

The platform ships two MCP servers, and they are different programs on purpose:

| Server | Who runs it | What it exposes | |---|---|---| | @4pay.online/payments-mcp (this one) | the merchant | payments, payouts, refunds, payment links, saved cards | | @4pay.online/mcp-server | the platform operator | terminals, routing, limits, FX, organizations, partners — the platform itself |

A merchant's agent has no business seeing terminals and routing rules. Given them, an agent working through a declined payment will eventually try to "fix" the live routing — and that is not a prompt problem you can solve with a stern system message. A tool that is not in the list cannot be called, whatever anyone types.

So this package contains no operator code at all. Not disabled, not filtered — absent.

Install

Install from npm:

npm install -g @4pay.online/payments-mcp

The package contains its compiled distribution, so installation needs neither the repository nor development dependencies. In MCP configuration use npx -y @4pay.online/payments-mcp or the installed 4pay-payments-mcp command.

Configure

Two values, both issued by your platform operator at the same time:

// .mcp.json
{
  "mcpServers": {
    "fourpay": {
      "command": "4pay-payments-mcp",
      "env": {
        "FOURPAY_API_URL": "https://sandbox.4pay.online",
        "FOURPAY_API_KEY": "${FOURPAY_API_KEY}",
        "FOURPAY_ORGANIZATION_ID": "${FOURPAY_ORGANIZATION_ID}",
        "FOURPAY_ENV": "test"
      }
    }
  }
}

| Variable | Meaning | |---|---| | FOURPAY_API_KEY | your partner API key | | FOURPAY_ORGANIZATION_ID | the organization it lives in — the key is resolved inside it, and a request carrying only the key is refused before the key is read | | FOURPAY_API_URL | https://sandbox.4pay.online while integrating, https://4pay.online in production | | FOURPAY_ENV | test (default) or prod | | FOURPAY_TIMEOUT | request timeout in ms, default 30000 |

One server, one environment. env is not a tool argument: if a model could choose it, one confident sentence in a prompt would be enough to send a live payment into test, or a test into production. Run a second server if you need both.

Tools

| Tool | What it does | |---|---| | create_payment | takes a payment and returns the link to hand the payer | | create_payout | sends money out to a card, account or wallet | | get_payment | reads one transaction by its platform id | | list_payments | lists transactions, newest first, cursor-paged | | refund_payment | refunds a settled payment, fully or partly | | cancel_payment | cancels one that has not settled | | create_payment_link | a reusable link (and QR) for a fixed or open amount | | list_payment_links | lists them | | list_saved_cards | cards payers saved for repeat purchases | | generate_order_id | a unique id, when you have no reference of your own |

Amounts are always minor units as integers: 2500 is 25.00 in a two-decimal currency. Models are fluent, not exact — decimal arithmetic on money is not something to delegate to one.

Three things this server refuses to let an agent get wrong

A 201 is not an acceptance. The platform creates the transaction and then tells you it was rejected — same response, same status code. Every tool prints what the status means for the money: settled, nothing was charged, still in flight.

An unknown status is not final. Payment rails carry their own intermediate states. A closed list of statuses would mean "unrecognised, therefore paid" the first time an unusual rail appears.

A missing terminal is not the agent's problem to solve. When routing finds nothing, the tool says so and says who fixes it — the operator — instead of leaving terminal not found for the model to interpret as "try a different amount".

Development

npm install
npm run build
npm test

The tests run against a stub transport; nothing touches the network.