# mcp-pagbrasil

Wires three PagBrasil tools into your agent: create an order, check its status, issue a refund. Useful when your store sells into Brazil and takes Pix or boleto.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/payments/pagbrasil
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-pagbrasil

## What it does

The server talks to PagBrasil, an acquirer that handles cross-border sales into Brazil. You get three tools. `create_order` opens an order or payment request (pix, boleto, creditcard); `get_order` returns where that order stands now; `refund_order` sends money back on a settled payment. Pix replies include `pix_code` and `pix_image`, boleto replies the bar code plus a PDF link.

The transport is unusual. PagBrasil wants form-urlencoded input and answers in XML, so the server hands the raw XML back to the agent under `xml` and nothing gets dropped on the way. Merchant token and secret phrase ride in the request body, not in an auth header; the server fills them from `PAGBRASIL_PBTOKEN` and `PAGBRASIL_SECRET`. Both are required and both come from the PagBrasil dashboard.

A valid `customer_taxid` is mandatory — a real CPF or CNPJ. The agent has to ask for it, inventing one breaks the request. `order_number` stays unique per taxpayer: repeat it with the same taxid and the call is an idempotent no-op, change the taxid and you get `Duplicated order`. Amounts go in `amount_brl` as a string in major units, so `'125.00'` means R$ 125,00. Requests hit `https://sandbox.pagbrasil.com/api` by default; production hosts are issued per merchant once the Payment Service Agreement is signed, and you point `PAGBRASIL_BASE_URL` at yours.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `PAGBRASIL_PBTOKEN`, `PAGBRASIL_SECRET`, `PAGBRASIL_BASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> --env PAGBRASIL_SECRET=<PAGBRASIL_SECRET> --env PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> --transport stdio pagbrasil -- npx -y @codespar/mcp-pagbrasil
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add pagbrasil --env PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> --env PAGBRASIL_SECRET=<PAGBRASIL_SECRET> --env PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> -- npx -y @codespar/mcp-pagbrasil
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "pagbrasil": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-pagbrasil"
            ],
            "env": {
                "PAGBRASIL_PBTOKEN": "<PAGBRASIL_PBTOKEN>",
                "PAGBRASIL_SECRET": "<PAGBRASIL_SECRET>",
                "PAGBRASIL_BASE_URL": "<PAGBRASIL_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "pagbrasil": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-pagbrasil"
            ],
            "env": {
                "PAGBRASIL_PBTOKEN": "<PAGBRASIL_PBTOKEN>",
                "PAGBRASIL_SECRET": "<PAGBRASIL_SECRET>",
                "PAGBRASIL_BASE_URL": "<PAGBRASIL_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> -e PAGBRASIL_SECRET=<PAGBRASIL_SECRET> -e PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> pagbrasil npx -y @codespar/mcp-pagbrasil
```
Replace <…> with your own values

## When to use it
- charge a Brazilian buyer with Pix and show the QR code
- issue a boleto and hand over the bar code and PDF
- poll an order until the payment settles
- refund a settled order in part or in full
- take a local card payment with installments

## Example prompts
- Create an order for 249.90 for the CPF I'm about to paste and give me the Pix code.
- Check order 1042 — has the payment landed yet?
- Refund 50.00 on order 1042, partial amount.

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [OpenWork MCP Gateway](https://affpapa.org/en/nevibecode/mcp/openwork-mcp-gateway.md) — MCP server · ★ 24242
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9366
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7506

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md