Openpay

v0.2.0API Key

BBVA-owned Mexican gateway — the MX alternative to Conekta. Cards, OXXO, SPEI, subscriptions (native), marketplace payouts. Closes the BBVA-rail story for Mexico.

23 tools3 env vars🇲🇽 Mexicostable on npm

Install

terminal

$ npm install @codespar/mcp-openpay

Quickstart

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

claude_desktop_config.json

{
  "mcpServers": {
    "openpay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-openpay"
      ],
      "env": {
        "OPENPAY_MERCHANT_ID": "<your_openpay_merchant_id>",
        "OPENPAY_PRIVATE_KEY": "<your_openpay_private_key>"
      }
    }
  }
}

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

Environment variables · 3

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

OPENPAY_MERCHANT_ID

required

Openpay merchant id (forms part of the API URL path)

OPENPAY_PRIVATE_KEY

requiredsecret

Openpay private API key (used as HTTP Basic auth username with empty password)

OPENPAY_ENV

optional

Environment: 'sandbox' (default) or 'production'. Selects between https://sandbox-api.openpay.mx and https://api.openpay.mx.

Available tools · 23

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

WRITEcreate_charge

Create a charge. Pass customer_id to charge at a customer scope (POST /customers/{customer_id}/charges); omit to charge at merchant scope (POST /charges). Methods: 'card' (requires source_id token), 'bank_account' (SPEI — returns CLABE reference), 'store' (OXXO — returns barcode/reference). Amounts are in major units (e.g. 100 = 100 MXN).

WRITEget_charge

Retrieve a charge. Pass customer_id to fetch at customer scope (GET /customers/{customer_id}/charges/{id}); omit for merchant scope (GET /charges/{id}).

WRITEcapture_charge

Capture a previously authorized charge (when the original charge used capture=false). Pass amount to capture less than the authorized total; omit to capture the full authorized amount.

DELETErefund_charge

Refund a captured charge. Supports partial refunds via amount; omit amount for a full refund.

WRITEcreate_customer

Create a customer record. Set requires_account=true to create an associated Openpay wallet for the customer; false for a payment-only record.

READget_customer

Retrieve a customer by Openpay customer id.

READlist_customers

List customers with optional filters. All parameters are passed as query params.

WRITEcreate_card

Tokenize a card. Pass customer_id to attach to a stored customer (POST /customers/{customer_id}/cards); omit for a merchant-level token (POST /cards). Prefer tokenizing client-side with Openpay.js to avoid PCI scope.

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.