centrapay-mcp

An MCP server for the Centrapay payments API — bring NZ payment-flow testing directly into Claude Code, Claude Desktop, and any MCP-compatible AI tool.

Ask Claude things like:

• "Create a $25 NZD payment request under config X"
• "What's the status of payment request abc123?"
• "List the merchants on this account"

---

Centrapay's model

Centrapay is structured Account → Merchant Config (configId) → Payment Request. A payment request is always created under a merchant config, and money is expressed as a value object with the amount in minor units as a string ({ "amount": "2500", "currency": "NZD" } = $25.00).

This server speaks that model directly — endpoints, methods, and field names are matched to the live API (see Verification below).

---

Tools

Tool	What it does	Endpoint
create_payment_request	Create a request under a configId	POST /payment-requests
get_payment_status	Get a request by id	GET /payment-requests/{id}
void_payment_request	Void (cancel) a request	POST /payment-requests/{id}/void
list_payment_requests	List by externalRef for a merchant account	GET /payment-requests/external-ref/{ref}
pay_payment_request	Settle a paid request — live call (test vs live depends on key + assetType)	POST /payment-requests/{id}/pay
create_refund	Refund a paid request (value + idempotencyKey + externalRef)	POST /payment-requests/{id}/refund
list_merchants	Merchants visible to the API key	GET /merchants
get_merchant	Merchant details by id	GET /merchants/{id}
create_merchant	Create a merchant under an account	POST /merchants

Auth is via the x-api-key header.

---

Setup

1. Credentials — a public test key is documented at docs.centrapay.com/api/auth; for your own merchant config, contact integrations@centrapay.com.

2. Install and build

git clone https://github.com/CedricConday/centrapay-mcp
cd centrapay-mcp
npm install && npm run build

3. Add to Claude Code

claude mcp add centrapay-mcp node /path/to/centrapay-mcp/dist/index.js \
  -e CENTRAPAY_API_KEY=your_key

---

Verification

The request contract (endpoints, methods, body shapes, x-api-key auth) is pinned by contract tests (src/__tests__/payments.test.ts) that mock fetch and assert the exact method, path, and body for create / pay / refund — including the required refund idempotencyKey. Note: Centrapay has no separate sandbox host — service.centrapay.com is production, and test vs live is determined by your API key and the asset types you settle with, so pay / refund are real money-moving calls. A full create → pay → refund round-trip needs a configId under your own merchant account, so response formatting stays defensive (known fields with fallbacks, plus raw passthrough) until pinned against a live create.

---

Why

Centrapay builds the payment infrastructure NZ merchants use daily. I built this to understand their API from the outside — what integrating actually feels like, and where the friction is. If you're interviewing a candidate who already shipped a correct MCP server around your API, they've done the reading.

---

Tests

npm test
# Tests run against the real source (not reimplemented copies):
# amount → minor-unit-string coercion, and defensive response formatting.

---

Stack

TypeScript · Node.js · @modelcontextprotocol/sdk · Centrapay REST API

License

MIT