Checkout

Disclaimer: This is an unofficial, community-built project. It is not affiliated with, endorsed by, or officially connected to Checkout.com or Checkout Ltd. "Checkout.com" is a registered trademark of Checkout Ltd. This tool uses the publicly available Checkout.com REST API and requires your own valid API credentials. All development and testing was performed exclusively against the Checkout.com sandbox (test) environment for educational and learning purposes — no live/production transactions were made.

A Model Context Protocol (MCP) server that connects any MCP-compatible client to the Checkout.com API. Enables programmatic access to payments, customers, disputes, webhooks, and more — directly from your IDE or automation tooling.

28 tools across 8 domains: Payments (with L2/L3 interchange), Payment Sessions, Payment Links, Customers, Instruments, Disputes, Webhooks (read-only), and Card Metadata.

Quick Start

# Install
npm install -g checkout-mcp

# Or run directly with npx
npx checkout-mcp --secretKey sk_sbox_your_key_here

Configuration

Flag	Required	Default	Description
--secretKey	Yes	—	Your Checkout.com secret key
--publicKey	No	—	Your Checkout.com public key
--environment	No	sandbox	sandbox or production
--processingChannelId	No	—	Default processing channel ID

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

Claude Desktop (with all options)

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": [
        "-y", "checkout-mcp",
        "--secretKey", "sk_sbox_your_key_here",
        "--publicKey", "pk_sbox_your_key_here",
        "--processingChannelId", "pc_your_channel_id",
        "--environment", "sandbox"
      ]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

Tools Reference

Payments (9 tools)

Tool	Description
request_payment	Request a payment. Supports token, card, instrument sources. Includes optional L2/L3 interchange data.
get_payment	Retrieve a payment's full details by ID
get_payment_actions	Get all actions (captures, refunds, voids) for a payment
capture_payment	Capture a previously authorized payment (full or partial)
void_payment	Void an authorized payment before capture
refund_payment	Refund a captured payment (full or partial)
reverse_payment	Reverse a payment (auto-selects void or refund)
increment_payment_authorization	Increment auth amount (hotel/car rental holds)
list_payments	Search and list payments with filters (beta)

Payment Sessions (1 tool)

Tool	Description
create_payment_session	Create a Payment Session for Checkout.com's hosted payment page

Payment Links (2 tools)

Tool	Description
create_payment_link	Create a shareable payment link
get_payment_link	Retrieve payment link details

Customers (4 tools)

Tool	Description
create_customer	Create a new customer
get_customer	Retrieve customer by ID
update_customer	Update customer details
delete_customer	Delete a customer

Instruments (4 tools)

Tool	Description
create_instrument	Create a stored payment instrument from a token
get_instrument	Retrieve instrument details
update_instrument	Update instrument (expiry, billing address)
delete_instrument	Delete an instrument

Disputes (5 tools)

Tool	Description
get_dispute	Retrieve dispute (chargeback) details
accept_dispute	Accept/concede a dispute
get_dispute_evidence	Retrieve submitted evidence
provide_dispute_evidence	Upload evidence to fight a dispute
submit_dispute_evidence	Submit evidence for review

Webhooks (2 tools — read-only)

Tool	Description
list_webhooks	List all configured webhooks
get_webhook	Get a webhook's details

Card Metadata (1 tool) — Beta

Tool	Description
get_card_metadata	Look up card metadata by BIN (scheme, type, issuer, country)

Example Prompts

Once the MCP server is connected, use natural language with your LLM client. The LLM reads each tool's schema and maps your words to the correct API call.

Payments

Prompt	Tool Called
"Authorize a $25.00 USD payment using token tok_abc123, don't capture yet"	request_payment → amount: 2500, currency: "USD", source: { type: "token", token: "tok_abc123" }, capture: false
"Capture payment pay_mbv123abc in full"	capture_payment → payment_id: "pay_mbv123abc"
"Refund $10 from payment pay_mbv123abc"	refund_payment → payment_id: "pay_mbv123abc", amount: 1000
"Void payment pay_mbv123abc"	void_payment → payment_id: "pay_mbv123abc"
"Show me payment pay_mbv123abc details"	get_payment → payment_id: "pay_mbv123abc"
"What actions have been taken on payment pay_mbv123abc?"	get_payment_actions → payment_id: "pay_mbv123abc"
"List payments with reference ORDER-789"	list_payments → reference: "ORDER-789"

Payment Sessions

Prompt	Tool Called
"Create a payment session for £30.00 GBP, success URL https://shop.example.com/success, failure URL https://shop.example.com/fail"	create_payment_session → amount: 3000, currency: "GBP", success_url: "...", failure_url: "..."

Payment Links

Prompt	Tool Called
"Create a €50 payment link for order SHOP-789"	create_payment_link → amount: 5000, currency: "EUR", reference: "SHOP-789"
"Get the status of payment link pl_abc123"	get_payment_link → link_id: "pl_abc123"

Customers

Prompt	Tool Called
"Create a customer with email [email protected] and name John Doe"	create_customer → email: "[email protected]", name: "John Doe"
"Look up customer cus_abc123"	get_customer → customer_id: "cus_abc123"
"Update customer cus_abc123 email to [email protected]"	update_customer → customer_id: "cus_abc123", email: "[email protected]"
"Delete customer cus_abc123"	delete_customer → customer_id: "cus_abc123"

Instruments

Prompt	Tool Called
"Create a payment instrument from token tok_abc for customer cus_xyz"	create_instrument → type: "token", token: "tok_abc", customer: { id: "cus_xyz" }
"Get instrument src_abc123"	get_instrument → instrument_id: "src_abc123"

Disputes

Prompt	Tool Called
"Show me dispute dsp_abc123"	get_dispute → dispute_id: "dsp_abc123"
"Accept dispute dsp_abc123"	accept_dispute → dispute_id: "dsp_abc123"
"What evidence has been submitted for dispute dsp_abc123?"	get_dispute_evidence → dispute_id: "dsp_abc123"

Webhooks

Prompt	Tool Called
"List all webhooks"	list_webhooks → (no args)
"Show webhook wh_abc123 details"	get_webhook → webhook_id: "wh_abc123"

Card Metadata

Prompt	Tool Called
"Look up card BIN 424242"	get_card_metadata → bin: "424242"

Tip: You don't need to remember exact field names. The LLM reads the tool schemas and converts your natural language into the correct API call — including converting dollar amounts to minor units (e.g. $25.00 → 2500).

Level 2/3 Interchange Data

The request_payment tool supports L2 and L3 interchange data for reduced processing fees on commercial/corporate cards:

Level 2: customer_reference, tax_amount, tax_rate, postal_code
Level 3: All L2 fields + freight_amount, duty_amount, ship_from_postal_code, line_items[]

Example prompt:

"Process a $50 payment on card 4242... with Level 2 data — PO number CORP-123, tax $4.50"

Testing

# Unit tests (37 tests across 9 files)
npm test

# TypeScript type check
npm run lint

# Live sandbox integration test (requires .env with CKO_SECRET_KEY and CKO_PROCESSING_CHANNEL_ID)
source .env && export CKO_SECRET_KEY CKO_PROCESSING_CHANNEL_ID && node test-live.mjs

See TESTING_RESULTS.md for full test results and methodology.

Background

This project was built on patterns and integration logic from two existing Checkout.com projects:

Cko-Flow-Web — Payment Sessions / Flow

The Flow integration was the primary influence. Key patterns carried over:

• Direct fetch() calls with Bearer token auth — The Flow server makes raw HTTP requests to https://api.sandbox.checkout.com/payment-sessions with Authorization: Bearer ${SECRET_KEY} and Content-Type: application/json headers. This exact pattern became the foundation of the CkoClient class used across all 28 tools. The official checkout-sdk-node has unresolved ESM/CJS compatibility issues with modern Node.js, so the direct fetch approach — already proven in the Flow project — was the right call.
• Request body construction — The Flow server builds a full payment session payload: amount, currency, success_url, failure_url, billing, shipping, customer, billing_descriptor, items[], risk, metadata, and processing_channel_id. The create_payment_session tool mirrors this exact body structure and field mapping.
• 3ds key remapping — In the Flow server, 3D Secure is sent as "3ds": { "enabled": true } in the JSON body. Since JavaScript identifiers can't start with a number, the tool accepts three_ds as input and remaps it to "3ds" before sending to the API. Same pattern, same reason.
• async/await with fetch() — The Flow server uses async route handlers with await fetch(...) followed by await request.json() to parse the response. The CkoClient follows the same async flow: await fetch() → await res.text() → JSON.parse(), with added error handling around the parse step.
• Promise-based response handling — The Flow server chains .json() on the fetch response and passes the parsed result directly to res.send(). The MCP tools follow the same pattern: the client resolves to parsed JSON, and the tool handler returns it as-is for the MCP framework to serialize.

React-Payments-App — Unified Payments API / Dashboard

The payments dashboard provided the Unified Payments API request and proxy patterns:

• Card source schema — The dashboard posts directly to POST /payments with source: { type: "card", number: "4242424242424242", expiry_month: "01", expiry_year: "25", cvv: "100" }, plus amount, currency, reference, and processing_channel_id. The request_payment tool supports this exact source structure for sandbox testing.
• Proxy pattern for API calls — The dashboard routes client requests through a server-side /proxy endpoint using axios({ method, url, headers, data }) to avoid CORS. The MCP server operates on the same principle — it sits between the client (MCP host) and the Checkout.com API, forwarding structured requests with the right auth headers.
• async/await with try/catch error handling — Every route handler in the dashboard wraps the API call in try { ... } catch (err) { res.status(500).json({ error }) }. The MCP tool invocation layer uses the same pattern: each tool call is wrapped in try/catch, with errors returned as { isError: true, content: [{ text: "Error: ..." }] } instead of crashing the server.
• MongoDB persistence pattern — The dashboard stores payment responses with await collection.insertOne(responseToSave) for later retrieval via /api/paymentDetails. While the MCP server doesn't persist data itself, the same async data-handling pattern (await the operation, return the result, catch errors) is used throughout.
• Two-step payment flow — The dashboard demonstrates authorize-then-capture by posting with capture: false and tracking the authorization status. This is why the MCP server splits it into request_payment (with capture flag) and a separate capture_payment tool for the second step.

Key Programming Concepts Used

Concept	Where it's applied
async/await	Every tool handler, CkoClient methods, server startup
fetch() API	CkoClient — all HTTP communication with Checkout.com
Promise chaining	Response parsing: fetch() → .text() → JSON.parse()
Destructuring	Tool handlers extract args: const { customer_id, ...body } = args
Spread operator	Merging defaults: { ...args }, building request bodies
try/catch	Error boundary around every tool invocation and API call
Template literals	URL construction: `/payments/${args.payment_id}/captures`
Record<string, unknown> types	Type-safe request body construction
Zod schema validation	Input validation for all 28 tools before API calls
Module pattern	Each domain (payments, customers, etc.) exports tool definitions as named exports
CLI argument parsing	node:util parseArgs for --secretKey, --environment, etc.
Conditional object building	if (args.reference) body.reference = args.reference — only include fields that were provided

Development

# Install deps
npm install

# Type check
npm run lint

# Build
npm run build

# Run tests
npm test

# Dev mode (auto-reload)
npm run dev -- --secretKey sk_sbox_your_key

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│           (Claude Desktop / Cursor / VS Code / etc.)            │
└──────────────────────────┬──────────────────────────────────────┘
                           │ JSON-RPC over stdio
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                     checkout-mcp server                         │
│                                                                 │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐     │
│  │ McpServer    │   │ StdioServer  │   │ Configuration    │     │
│  │ (tool reg)   │◄──│ Transport    │   │ (CLI args parse) │     │
│  └──────┬───────┘   └──────────────┘   └──────────────────┘     │
│         │                                                       │
│         │  routes to tool handler                               │
│         ▼                                                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Tool Registry                        │    │
│  │                                                         │    │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────────┐  │    │
│  │  │ Payments │ │ Sessions │ │ Links  │ │  Customers  │  │    │
│  │  │ (9)      │ │ (1)      │ │ (2)    │ │  (4)        │  │    │
│  │  └──────────┘ └──────────┘ └────────┘ └─────────────┘  │    │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────────┐  │    │
│  │  │Instruments│ │ Disputes │ │Webhooks│ │Card Metadata│  │    │
│  │  │ (4)      │ │ (5)      │ │ (2)    │ │ (1) beta    │  │    │
│  │  └──────────┘ └──────────┘ └────────┘ └─────────────┘  │    │
│  └─────────────────────┬───────────────────────────────────┘    │
│                        │                                        │
│                        ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    CkoClient                            │    │
│  │          Thin HTTP wrapper over native fetch()          │    │
│  │       POST / GET / PUT / PATCH / DELETE methods         │    │
│  └─────────────────────────┬───────────────────────────────┘    │
│                            │                                    │
└────────────────────────────┼────────────────────────────────────┘
                             │ HTTPS (Bearer token auth)
                             ▼
┌────────────────────────────────────────────────────────────────┐
│                  Checkout.com REST API                         │
│          api.sandbox.checkout.com (sandbox)                    │
│          api.checkout.com (production)                         │
└────────────────────────────────────────────────────────────────┘

Design Decisions

• Unified Payments API over SDK — The official checkout-sdk-node has unresolved module compatibility issues with modern Node.js (ESM/CJS conflict). A thin CkoClient using native fetch() calls the Unified Payments API directly, keeps the bundle small, and gives full control over request construction.
• Stdio transport — The server communicates via stdin/stdout using JSON-RPC, which is the standard MCP transport. No HTTP server to configure, no ports to open.
• Zod schemas for every tool — Each tool declares its input schema with Zod. The MCP SDK uses these to generate JSON Schema for client-side validation and tool discovery.
• Single CJS bundle — tsup compiles everything into one ~31KB file. No runtime transpilation, no module resolution issues.
• Processing channel injection — If --processingChannelId is provided at startup, it's automatically injected into tools that accept it, so the caller doesn't need to pass it every time.

Project Structure

checkout-mcp-server/
├── src/
│   ├── index.ts                 # Entry point — server setup, tool registration
│   ├── client.ts                # CkoClient — HTTP wrapper for Checkout.com API
│   ├── configurations/
│   │   └── configurations.ts    # CLI argument parsing and validation
│   └── tools/
│       ├── types.ts             # Tool interface definition
│       ├── tools.ts             # Master tool registry (all 28 tools)
│       ├── payments/            # 9 tools — full payment lifecycle + L2/L3
│       ├── payment-sessions/    # 1 tool — hosted payment sessions
│       ├── payment-links/       # 2 tools — shareable payment links
│       ├── customers/           # 4 tools — CRUD
│       ├── instruments/         # 4 tools — stored payment methods
│       ├── disputes/            # 5 tools — chargeback management
│       ├── webhooks/            # 2 tools — event notification queries (read-only)
│       └── card-metadata/       # 1 tool — BIN lookup (beta)
├── test/                        # Unit tests (vitest)
├── dist/                        # Build output (CJS bundle)
├── .env.example                 # Template for credentials
└── package.json

Security

• API keys are passed as CLI arguments at runtime — never hardcoded
• Use .env files locally and add them to .gitignore
• The server validates key format on startup (warns on mismatched environment/key prefix)
• All API communication uses HTTPS with Bearer token authentication
• No keys are logged or included in MCP responses
• Raw card numbers are blocked in production mode — use tokens or saved instruments instead
• All HTTP requests have a 30-second timeout to prevent hanging connections

Note: This is an open-source tool provided "as is" with no warranty. Review the source code and understand what each tool does before using with production credentials. You are responsible for how you use it.

Requirements

• Node.js 18+
• Checkout.com account with API keys (Get sandbox keys)

License

MIT — see LICENSE for details.

---

This project is independently maintained by IamHamud and is not an official Checkout.com product.