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

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

# 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