@codespar/mcp-rinne
MCP server for Rinne — Brazilian card acquiring, PIX, banking, and payment infrastructure, covering the full API surface
What is Rinne?
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.
This 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.
Quick Start
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"rinne": {
"command": "npx",
"args": ["-y", "@codespar/mcp-rinne"],
"env": {
"RINNE_API_KEY": "your-api-key",
"RINNE_SANDBOX": "true"
}
}
}
}
Claude Code
claude mcp add rinne -- npx @codespar/mcp-rinne
Cursor / VS Code
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"servers": {
"rinne": {
"command": "npx",
"args": ["-y", "@codespar/mcp-rinne"],
"env": {
"RINNE_API_KEY": "your-api-key",
"RINNE_SANDBOX": "true"
}
}
}
}
Company
| Tool | Purpose |
|---|
get_company | Get the authenticated company (org or merchant, depending on key scope) |
update_company | Update the authenticated company |
Merchants
| Tool | Purpose |
|---|
create_merchant | Create a merchant under your organization (KYC) |
list_merchants | List merchants |
get_merchant | Get merchant details by ID |
update_merchant | Update a merchant |
Affiliations
| Tool | Purpose |
|---|
create_affiliation | Create a merchant account with a payment provider (Rinne, Cappta, Celcoin, ...) |
register_affiliation | Register a gateway-mode affiliation using existing provider credentials |
list_affiliations | List affiliations, org-wide or for one merchant |
get_affiliation | Get a specific affiliation |
Cards on file
| Tool | Purpose |
|---|
store_card | Save a card for reuse in future transactions |
list_cards | List stored cards |
get_card | Get a stored card by ID |
delete_card | Delete a stored card |
3D Secure
| Tool | Purpose |
|---|
create_3ds_session | Create a 3DS authentication session ahead of a transaction |
Transactions
| Tool | Purpose |
|---|
create_transaction | Create a card (raw, stored, or Apple Pay/Google Pay) or PIX transaction |
authenticate_transaction | Complete 3DS for a transaction awaiting authentication |
get_transaction | Get transaction details and status, including refunds |
list_transactions | List transactions, org-wide or for one merchant |
cancel_transaction | Cancel a pending transaction (e.g. unpaid bolepix) |
refund_transaction | Refund a transaction, fully or partially |
cancel_refund | Cancel a refund that hasn't settled yet |
get_transaction_receipt | Get a transaction's receipt (base64 PDF) |
simulate_pay_transaction | Sandbox only — mark a transaction as paid |
PIX (collection keys)
| Tool | Purpose |
|---|
create_pix_collection_key | Create a PIX key the merchant uses to receive payments |
list_pix_collection_keys | List the merchant's PIX collection keys |
Ledger
| Tool | Purpose |
|---|
list_ledger_entries | List ledger entries for the authenticated company |
get_ledger_entry | Get a single ledger entry |
Banking
| Tool | Purpose |
|---|
create_bank_account | Register an external bank account (payout destination) |
update_bank_account | Set a bank account as primary |
register_cashout_pix_key | Register an external PIX key as a payout destination |
get_balance | Get the current balance |
topup_balance | Sandbox only — simulate funding the balance |
get_statement | Get a merchant's balance statement for a date range |
create_internal_transfer | Transfer funds between your org's own bank accounts |
list_judicial_blockages | List court-ordered account freezes affecting balances |
Cashouts
| Tool | Purpose |
|---|
create_cashout | Create a payout to a bank account or PIX key |
list_cashouts | List cashouts |
get_cashout | Get a single cashout |
get_cashout_receipt | Get a cashout's receipt |
Pricing
| Tool | Purpose |
|---|
list_fee_policies | List fee policies (what you charge merchants) |
create_fee_policy | Create a fee policy |
replace_fee_policy | Replace a fee policy in full |
update_fee_policy | Partially update a fee policy |
list_cost_policies | List cost policies (what providers charge you) |
list_mccs | List Merchant Category Codes |
Webhooks
| Tool | Purpose |
|---|
get_webhook_dashboard_url | Get the URL to configure webhook endpoints/events |
System
| Tool | Purpose |
|---|
get_health | Check API health status |
Access management — JWT required
| Tool | Purpose |
|---|
create_api_key | Create an API key (shown once) |
list_api_keys | List API keys (prefix + last 4 only) |
revoke_api_key | Revoke an API key |
create_role | Create a custom role |
list_roles | List roles |
list_permissions | List all available permissions |
get_current_session | Whoami for the JWT session |
Users
| Tool | Purpose |
|---|
create_user | Create a user (merchant scope: x-api-key; org scope: JWT) |
list_users | List users |
update_user | Update a user's name/roles — JWT, org only |
suspend_user | Suspend a user — JWT, org only |
activate_user | Reactivate a user — JWT, org only |
Zipcode — JWT required
| Tool | Purpose |
|---|
lookup_zipcode | Look up a Brazilian address by CEP |
Sandbox
| Tool | Purpose |
|---|
get_sandbox_guide | Return test cards, the amount-based decline rule, and which tools need JWT |
Card data is never sent in the clear
Rinne 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.
In practice, this server is the second half of a checkout: run a rinne-js flow (see rinne-js docs) 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.
Organization vs. merchant scope
Every resource that operates on transactions, cards, 3DS sessions, affiliations, or banking accepts an optional merchant_id:
- Omitted — acts at the organization/self level.
- Provided — acts on that specific merchant (
/v1/merchants/{merchant_id}/...), for an organization managing multiple merchants.
refund_transaction, get_statement, and create_pix_collection_key/list_pix_collection_keys always require merchant_id — they only exist at the merchant level.
Two PIX key resources — don't confuse them
Rinne has two distinct PIX-key resources with similarly-named endpoints:
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).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).
Authentication
Most 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:
| Auth | Used by |
|---|
x-api-key (RINNE_API_KEY) | Everything else — merchants, affiliations, cards, 3DS, transactions, PIX, banking, cashouts, pricing, webhooks, merchant-scoped users |
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 |
This 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.
Sandbox / Testing
Defaults to sandbox (https://api-sandbox.rinne.com.br/core). Set RINNE_SANDBOX=false for production (https://api.rinne.com.br/core).
Sandbox simulation rules
Call get_sandbox_guide for the full JSON, or see below:
Test cards
| Card number | Brand | 3DS |
|---|
5155901222280001 | Mastercard | No |
4012001037141112 | Visa | No |
4242424242424242 | Visa | Challenge |
Outcome by amount
The last two digits of the amount (in cents) determine the result — not the card number:
| Last 2 digits | Result |
|---|
00 | Approved |
51 | Refused — insufficient funds |
05 | Refused — do not honor |
54 | Refused — expired card |
Example: amount: 1051 → REFUSED with code 51.
PIX
Use simulate_pay_transaction (sandbox only) to mark a WAITING_PAYMENT PIX transaction as paid.
Reference: Rinne testing guide
Environment Variables
| Variable | Required | Description |
|---|
RINNE_API_KEY | Yes | API key, sent as x-api-key |
RINNE_SANDBOX | No | Defaults to sandbox; set to "false" for production |
RINNE_EMAIL | No | Login identifier for JWT-gated tools |
RINNE_PASSWORD | No | Login password, paired with RINNE_EMAIL |
RINNE_COMPANY_ID | No | Company to select after login, for multi-company accounts |
Links
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