erip-mcp

MCP server for Belarus ERIP / E-POS / KROK payments via aggregator APIs.
Tools are platform-specific (bepaid_erip_*, express_pay_*, webpay_*, …) — not a generic payment facade.

Disclaimer: This software is not a payment service provider, not affiliated with ОАО «НКФО «ЕРИП», and is not an official ERIP API. You need a merchant contract with an aggregator where required. See docs/legal-research-belarus.md (not legal advice).

Status: what is ready vs not

Area	Status	Notes
Express-Pay ERIP/E-POS tools	Ready (verified)	Live e2e against public sandbox (sandbox-api.express-pay.by) — list / create / get / status / cancel
Express-Pay QR tool	Implemented, not in e2e yet	Code path exists; not covered by the live test suite
bePaid ERIP tools	Implemented, unverified live	Unit tests with mocked HTTP only. Needs a real shop with ERIP enabled
bePaid KROK tools	Implemented, unverified live	Needs shop registered for KROK
WEBPAY ERIP checkout builder	Implemented, unverified live	Builds signed form; needs merchant storeid/secret
Hutki Grosh ERIP bills	Implemented, unverified live	Cookie session API; no public sandbox
Assist checkout builders	Implemented, unverified live	Form fields for test.paysec.by / paysec.by
MCP stdio + docs resources	Ready	Works without credentials (docs-only mode)
Production / live money	Use at your own risk	Default is sandbox; production writes need ERIP_MCP_ALLOW_WRITE=1
Official НКФО ERIP protocol	Out of scope	NDA / dedicated channel

Practical recommendation: start with Express-Pay to try the MCP. Treat other providers as experimental until verified against your merchant account.

Run verified Express-Pay e2e:

ERIP_MCP_LIVE=1 npm test -- src/providers/express-pay/e2e.test.ts

vs bepaid-mcp

Package	Focus
erip-mcp (this)	ERIP / E-POS / KROK via aggregators (Express-Pay verified; others untested live)
bepaid-mcp	bePaid cards (capture, void, refund, tokenize, subscriptions)

Install / run

npx -y erip-mcp

Or from source:

npm install
npm run build
node dist/index.js

Cursor / Claude Desktop

Recommended (Express-Pay public sandbox):

{
  "mcpServers": {
    "erip": {
      "command": "npx",
      "args": ["-y", "erip-mcp"],
      "env": {
        "EXPRESS_PAY_TOKEN": "a75b74cbcfe446509e8ee874f421bd66",
        "EXPRESS_PAY_SECRET_WORD": "sandbox.expresspay.by",
        "ERIP_MCP_ENV": "sandbox"
      }
    }
  }
}

bePaid (unverified — needs your shop credentials + ERIP/KROK enabled):

{
  "mcpServers": {
    "erip": {
      "command": "npx",
      "args": ["-y", "erip-mcp"],
      "env": {
        "BEPAID_SHOP_ID": "YOUR_SHOP_ID",
        "BEPAID_SECRET_KEY": "YOUR_SECRET_KEY",
        "ERIP_MCP_ENV": "sandbox"
      }
    }
  }
}

You can enable several providers at once; tools register per present credentials.
See also examples/cursor-mcp.json.

Without credentials the server still exposes documentation resources (erip://docs/...).

Environment

Variable	Required	Description
EXPRESS_PAY_TOKEN	for Express-Pay tools	API token
EXPRESS_PAY_SECRET_WORD	if signatures required	HMAC secret (sandbox: sandbox.expresspay.by)
EXPRESS_PAY_API_BASE_URL	no	Defaults from ERIP_MCP_ENV
BEPAID_SHOP_ID	for bePaid tools	Shop ID from bePaid backoffice
BEPAID_SECRET_KEY	for bePaid tools	Secret key
BEPAID_API_BASE_URL	no	Default https://api.bepaid.by
WEBPAY_STORE_ID	for WEBPAY tools	Merchant store id
WEBPAY_SECRET_KEY	for WEBPAY tools	Signature secret
WEBPAY_PAYMENT_BASE_URL	no	Sandbox/prod payment URL
HUTKIGROSH_USER	for Hutki tools	API login
HUTKIGROSH_PASSWORD	for Hutki tools	API password
HUTKIGROSH_API_BASE_URL	no	Default https://www.hutkigrosh.by/API/v1
ASSIST_MERCHANT_ID	for Assist tools	Merchant id
ASSIST_PAYMENT_BASE_URL	no	Default test/prod Assist host
ERIP_MCP_ENV	no	sandbox (default) or production
ERIP_MCP_ALLOW_WRITE	production writes	Set 1 to allow create/cancel/delete in production

Tools

Express-Pay ERIP / E-POS — verified in sandbox e2e*

Tool	API	Live e2e
express_pay_erip_list_invoices	GET /v1/invoices	yes
express_pay_erip_create_invoice	POST /v1/invoices	yes
express_pay_erip_get_invoice	GET /v1/invoices/{id}	yes
express_pay_erip_get_invoice_status	GET /v1/invoices/{id}/status	yes
express_pay_erip_cancel_invoice	DELETE /v1/invoices/{id}	yes
express_pay_epos_get_qrcode	GET /v1/qrcode/getqrcode	not yet

*Against Express-Pay’s documented public sandbox tokens, not a private merchant account.

amount is in major units (e.g. 10.5 → API 10,50).

bePaid ERIP — code present, live unknown

Tool	API	Live e2e
bepaid_erip_create_payment	POST /beyag/payments (type: erip)	no
bepaid_erip_get_payment	GET /beyag/payments/:uid or ?order_id=	no
bepaid_erip_delete_payment	DELETE /beyag/payments/:uid	no

amount is in minor units (e.g. 1000 = 10.00 BYN).
bePaid uses the same API host with "test": true (no separate sandbox URL). The shop must have ERIP enabled.

bePaid KROK — code present, live unknown

Tool	API	Live e2e
bepaid_krok_create_payment	POST /beyag/transactions/payments (method.type: krok)	no
bepaid_krok_get_transaction	GET /beyag/transactions/:uid	no

WEBPAY ERIP — form builder (no remote call)

Tool	Notes	Live e2e
webpay_erip_build_checkout	SHA1 signature + wsb_tab=erip; POST fields to WEBPAY	no

Hutki Grosh ERIP — code present, live unknown

Tool	API	Live e2e
hutkigrosh_erip_create_bill	POST /Invoicing/Bill	no
hutkigrosh_erip_get_bill	GET /Invoicing/Bill({id})	no
hutkigrosh_erip_get_bill_status	GET /Invoicing/BillStatus({id})	no
hutkigrosh_erip_delete_bill	DELETE /Invoicing/Bill({id})	no
hutkigrosh_erip_list_bills	GET /Invoicing/Bills(...)	no
hutkigrosh_erip_get_qrcode	GET /Invoicing/BillQRCode(...)	no

Assist — form builders (no remote call)

Tool	Notes	Live e2e
assist_build_payment_checkout	Fields for /pay/order.cfm	no
assist_build_create_bill	Fields for /bill/createbill.cfm	no

Resources

• erip://docs/overview
• erip://docs/legal
• erip://docs/bepaid-erip

Roadmap

• Live verification of bePaid / WEBPAY / Hutki / Assist / KROK with real merchant accounts
• E2E for express_pay_epos_get_qrcode
• No generic create_payment facade

See docs/plan-mcp-server.md.

License

MIT