Rinne API Documentation

Rinne provides banking operations through integrated payment providers: checking balances, viewing statements, managing affiliation PIX keys used to receive transactions, moving funds between your own accounts (internal transfers), and configuring automatic settlement behavior.

Affiliation PIX keys are not the same as external PIX key destinations under /pix-keys, which exist only for cashouts. See Cashouts.

Bank accounts

Merchants can register multiple bank accounts for receiving settlements and processing transfers.

Entity relationships

Creating a bank account

Account numbers must contain only digits. Do not include dashes, spaces, or other special characters.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/bank-accounts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Main operations account",
    "branch_number": "0001",
    "account_number": "123456",
    "account_type": "CHECKING",
    "account_holder_name": "Store Name Ltda.",
    "account_holder_document_number": "16525269000121",
    "ispb": "00000000"
  }'

Nicknames

nickname is an optional user-defined label (1–100 characters) for a company bank account. It never leaves Rinne—the provider is not given the nickname—and it exists purely to help you distinguish accounts when a company holds several withdrawal accounts, even at the same bank. Unlike the other bank-account fields, nickname stays editable even on accounts with successful or ongoing cashouts. Nickname-only PATCH requests bypass the “no updates once used” guard, and you can clear the label by sending "nickname": null.

Account types

CHECKING: Checking account (conta corrente)
SAVINGS: Savings account (poupança)
SALARY: Salary account (conta salário)
PAYMENT: Payment account (conta pagamento)

Primary account

Set one account as primary for default settlement operations:

curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/bank-accounts/ACCOUNT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primary": true
  }'

Adding balance in sandbox

In the sandbox environment, you can add balance to accounts for testing purposes.

Add balance to a merchant account

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "amount": 10000
  }'

Add balance to an organization account

Use this endpoint when you need to add balance directly to the authenticated organization’s own bank account. No merchantId parameter is needed.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/banking/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "amount": 10000
  }'

Only companies with type ORGANIZATION can use the /v1/banking/balance POST endpoint.

Both endpoints return a status and request ID:

{
  "request_id": "f9b978a6-ab7e-4460-997d-1234567890ab",
  "status": "CONFIRMED"
}

Checking balance

Get the current balance for a merchant’s account:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/balance?provider=CELCOIN" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "company_id": "merchant-123",
  "provider": "CELCOIN",
  "balance": 150000,
  "blocked_balance": 5000,
  "total_balance": 155000,
  "currency": "BRL"
}

balance: Available balance (in cents)
blocked_balance: Temporarily blocked funds
total_balance: Total balance including blocked funds

Account statements

Retrieve transaction history for a merchant’s account:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/statement?provider=CELCOIN&date_from=2025-01-01T00:00:00Z&date_to=2025-01-07T23:59:59Z" \
  -H "x-api-key: YOUR_API_KEY"

Providers enforce a maximum 7-day date range for statements.

Response includes all account movements:

{
  "items": [
    {
      "movement_id": "mov-123",
      "occurred_at": "2025-01-05T10:30:00Z",
      "amount": 10000,
      "type": "CREDIT",
      "movement_type": "PIXPAYMENTIN",
      "balance_after": 150000
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 25,
  "total_pages": 1
}

Internal transfers

Transfer funds between bank accounts within the same provider (organization only).

curl -X POST https://api-sandbox.rinne.com.br/core/v1/banking/internal-transfers \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "transfer-123",
    "origin_bank_account_id": "account-1",
    "destination_bank_account_id": "account-2",
    "amount": 25000,
    "metadata": {
      "transfer_reason": "settlement",
      "custom_field": "value"
    }
  }'

Internal transfer requirements

Both accounts must have active affiliations
Accounts must be with the same provider
Only organizations can create internal transfers
Origin and destination must be different accounts

Automatic transfers

Configure automatic settlement transfers for merchants:

{
  "transfer_configurations": {
    "automatic_transfer_enabled": true,
    "transfer_frequency": "DAILY",
    "transfer_date": 1,
    "rail": "PIX"
  }
}

DAILY: Transfer every day
WEEKLY: Transfer on specified day of week
MONTHLY: Transfer on specified day of month (1-28)

Automatic transfers work like regular cashouts, but Rinne creates them for you on schedule instead of you calling the API. Money goes to the company’s active primary bank account if one is set up; if not, it goes to the active primary PIX key instead. If neither is set up yet, the current cycle is skipped; no transfer is created. A later scheduled cycle can run once an active primary destination exists. See Cashouts → Automatic cashouts for more detail.

Judicial blockages

Courts can order funds in a bank account to be frozen (blocked) or unfrozen (released). When this happens to an affiliation bank account, the payment provider applies the order and notifies Rinne, which records each movement. You can list these movements through the API to understand why funds are unavailable and to reconcile blocked amounts. Each judicial blockage record represents a single movement:

BLOCK: Funds were frozen by court order.
RELEASE: Previously blocked funds were unblocked.

Records are created automatically from provider notifications—there is no write API. The list is append-only: a block and its later release appear as two separate records. When a movement is recorded, Rinne also sends a judicial-blockage.created webhook. Account-level restriction changes (REGULAR ↔ JUDICIAL_BLOCK) arrive separately as affiliation-bank-account.operational-status-changed. See Webhooks for payload details and handler examples.

While an account is under a judicial block, the affected funds are frozen at the provider and cannot be withdrawn or transferred.

Listing judicial blockages

List movements for the authenticated organization’s own accounts (requires the banking.list permission):

curl "https://api-sandbox.rinne.com.br/core/v1/banking/judicial-blockages?type=BLOCK&sort=-occurred_at" \
  -H "x-api-key: YOUR_API_KEY"

Or for a specific merchant that belongs to your organization (requires the merchant.banking.list permission):

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/1c9f4a67-3b2e-4d80-9f15-6a8c0d72e394/banking/judicial-blockages" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "b2f6a1de-4c39-4f8e-9a71-2d5c8e0f3b64",
      "affiliation_bank_account_id": "a41c7b02-95d3-4e6f-8c2a-1f0b9d67e358",
      "provider_movement_id": "mov_123456789",
      "type": "BLOCK",
      "amount": 250000,
      "description": "Bloqueio judicial",
      "process_number": "0012345-67.2026.8.26.0100",
      "author_name": "John Doe",
      "court_name": "1ª Vara Cível de São Paulo",
      "occurred_at": "2026-07-10T14:22:00Z",
      "created_at": "2026-07-10T14:22:05Z",
      "updated_at": "2026-07-10T14:22:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

amount: Movement amount in cents
process_number, author_name, court_name: Judicial process details, when provided by the court order (may be null)
occurred_at: When the movement occurred at the provider

Filtering and sorting

Both endpoints support the same query parameters:

Parameter	Description
`type`	Filter by movement type: `BLOCK`, `RELEASE`, or both (comma-separated)
`affiliation_bank_account_id`	Filter by a specific affiliation bank account
`process_number`	Filter by judicial process number
`occurred_at_from` / `occurred_at_to`	Filter by occurrence date range (ISO 8601)
`sort`	Sort by `occurred_at`, `created_at`, or `amount`; prefix with `-` for descending (e.g. `-occurred_at`)
`page` / `limit`	Pagination (default page 1, limit 20, max 100)

Getting started

Core concepts

Guides

Banking

Bank accounts

Entity relationships

Creating a bank account

Nicknames

Account types

Primary account

Adding balance in sandbox

Add balance to a merchant account

Add balance to an organization account

Checking balance

Account statements

Internal transfers

Internal transfer requirements

Automatic transfers

Judicial blockages

Listing judicial blockages

Filtering and sorting

Next steps

PIX Payments

Pricing

​Bank accounts

​Entity relationships

​Creating a bank account

​Nicknames

​Account types

​Primary account

​Adding balance in sandbox

​Add balance to a merchant account

​Add balance to an organization account

​Checking balance

​Account statements

​Internal transfers

​Internal transfer requirements

​Automatic transfers

​Judicial blockages

​Listing judicial blockages

​Filtering and sorting

​Next steps

PIX Payments

Pricing

Bank accounts

Entity relationships

Creating a bank account

Nicknames

Account types

Primary account

Adding balance in sandbox

Add balance to a merchant account

Add balance to an organization account

Checking balance

Account statements

Internal transfers

Internal transfer requirements

Automatic transfers

Judicial blockages

Listing judicial blockages

Filtering and sorting

Next steps