Culqi

v0.2.0API Key

Peru's Stripe-analog — default PSP for Peruvian D2C and SaaS (CulqiOnline, CulqiLink, CulqiFull). Brings Peru into the catalog alongside BR/MX/AR/CO/CL.

20 tools1 env vars🇵🇪 Perustable on npm

Install

terminal

$ npm install @codespar/mcp-culqi

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "culqi": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-culqi"
      ],
      "env": {
        "CULQI_SECRET_KEY": "<your_culqi_secret_key>"
      }
    }
  }
}

After restart, your agent can call any of the 20 tools below — try create_token first.

Environment variables · 1

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

CULQI_SECRET_KEY

requiredsecret

Culqi secret key. Use sk_test_... for sandbox, sk_live_... for production.

Available tools · 20

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEcreate_token

Tokenize a card (POST /tokens). Returns a token id like tkn_xxx. Tokenization is typically done client-side via culqi.js or mobile SDKs; this tool is primarily for test scripts and integration tests. Never send real PANs from a backend without PCI scope.

WRITEcreate_charge

Create a charge (POST /charges). Amount is in cents of the currency (e.g. 1000 = S/ 10.00 PEN). source_id accepts a token id (tkn_xxx) or a stored card id (crd_xxx).

WRITEget_charge

Retrieve a charge by Culqi id.

WRITElist_charges

List charges (GET /charges) with optional filters. Filters are passed as query params: amount, min_amount, max_amount, installments, currency_code, code (auth code), decline_code, fraud_score, first_name, last_name, email, country_code, creation_date_from (ms), creation_date_to (ms), limit, before, after.

WRITEcapture_charge

Capture a previously-authorized charge (POST /charges/{id}/capture). Use after creating a charge with capture=false. Must be called within 10 days of authorization.

DELETErefund_charge

Refund a captured charge (POST /refunds). Partial refunds supported by setting amount below the charge total.

DELETEget_refund

Retrieve a refund by id (GET /refunds/{id}).

WRITEcreate_customer

Create a customer record (POST /customers). Use the returned customer_id with create_card to save reusable cards.

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.