io.github.codespar/mcp-safrapay

io.github.codespar/mcp-safrapay · 273 stars · TypeScript · MIT

MCP server MCP server for Safrapay — Banco Safra acquirer: credit, Pix, boleto + split, 3DS, chargebacks

Install

The repo has no one-line install. Follow its README.

Published as

npm@codespar/mcp-safrapaystdio

From the server's entry in the official MCP Registry.

Open the repo

Configuration

Name	Set as	What it is
`SAFRAPAY_CLIENT_ID`Required	Env var	Safrapay merchant CNPJ (sent as merchantCredential header on auth)
`SAFRAPAY_CLIENT_SECRET`Required · Secret	Env var	Safrapay MerchantToken used to compute the BCRYPT Authorization header on auth
`SAFRAPAY_MERCHANT_ID`Required	Env var	Safrapay merchant id (used in request bodies where applicable)
`SAFRAPAY_ENV`Optional	Env var	Environment: 'sandbox' or 'production'. Defaults to sandbox.

Files

packages/payments/safrapay/README.md

@codespar/mcp-safrapay

MCP server for Safrapay — Banco Safra's acquirer. B2B-banking crossover focused on mid-to-large BR merchants and private-banking clientele.

Safrapay's API surface is operated on Aditum's payment platform (documented at safrapay-docs.aditum.com.br). The gateway, portal, reconciliation, and webhook products are split across separate base hosts.

Status: 0.1.0-alpha.1. The endpoint paths here were derived from the Aditum-hosted Safrapay developer docs (publicly reachable). Auth flow (BCRYPT + CNPJ on gateway, JWT Bearer thereafter) is best-effort: the BCRYPT hash input format is not fully specified in public docs and very likely requires a sandbox account to finalize. Treat all tools as scaffolding until validated against a live sandbox merchant.

Tools (22)

Tool	Purpose
`authorize_payment`	Authorize a credit-card payment on Safrapay.
`capture_payment`	Capture a previously authorized (pre-auth) payment.
`cancel_payment`	Cancel (void) an authorized-but-uncaptured payment.
`refund_payment`	Refund a captured payment.
`create_pix`	Create a Pix charge.
`create_boleto`	Create a boleto charge.
`get_payment`	Retrieve a charge by Safrapay chargeId.
`tokenize_card`	Tokenize a card for PCI-safe reuse.
`create_split_rule`	Configure split distribution for an existing charge.
`get_statement`	Retrieve the digital statement (extrato).
`list_transactions`	List charges with optional filters.
`delete_card_token`	Revoke a stored card token.
`search_by_merchant_order`	Look up charges by the merchant-side order identifier (the order_id supplied at creation).
`query_chargeback`	Retrieve chargeback (contestacao) detail for a charge: reason code, acquirer deadline, dispute amount, evid...
`query_installments`	Simulate an installment plan for a given amount.
`authenticate_3ds`	Kick off 3-D Secure authentication before authorize_payment.
`create_recurrence`	Create a recurring-billing subscription.
`get_recurrence`	Retrieve a recurrence by id: schedule, next-charge date, charge history, status.
`cancel_recurrence`	Cancel an active recurrence.
`get_settlement_report`	Retrieve a settlement (liquidacao) report from the reconciliation host.
`create_payment_link`	Create a hosted-checkout payment link.
`register_webhook`	Bulk-register webhook subscriptions on the Safrapay webhook product.

Install

npm install @codespar/mcp-safrapay@alpha

Environment

SAFRAPAY_CLIENT_ID="..."      # Merchant CNPJ (sent as merchantCredential)
SAFRAPAY_CLIENT_SECRET="..."  # MerchantToken (used to compute BCRYPT)
SAFRAPAY_MERCHANT_ID="..."    # Safrapay merchant id (body field where required)
SAFRAPAY_ENV="sandbox"        # 'sandbox' (default) or 'production'

Base URLs

Safrapay splits its API into four products hosted on distinct domains:

Product	Sandbox	Production
Gateway (payments)	`https://payment-dev.aditum.com.br`	`https://payment.aditum.com.br`
Portal (management)	`https://portal-dev.aditum.com.br`	`https://portal-api.aditum.com.br`
Reconciliation	`https://reconciliation-dev.aditum.com.br`	`https://reconciliation-api.aditum.com.br`
Webhook	`https://webhook-dev.aditum.com.br`	`https://webhook.aditum.com.br`

Authentication

Gateway uses a two-step bootstrap:

POST {gateway}/v2/merchant/auth with headers Authorization: <BCRYPT(CNPJ+MerchantToken)> and merchantCredential: <CNPJ> to exchange for a JWT access token.
Subsequent calls send Authorization: Bearer <jwt>.

The server caches the JWT in memory until 60 s before expiry. The BCRYPT input concatenation is an informed guess; refine once you have a sandbox account.

Run

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

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

Endpoint map (used by tools)

Tool	Method	Path (under gateway, unless noted)
`authorize_payment`	POST	`/v2/charge/authorization` or `/v2/charge/preauthorization`
`capture_payment`	PUT	`/v2/charge/capture/{chargeId}`
`cancel_payment`	PUT	`/v2/charge/cancelation/{chargeId}`
`refund_payment`	PUT	`/v2/charge/cancelation/{chargeId}` (partial amount)
`create_pix`	POST	`/v2/charge/pix`
`create_boleto`	POST	`/v2/charge/boleto`
`get_payment`	GET	`/v2/charge/{chargeId}`
`tokenize_card`	POST	`/v2/card` (or `/v2/temporary/card`)
`create_split_rule`	PUT	`/v2/charge/split/{chargeId}`
`get_statement`	GET	`/v2/Account/Movement/Extract`
`list_transactions`	GET	`/v2/charges`
`register_webhook`	POST	`{webhook}/v1/webhook/bulk`

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

Facts

Kind: MCP server
Repo: codespar/mcp-dev-latam
Group: Uncategorized
Stars: 273
License: MIT
Language: TypeScript
Last push: 2026-09-27
Forks: 50
MCP Registry: io.github.codespar/mcp-safrapay
Homepage: codespar.dev/servers
Topics: agentic-commerce, ai-agents, brazil, claude, fintech, latin-america, llm-tools, mcp, model-context-protocol, nfe, open-finance, payments, pix

io.github.codespar/mcp-safrapay

Install

Published as

Configuration

Files

@codespar/mcp-safrapay

Tools (22)

Install

Environment

Base URLs

Authentication

Run

Endpoint map (used by tools)

Enterprise

License

Facts

More on this shelf