@codespar/mcp-izipay

MCP server for Izipay — Peru's enterprise acquirer.

Izipay is the merchant-facing brand of Niubiz (Visa + Peruvian banks joint venture), the largest card acquirer in Peru with 20%+ share. Niubiz/Izipay is the default for enterprise merchants with serious volume and a direct acquirer contract.

Positioning vs Culqi

| | @codespar/mcp-culqi | @codespar/mcp-izipay | |---|---|---| | Segment | Peru SMB | Peru enterprise | | Type | PSP (Stripe-analog) | Acquirer (Niubiz) | | Onboarding | Self-serve | Commercial contract | | Customers | D2C, SaaS, startups | Retail chains, airlines, utilities, banks |

Peruvian merchants with serious volume typically have an Izipay acquirer contract before they adopt a PSP — different customers, different contracts, different commercial terms. The two servers complement each other.

Status: alpha

This is 0.1.0-alpha.1. Izipay's developer portal at developers.izipay.pe is contract-gated — the public homepage advertises the API but the full REST reference is only available to contracted merchants. The endpoint paths in this server are best-effort inferences from Izipay's public SDK repositories (github.com/izipay-pe) and common Niubiz/Izipay REST conventions. Every endpoint below should be validated against your integration kit before going live, and corrections are welcome via PR.

Best-guess endpoints (unverified)

| Tool | Method | Path | |---|---|---| | auth (internal) | POST | /auth/login | | create_charge | POST | /v1/charges | | capture_charge | POST | /v1/charges/{id}/capture | | cancel_charge | POST | /v1/charges/{id}/cancel | | refund_charge | POST | /v1/charges/{id}/refund | | get_charge | GET | /v1/charges/{id} | | tokenize_card | POST | /v1/tokens | | delete_token | DELETE | /v1/tokens/{id} | | create_installment_plan | POST | /v1/installments | | list_transactions | GET | /v1/transactions | | get_settlement | GET | /v1/settlements/{date} |

Tools (20)

| Tool | Purpose | |---|---| | create_charge | Authorize a card payment. | | capture_charge | Capture a previously authorized charge (when capture=false was used in create_charge). | | cancel_charge | Void an authorized-but-uncaptured charge. | | refund_charge | Refund a captured charge. | | get_charge | Retrieve a charge by Izipay charge id. | | tokenize_card | Tokenize a card for PCI-safe reuse. | | delete_token | Delete a stored card token. | | create_installment_plan | Create a Peruvian cuotas (installment) plan on a charge. | | list_transactions | List transactions for reconciliation. | | get_settlement | Get the daily settlement batch (liquidación) for a given date. | | get_charge_by_order | Retrieve a charge by the merchant-side orderNumber (order_id passed to create_charge). | | list_installment_options | Query available cuota programs for a given card BIN and amount. | | list_settlements | List settlement batches across a date range. | | create_payment_link | Create a hosted payment link (pay-by-link). | | get_payment_link | Retrieve a payment link by id. | | pay_yape | Initiate a Yape direct payment. | | pay_plin | Initiate a Plin direct payment. | | authenticate_3ds | Complete a 3-D Secure challenge. | | create_subscription | Start a recurring card charge (subscription). | | cancel_subscription | Cancel an active subscription. |

Install

npm install @codespar/mcp-izipay@alpha

Environment

IZIPAY_USERNAME="..."       # merchant username
IZIPAY_PASSWORD="..."       # merchant password (secret)
IZIPAY_MERCHANT_CODE="..."  # codigoComercio
IZIPAY_ENV="production"     # or "sandbox"
IZIPAY_BASE_URL="..."       # Optional override

Defaults:

• IZIPAY_ENV=production → https://api.izipay.pe
• IZIPAY_ENV=sandbox → https://sandbox-api.izipay.pe

Authentication

JWT Bearer. On the first API call the server POSTs { username, password, merchantCode } to /auth/login, caches the returned JWT in memory, and attaches it as Authorization: Bearer <jwt> on every subsequent request. The cached JWT is refreshed 60s before expiry. Transparent to callers.

Run

# stdio (default)
npx @codespar/mcp-izipay

# HTTP
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-izipay

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT