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

erip-mcp

erip-mcp

Status: what is ready vs not

vs bepaid-mcp

Install / run

Cursor / Claude Desktop

Environment

Tools

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

bePaid ERIP — code present, live unknown

bePaid KROK — code present, live unknown

WEBPAY ERIP — form builder (no remote call)

Hutki Grosh ERIP — code present, live unknown

Assist — form builders (no remote call)

Resources

Roadmap

License

Latest Blog Posts

MCP directory API