Getting started

MCP server

Let an AI agent create and read payments for you, sandbox-first.

MCP (Model Context Protocol) is an open standard that lets AI agents like Claude call external tools. kasera-pay-mcp is our MCP server: run it next to your agent and the agent can create payment requests, look them up, read your pricing and drive test payments — through the same public /v1 API these docs describe, with your API key never leaving the server's environment.

Install

The server ships as an npm package, kasera-pay-mcp, and runs with npx kasera-pay-mcp — no install step of its own.

Claude Code

claude mcp add kasera-pay -e KASERA_API_KEY=kp_test_... -- npx kasera-pay-mcp

Claude Desktop & Cursor

Both read the same JSON shape — Claude Desktop from claude_desktop_config.json, Cursor from .cursor/mcp.json:

{
  "mcpServers": {
    "kasera-pay": {
      "command": "npx",
      "args": ["kasera-pay-mcp"],
      "env": { "KASERA_API_KEY": "kp_test_..." }
    }
  }
}

Environment

Variable	Meaning
`KASERA_API_KEY`	Required. kp_test_... or kp_live_... from Settings → Developer. Set in the server's environment, never passed as a tool argument.
`KASERA_BASE_URL`	Optional. Defaults to https://pay.kasera.id.
`KASERA_ALLOW_LIVE`	Optional. A kp_live_ key gets read tools only unless this is true.

Tools

Five tools, each a thin call over one /v1 endpoint. The server also serves the live OpenAPI document as the resource kasera-pay://openapi, so an agent can read the full API contract on its own. There is no payouts tool — payouts are not part of the public /v1 API.

Tool	What it does
`create_payment_request`	Create a payment request and get its checkout_url (POST /v1/transactions).
`get_payment`	Fetch one payment request by its payreq_* id (GET /v1/transactions/{id}).
`list_payments`	One page of payment requests, newest first, with a next_cursor to page on (GET /v1/transactions).
`get_pricing`	The account's enabled methods with per-method fees, amount bounds and required customer fields (GET /v1/payment_methods).
`simulate_payment`	Drive a pending test payment to succeeded or expired. Test keys only — refused on live keys, always.

Safety model

An agent holding your key is a caller like any other, so the server is built sandbox-first:

Start with a test key. A kp_test_ key gets the full surface, and nothing it creates can move real money — the same test mode described in Test mode.

Live keys are read-only by default. With a kp_live_ key, create_payment_request is refused with instructions to set KASERA_ALLOW_LIVE=true — a deliberate step you take in the server's environment, not something an agent can talk its way past. simulate_payment is refused on a live key unconditionally: live payments are paid by real buyers, never simulated.

Every create carries an Idempotency-Key. The server generates a fresh UUID key per call, so a network retry of one call cannot bill twice. Two separate calls are still two payments — asking the agent to create the same payment twice creates it twice.

Sandbox walkthrough

With the server configured on a kp_test_ key, walk a payment end to end from the conversation:

1. Create. Ask the agent to create a Rp150.000 test payment. It calls create_payment_request and reports back a payreq_* id, a checkout_url, and the fee and net your account's rates stamp on it.

2. Simulate. A test payment never confirms on its own. Ask the agent to simulate it as paid: simulate_payment drives it to succeeded — and fires the same signed payment.paid webhook a real payment would, to your test endpoint.

3. Get. Ask for the payment's status. get_payment returns it with status: succeeded, livemode: false, and paid_at set.