{"_id":"@codespar/mcp-rinne","name":"@codespar/mcp-rinne","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@codespar/mcp-rinne","version":"0.1.0","description":"MCP server for Rinne — Brazilian card acquiring, PIX, banking, and payment infrastructure API","type":"module","main":"./dist/index.js","bin":{"mcp-rinne":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.8.0"},"keywords":["mcp","rinne","payments","card","acquiring","3ds","brazil"],"license":"MIT","mcpName":"io.github.codespar/mcp-rinne","_id":"@codespar/mcp-rinne@0.1.0","gitHead":"1e32748df2e0a8d2c99d6da68177374e9a39753e","types":"./dist/index.d.ts","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-nT9+LW0ChdwXwTcKrFiFHmcr8/u00ASeoxHtz13kcNTcOvpZnUQ8de7XpSGYud8StXHVlQhNdm+Ic5Vf3HCltw==","shasum":"2c00cbd4bb4291224a6b13e2ebf3220adb3121b7","tarball":"https://registry.npmjs.org/@codespar/mcp-rinne/-/mcp-rinne-0.1.0.tgz","fileCount":6,"unpackedSize":141146,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDbzTMOf+hY7gTJXtUeDhjbsNLTO1HcxdVtWv5K1BHr0AIgFIKYajYzezC1KVWVFQAmuresCzXYwFy5zjIUkv5EJLU="}]},"_npmUser":{"name":"codespar-npm","email":"fabiano@codespar.dev"},"directories":{},"maintainers":[{"name":"codespar-npm","email":"fabiano@codespar.dev"},{"name":"dangazineu","email":"daniel.gazineu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-rinne_0.1.0_1786301115737_0.140115079555313"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-09T18:45:15.549Z","0.1.0":"2026-08-09T18:45:15.893Z","modified":"2026-08-09T18:45:16.228Z"},"maintainers":[{"name":"codespar-npm","email":"fabiano@codespar.dev"},{"name":"dangazineu","email":"daniel.gazineu@gmail.com"}],"description":"MCP server for Rinne — Brazilian card acquiring, PIX, banking, and payment infrastructure API","keywords":["mcp","rinne","payments","card","acquiring","3ds","brazil"],"license":"MIT","readme":"# @codespar/mcp-rinne\n\n> MCP server for **Rinne** — Brazilian card acquiring, PIX, banking, and payment infrastructure, covering the full API surface\n\n[![npm](https://img.shields.io/npm/v/@codespar/mcp-rinne)](https://www.npmjs.com/package/@codespar/mcp-rinne)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## What is Rinne?\n\n**Rinne** is a Brazilian payment infrastructure API. It runs a B2B2B model: your **Organization** manages any number of **Merchants**, each merchant onboards via KYC and connects to a payment provider (Rinne itself, Cappta, Celcoin, ...) through an **Affiliation**, and everything downstream flows through that affiliation — card and PIX transactions, cards-on-file, 3D Secure, cashouts/payouts, ledger, and pricing.\n\nThis MCP server wraps the entire Rinne REST API — not just card acquiring — so AI agents can manage merchants, run transactions, move money, and administer access in sandbox or production.\n\n## Quick Start\n\n### Claude Desktop\n\nAdd to `~/.config/claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rinne\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@codespar/mcp-rinne\"],\n      \"env\": {\n        \"RINNE_API_KEY\": \"your-api-key\",\n        \"RINNE_SANDBOX\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add rinne -- npx @codespar/mcp-rinne\n```\n\n### Cursor / VS Code\n\nAdd to `.cursor/mcp.json` or `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"rinne\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@codespar/mcp-rinne\"],\n      \"env\": {\n        \"RINNE_API_KEY\": \"your-api-key\",\n        \"RINNE_SANDBOX\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## Tools (62)\n\n### Company\n\n| Tool | Purpose |\n|---|---|\n| `get_company` | Get the authenticated company (org or merchant, depending on key scope) |\n| `update_company` | Update the authenticated company |\n\n### Merchants\n\n| Tool | Purpose |\n|---|---|\n| `create_merchant` | Create a merchant under your organization (KYC) |\n| `list_merchants` | List merchants |\n| `get_merchant` | Get merchant details by ID |\n| `update_merchant` | Update a merchant |\n\n### Affiliations\n\n| Tool | Purpose |\n|---|---|\n| `create_affiliation` | Create a merchant account with a payment provider (Rinne, Cappta, Celcoin, ...) |\n| `register_affiliation` | Register a gateway-mode affiliation using existing provider credentials |\n| `list_affiliations` | List affiliations, org-wide or for one merchant |\n| `get_affiliation` | Get a specific affiliation |\n\n### Cards on file\n\n| Tool | Purpose |\n|---|---|\n| `store_card` | Save a card for reuse in future transactions |\n| `list_cards` | List stored cards |\n| `get_card` | Get a stored card by ID |\n| `delete_card` | Delete a stored card |\n\n### 3D Secure\n\n| Tool | Purpose |\n|---|---|\n| `create_3ds_session` | Create a 3DS authentication session ahead of a transaction |\n\n### Transactions\n\n| Tool | Purpose |\n|---|---|\n| `create_transaction` | Create a card (raw, stored, or Apple Pay/Google Pay) or PIX transaction |\n| `authenticate_transaction` | Complete 3DS for a transaction awaiting authentication |\n| `get_transaction` | Get transaction details and status, including refunds |\n| `list_transactions` | List transactions, org-wide or for one merchant |\n| `cancel_transaction` | Cancel a pending transaction (e.g. unpaid bolepix) |\n| `refund_transaction` | Refund a transaction, fully or partially |\n| `cancel_refund` | Cancel a refund that hasn't settled yet |\n| `get_transaction_receipt` | Get a transaction's receipt (base64 PDF) |\n| `simulate_pay_transaction` | **Sandbox only** — mark a transaction as paid |\n\n### PIX (collection keys)\n\n| Tool | Purpose |\n|---|---|\n| `create_pix_collection_key` | Create a PIX key the merchant uses to *receive* payments |\n| `list_pix_collection_keys` | List the merchant's PIX collection keys |\n\n### Ledger\n\n| Tool | Purpose |\n|---|---|\n| `list_ledger_entries` | List ledger entries for the authenticated company |\n| `get_ledger_entry` | Get a single ledger entry |\n\n### Banking\n\n| Tool | Purpose |\n|---|---|\n| `create_bank_account` | Register an external bank account (payout destination) |\n| `update_bank_account` | Set a bank account as primary |\n| `register_cashout_pix_key` | Register an external PIX key as a *payout* destination |\n| `get_balance` | Get the current balance |\n| `topup_balance` | **Sandbox only** — simulate funding the balance |\n| `get_statement` | Get a merchant's balance statement for a date range |\n| `create_internal_transfer` | Transfer funds between your org's own bank accounts |\n| `list_judicial_blockages` | List court-ordered account freezes affecting balances |\n\n### Cashouts\n\n| Tool | Purpose |\n|---|---|\n| `create_cashout` | Create a payout to a bank account or PIX key |\n| `list_cashouts` | List cashouts |\n| `get_cashout` | Get a single cashout |\n| `get_cashout_receipt` | Get a cashout's receipt |\n\n### Pricing\n\n| Tool | Purpose |\n|---|---|\n| `list_fee_policies` | List fee policies (what you charge merchants) |\n| `create_fee_policy` | Create a fee policy |\n| `replace_fee_policy` | Replace a fee policy in full |\n| `update_fee_policy` | Partially update a fee policy |\n| `list_cost_policies` | List cost policies (what providers charge you) |\n| `list_mccs` | List Merchant Category Codes |\n\n### Webhooks\n\n| Tool | Purpose |\n|---|---|\n| `get_webhook_dashboard_url` | Get the URL to configure webhook endpoints/events |\n\n### System\n\n| Tool | Purpose |\n|---|---|\n| `get_health` | Check API health status |\n\n### Access management — JWT required\n\n| Tool | Purpose |\n|---|---|\n| `create_api_key` | Create an API key (shown once) |\n| `list_api_keys` | List API keys (prefix + last 4 only) |\n| `revoke_api_key` | Revoke an API key |\n| `create_role` | Create a custom role |\n| `list_roles` | List roles |\n| `list_permissions` | List all available permissions |\n| `get_current_session` | Whoami for the JWT session |\n\n### Users\n\n| Tool | Purpose |\n|---|---|\n| `create_user` | Create a user (merchant scope: x-api-key; org scope: JWT) |\n| `list_users` | List users |\n| `update_user` | Update a user's name/roles — **JWT, org only** |\n| `suspend_user` | Suspend a user — **JWT, org only** |\n| `activate_user` | Reactivate a user — **JWT, org only** |\n\n### Zipcode — JWT required\n\n| Tool | Purpose |\n|---|---|\n| `lookup_zipcode` | Look up a Brazilian address by CEP |\n\n### Sandbox\n\n| Tool | Purpose |\n|---|---|\n| `get_sandbox_guide` | Return test cards, the amount-based decline rule, and which tools need JWT |\n\n## Card data is never sent in the clear\n\nRinne does not accept a raw card number or CVV over this API. Every `number`/`cvv` field (and, for Apple Pay/Google Pay, `network_token`/`cryptogram`) must already be an encrypted token (`\"ev:...\"`) produced by the **rinne-js Card/Wallet Element** running in a browser — a raw PAN/CVV is rejected with `400 VALIDATION_ERROR`, and there is no server-side encryption path.\n\nIn practice, this server is the second half of a checkout: run a rinne-js flow (see [rinne-js docs](https://docs.rinne.com.br/rinne-js)) to collect and encrypt the card client-side, then hand the resulting token to `store_card` or `create_transaction` here to finish the operation. Alternatively, use `card_id` on `create_transaction` to charge a card already saved via `store_card`.\n\n## Organization vs. merchant scope\n\nEvery resource that operates on transactions, cards, 3DS sessions, affiliations, or banking accepts an optional `merchant_id`:\n\n- **Omitted** — acts at the organization/self level.\n- **Provided** — acts on that specific merchant (`/v1/merchants/{merchant_id}/...`), for an organization managing multiple merchants.\n\n`refund_transaction`, `get_statement`, and `create_pix_collection_key`/`list_pix_collection_keys` always require `merchant_id` — they only exist at the merchant level.\n\n## Two PIX key resources — don't confuse them\n\nRinne has two distinct PIX-key resources with similarly-named endpoints:\n\n- **`create_pix_collection_key`** (`/v1/merchants/{id}/pix/keys`) — a key the merchant uses to *receive* PIX payments, tied to a provider affiliation (`provider`, `key_type`).\n- **`register_cashout_pix_key`** (`/v1/merchants/{id}/pix-keys` or `/v1/companies/me/pix-keys`) — an *external* key registered as a *payout* destination for cashouts (`key`, `primary`).\n\n## Authentication\n\nMost of the API uses `x-api-key`, but Rinne's access-management surface deliberately rejects it — a leaked API key must not be able to create other keys, roles, or users. Those tools need a JWT session instead:\n\n| Auth | Used by |\n|---|---|\n| `x-api-key` (`RINNE_API_KEY`) | Everything else — merchants, affiliations, cards, 3DS, transactions, PIX, banking, cashouts, pricing, webhooks, merchant-scoped users |\n| JWT (`RINNE_EMAIL` + `RINNE_PASSWORD`) | `create_api_key`, `list_api_keys`, `revoke_api_key`, `create_role`, `list_roles`, `list_permissions`, `get_current_session`, `lookup_zipcode`, and org-scoped `create_user`/`list_users`/`update_user`/`suspend_user`/`activate_user` |\n\nThis server logs in lazily on the first JWT-gated tool call and caches the token, re-logging-in once on a `401`. If `RINNE_COMPANY_ID` is set, it selects that company right after login (for accounts with access to multiple companies). If `RINNE_EMAIL`/`RINNE_PASSWORD` aren't set, JWT-gated tools return a clear error instead of failing silently — the rest of the server works fine without them.\n\n## Sandbox / Testing\n\nDefaults to sandbox (`https://api-sandbox.rinne.com.br/core`). Set `RINNE_SANDBOX=false` for production (`https://api.rinne.com.br/core`).\n\n### Sandbox simulation rules\n\nCall `get_sandbox_guide` for the full JSON, or see below:\n\n#### Test cards\n\n| Card number | Brand | 3DS |\n|---|---|---|\n| `5155901222280001` | Mastercard | No |\n| `4012001037141112` | Visa | No |\n| `4242424242424242` | Visa | Challenge |\n\n#### Outcome by amount\n\nThe **last two digits of the amount (in cents)** determine the result — not the card number:\n\n| Last 2 digits | Result |\n|---|---|\n| `00` | Approved |\n| `51` | Refused — insufficient funds |\n| `05` | Refused — do not honor |\n| `54` | Refused — expired card |\n\nExample: `amount: 1051` → `REFUSED` with code `51`.\n\n#### PIX\n\nUse `simulate_pay_transaction` (sandbox only) to mark a `WAITING_PAYMENT` PIX transaction as paid.\n\nReference: [Rinne testing guide](https://docs.rinne.com.br/guides/testing)\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `RINNE_API_KEY` | Yes | API key, sent as `x-api-key` |\n| `RINNE_SANDBOX` | No | Defaults to sandbox; set to `\"false\"` for production |\n| `RINNE_EMAIL` | No | Login identifier for JWT-gated tools |\n| `RINNE_PASSWORD` | No | Login password, paired with `RINNE_EMAIL` |\n| `RINNE_COMPANY_ID` | No | Company to select after login, for multi-company accounts |\n\n## Links\n\n- [Rinne Documentation](https://docs.rinne.com.br)\n- [rinne-js SDK](https://docs.rinne.com.br/rinne-js)\n- [MCP Dev LATAM](https://github.com/codespar/mcp-dev-latam)\n- [Landing Page](https://codespar.dev/mcp)\n\n## Enterprise\n\nNeed governance, budget limits, and audit trails for agent payments? [CodeSpar Enterprise](https://codespar.dev/enterprise) adds policy engine, payment routing, and compliance templates on top of these MCP servers.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f3d74d2516684e75f143f3a3eea1d14b"}