@codespar/mcp-braspag

MCP server for Braspag — Cielo Group's enterprise orchestration layer: multi-acquirer routing, token vault (Cartão Protegido), recurrence, marketplace split, antifraud orchestration.

Braspag vs. Cielo (Acquirer)

CodeSpar ships two Cielo Group servers with different business contracts:

| Server | Product | What it is | Who uses it | |---|---|---|---| | @codespar/mcp-cielo | Cielo Acquirer | Direct card acquiring rails (credit, debit, boleto, Pix) | Any merchant taking cards through Cielo | | @codespar/mcp-braspag (this) | Braspag / Pagador | Enterprise orchestration on top of any acquirer | Enterprise BR retail (Magalu-tier): multi-acquirer routing, token vault, marketplace split |

Braspag orchestrates across acquirers. You keep your Cielo (or Rede, or Stone) acquiring contract and layer Braspag on top for: smart routing, failover, vaulting cards once and reusing across acquirers (Cartão Protegido), driving recurrence, and splitting marketplace capture across sub-merchants.

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "braspag": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-braspag"],
      "env": {
        "BRASPAG_MERCHANT_ID": "your-merchant-uuid",
        "BRASPAG_MERCHANT_KEY": "your-merchant-key",
        "BRASPAG_ENV": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add braspag -- npx @codespar/mcp-braspag

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "braspag": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-braspag"],
      "env": {
        "BRASPAG_MERCHANT_ID": "your-merchant-uuid",
        "BRASPAG_MERCHANT_KEY": "your-merchant-key",
        "BRASPAG_ENV": "sandbox"
      }
    }
  }
}

Tools (22)

| Tool | Purpose | |---|---| | create_sale | Create a sale on the Braspag Transaction API (POST /sales). | | capture_sale | Capture a pre-authorized sale (PUT /sales/{paymentId}/capture). | | void_sale | Void / cancel a sale (PUT /sales/{paymentId}/void). | | create_recurrent | Create a recurrent payment schedule (POST /recurrentPayments). | | disable_recurrent | Deactivate a recurrent payment (PUT /recurrentPayments/{recurrentPaymentId}/Deactivate). | | update_recurrent_amount | Update the charged amount on a recurrent payment (PUT /recurrentPayments/{recurrentPaymentId}/Amount). | | get_sale | Get sale detail by PaymentId (GET /sales/{paymentId} — Query API). | | get_sale_by_order_id | Look up sale(s) by MerchantOrderId (GET /sales?merchantOrderId=X — Query API). | | get_recurrent | Get a recurrent payment's configuration and history (GET /recurrentPayments/{recurrentPaymentId} — Query API). | | tokenize_card | Tokenize a card into the Braspag vault / Cartão Protegido (POST /card). | | get_card_token | Retrieve the stored card data associated with a Cartão Protegido token (GET /card/{token}). | | create_split_sale | Create a sale with marketplace split rules (POST /sales with Payment.SplitPayments). | | create_sale_3ds | Create a 3DS-authenticated credit sale (POST /sales). | | create_zero_auth | Zero-dollar authorization / card validation (POST /zeroauth). | | create_boleto_sale | Convenience wrapper to create a Boleto sale (POST /sales with Payment.Type=Boleto). | | create_pix_sale | Convenience wrapper to create a Pix sale (POST /sales with Payment.Type=Pix). | | reactivate_recurrent | Reactivate a previously deactivated recurrent payment (PUT /recurrentPayments/{recurrentPaymentId}/Reactiva... | | update_recurrent_next_payment | Update the NextPaymentDate on a recurrent payment (PUT /recurrentPayments/{recurrentPaymentId}/NextPaymentD... | | update_recurrent_payment | Update the Payment (CreditCard + Customer) on a recurrent schedule (PUT /recurrentPayments/{recurrentPaymen... | | create_antifraud_analysis | Submit a standalone Antifraud analysis (POST /fraudanalysis) through Braspag's antifraud orchestration (Cyb... | | delete_card_token | Delete a Cartão Protegido vault token (DELETE /card/{token}). | | create_split_capture | Capture a previously authorized split sale with overridden per-sub-merchant amounts (PUT /sales/{paymentId}... |

Authentication

Braspag uses MerchantId (UUID) and MerchantKey (secret) headers on both the Transaction API and the Query API.

Environments

| Env | Transaction API | Query API | |-----|-----------------|-----------| | sandbox (default) | https://apisandbox.braspag.com.br/v2 | https://apiquerysandbox.braspag.com.br/v2 | | production | https://api.braspag.com.br/v2 | https://apiquery.braspag.com.br/v2 |

Set via BRASPAG_ENV=production to switch.

Get your credentials

1. Reach out to your Cielo / Braspag account team to enable Braspag Pagador on your merchant contract.
2. Receive your MerchantId (UUID) and MerchantKey.
3. Set the environment variables below.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BRASPAG_MERCHANT_ID | Yes | Merchant UUID | | BRASPAG_MERCHANT_KEY | Yes | Merchant secret key | | BRASPAG_ENV | No | sandbox (default) or production |

Roadmap

v0.2 (planned)

• create_sale_with_card_token — convenience wrapper that uses a Cartão Protegido token
• delete_card_token — revoke a vault token
• get_sale_antifraud — Query API antifraud detail
• update_recurrent_payment — update non-amount fields on a recurrent
• create_zero_auth — zero-dollar auth for card validation

v0.3 (planned)

• Marketplace: sub-merchant onboarding endpoints
• Bank slip (boleto) registered-only helpers
• Webhook verification helper

Want to contribute? Open a PR or request a tool.

Links

• Braspag Manual (Pagador)
• Cielo / Braspag Developer Portal
• MCP Dev Brasil
• Landing Page

Enterprise

Need governance, budget limits, and audit trails for agent-driven payments on Braspag? CodeSpar Enterprise adds a policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT