Safrapay

v0.2.0-alpha.1API Keyalpha

Banco Safra's acquirer — premium/enterprise private-banking segment. Operated on Aditum's payment platform. Authorize/capture/cancel, Pix, boleto, tokenization, split, digital statements. Alpha on npm — BCRYPT auth recipe and body casing pending sandbox validation.

22 tools4 env vars🇧🇷 Brazilalpha — pending validation

Install

terminal

$ npm install @codespar/mcp-safrapay@alpha

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "safrapay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-safrapay@alpha"
      ],
      "env": {
        "SAFRAPAY_CLIENT_ID": "<your_safrapay_client_id>",
        "SAFRAPAY_CLIENT_SECRET": "<your_safrapay_client_secret>",
        "SAFRAPAY_MERCHANT_ID": "<your_safrapay_merchant_id>"
      }
    }
  }
}

After restart, your agent can call any of the 22 tools below — try authorize_payment first.

Environment variables · 4

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

SAFRAPAY_CLIENT_ID

required

Safrapay merchant CNPJ (sent as merchantCredential header on auth)

SAFRAPAY_CLIENT_SECRET

requiredsecret

Safrapay MerchantToken used to compute the BCRYPT Authorization header on auth

SAFRAPAY_MERCHANT_ID

required

Safrapay merchant id (used in request bodies where applicable)

SAFRAPAY_ENV

optional

Environment: 'sandbox' or 'production'. Defaults to sandbox.

Available tools · 22

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEauthorize_payment

Authorize a credit-card payment on Safrapay. Set preauth=true to authorize only (use capture_payment later); false to authorize+capture atomically.

WRITEcapture_payment

Capture a previously authorized (pre-auth) payment.

DELETEcancel_payment

Cancel (void) an authorized-but-uncaptured payment. Also used for full refund of a captured payment in Safrapay.

DELETErefund_payment

Refund a captured payment. Pass amount for a partial refund; omit for full. Safrapay routes both through /v2/charge/cancelation with an amount field.

WRITEcreate_pix

Create a Pix charge. Returns qr_code (EMV copy-paste payload), qr_code_image, and chargeId.

WRITEcreate_boleto

Create a boleto charge. Returns boleto PDF URL, barcode, digitable line, and expiration date.

WRITEget_payment

Retrieve a charge by Safrapay chargeId. Works for credit, Pix, and boleto.

WRITEtokenize_card

Tokenize a card for PCI-safe reuse. Set temporary=true for a single-use token (POST /v2/temporary/card); false for a persistent card-on-file (POST /v2/card).

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.