@codespar/mcp-izipay
@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@alphaEnvironment
IZIPAY_USERNAME="..." # merchant username
IZIPAY_PASSWORD="..." # merchant password (secret)
IZIPAY_MERCHANT_CODE="..." # codigoComercio
IZIPAY_ENV="production" # or "sandbox"
IZIPAY_BASE_URL="..." # Optional overrideDefaults:
IZIPAY_ENV=production→https://api.izipay.peIZIPAY_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-izipayEnterprise
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