Mcp Safrapay

io.github.codesparPublished by GitHub account codesparv0.2.0-alpha.3Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Local MCP server for the Safrapay (Banco Safra) acquirer, letting an assistant create and manage card, Pix and boleto charges, refunds, splits, recurrences and

What you can do
Authorize, capture, cancel and refund card payments, and run 3-D Secure authentication before authorization. Create Pix and boleto charges, payment links, split rules and recurring-billing subscriptions, and cancel recurrences. Look up charges by chargeId or merchant order id, list transactions, simulate installments and retrieve statements and settlement reports. Tokenize cards, revoke stored card tokens, query chargeback details and bulk-register webhooks.
When to use it
For Brazilian merchants or developers working with Safrapay/Aditum payments who want an assistant to drive charge creation, refunds, reconciliation lookups or webhook setup. It is an early alpha, so it is best suited to sandbox experimentation rather than live payment operations.
Requirements
Runs locally as an npm package (Node.js) over stdio, or over HTTP when MCP_HTTP is set. Requires SAFRAPAY_CLIENT_ID (merchant CNPJ), SAFRAPAY_CLIENT_SECRET (merchant token), SAFRAPAY_MERCHANT_ID and optionally SAFRAPAY_ENV (sandbox by default). Network access to the Aditum-hosted Safrapay hosts is needed.
Before you install
Handles real payment credentials: SAFRAPAY_CLIENT_SECRET is a merchant token used to compute the auth header, so keep it out of logs. Tools move money and change data — authorizing, capturing, refunding, cancelling, creating charges and recurrences, revoking card tokens and registering webhooks. The README states the auth flow and endpoints are unvalidated guesses, so test in sandbox first and avoid production until verified.

Installation

In SourceWeft

  1. Open Mcp Safrapay in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@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)

ToolPurpose
authorize_paymentAuthorize a credit-card payment on Safrapay.
capture_paymentCapture a previously authorized (pre-auth) payment.
cancel_paymentCancel (void) an authorized-but-uncaptured payment.
refund_paymentRefund a captured payment.
create_pixCreate a Pix charge.
create_boletoCreate a boleto charge.
get_paymentRetrieve a charge by Safrapay chargeId.
tokenize_cardTokenize a card for PCI-safe reuse.
create_split_ruleConfigure split distribution for an existing charge.
get_statementRetrieve the digital statement (extrato).
list_transactionsList charges with optional filters.
delete_card_tokenRevoke a stored card token.
search_by_merchant_orderLook up charges by the merchant-side order identifier (the order_id supplied at creation).
query_chargebackRetrieve chargeback (contestacao) detail for a charge: reason code, acquirer deadline, dispute amount, evid...
query_installmentsSimulate an installment plan for a given amount.
authenticate_3dsKick off 3-D Secure authentication before authorize_payment.
create_recurrenceCreate a recurring-billing subscription.
get_recurrenceRetrieve a recurrence by id: schedule, next-charge date, charge history, status.
cancel_recurrenceCancel an active recurrence.
get_settlement_reportRetrieve a settlement (liquidacao) report from the reconciliation host.
create_payment_linkCreate a hosted-checkout payment link.
register_webhookBulk-register webhook subscriptions on the Safrapay webhook product.

Install

bash
npm install @codespar/mcp-safrapay@alpha

Environment

bash
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:

ProductSandboxProduction
Gateway (payments)https://payment-dev.aditum.com.brhttps://payment.aditum.com.br
Portal (management)https://portal-dev.aditum.com.brhttps://portal-api.aditum.com.br
Reconciliationhttps://reconciliation-dev.aditum.com.brhttps://reconciliation-api.aditum.com.br
Webhookhttps://webhook-dev.aditum.com.brhttps://webhook.aditum.com.br

Authentication

Gateway uses a two-step bootstrap:

  1. POST {gateway}/v2/merchant/auth with headers Authorization: <BCRYPT(CNPJ+MerchantToken)> and merchantCredential: <CNPJ> to exchange for a JWT access token.
  2. 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

bash
# stdio (default)npx @codespar/mcp-safrapay
# HTTPMCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-safrapay

Endpoint map (used by tools)

ToolMethodPath (under gateway, unless noted)
authorize_paymentPOST/v2/charge/authorization or /v2/charge/preauthorization
capture_paymentPUT/v2/charge/capture/{chargeId}
cancel_paymentPUT/v2/charge/cancelation/{chargeId}
refund_paymentPUT/v2/charge/cancelation/{chargeId} (partial amount)
create_pixPOST/v2/charge/pix
create_boletoPOST/v2/charge/boleto
get_paymentGET/v2/charge/{chargeId}
tokenize_cardPOST/v2/card (or /v2/temporary/card)
create_split_rulePUT/v2/charge/split/{chargeId}
get_statementGET/v2/Account/Movement/Extract
list_transactionsGET/v2/charges
register_webhookPOST{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

Source: packages/payments/safrapay/README.md at commit d0a519a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0-alpha.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts