Rinne API Documentation

Rinne provides banking operations through integrated payment providers, allowing merchants to check balances, view statements, and process transfers.

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 '{
    "branch_number": "0001",
    "account_number": "123456",
    "account_type": "CHECKING",
    "account_holder_name": "Store Name Ltda.",
    "account_holder_document_number": "16525269000121",
    "ispb": "00000000"
  }'

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
}

Cashouts

Transfer funds from a merchant’s provider account to an external bank account.

Cashout flow

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "cashout-123",
    "origin_bank_account_id": "affiliated-account-id",
    "destination_bank_account_id": "external-account-id",
    "amount": 50000,
    "currency": "BRL",
    "method": "PIX",
    "metadata": {
      "order_id": "order-123",
      "custom_field": "value"
    }
  }'

Cashout requirements

Origin account must have an active affiliation
Destination account must belong to the merchant
Account holder documents must match
Sufficient balance in origin account
Currency defaults to BRL (currently the only supported currency)

Cashout status

Status	Description
`PENDING`	Cashout created, awaiting processing
`PROCESSING`	Being processed by provider
`COMPLETED`	Successfully transferred
`PARTIALLY_RETURNED`	Part of the cashout amount has been returned
`RETURNED`	Full cashout amount has been returned
`FAILED`	Transfer failed

Cashout returns

Cashouts can be partially or fully returned by the banking provider. When a return occurs:

The cashout status transitions to PARTIALLY_RETURNED or RETURNED
Each return is tracked individually with amount, reason, and timestamp
Multiple partial returns can accumulate until the full amount is returned

{
  "id": "cashout-123",
  "status": "PARTIALLY_RETURNED",
  "amount": 50000,
  "currency": "BRL",
  "returned_amount": 15000,
  "latest_return_at": "2025-01-06T14:30:00Z",
  "pix_returns": [
    {
      "id": "return-1",
      "amount": 15000,
      "reason": "CUSTOMER_REQUEST",
      "return_identification": "D12345678901234567890",
      "created_at": "2025-01-06T14:30:00Z"
    }
  ],
  "metadata": {
    "order_id": "order-123",
    "custom_field": "value"
  }
}

Return reasons:

BANKING_ERROR: Banking system error
FRAUD: Fraudulent transaction
CUSTOMER_REQUEST: Customer requested return
PIX_WITHDRAWAL_OR_CHANGE_ERROR: PIX withdrawal or change error

Cashout pricing

Cashouts incur fees and costs based on pricing policies:

{
  "amount": 50000,
  "currency": "BRL",
  "fee": 350,
  "cost": 300,
  "fee_policy_id": "fee-policy-123",
  "cost_policy_id": "cost-policy-456"
}

Cashout receipts

Generate a PDF receipt for completed cashouts. Receipts are available for cashouts with status COMPLETED, PARTIALLY_RETURNED, or RETURNED that have an end-to-end ID.

curl "https://api-sandbox.rinne.com.br/core/v1/banking/cashouts/CASHOUT_ID/receipt" \
  -H "x-api-key: YOUR_API_KEY"

Response includes cashout details, payer/receiver information, and a base64-encoded PDF:

{
  "cashout": {
    "id": "cashout-123",
    "amount": 50100,
    "fee": 100,
    "net_amount": 50000,
    "currency": "BRL",
    "status": "COMPLETED",
    "method": "PIX",
    "end_to_end_id": "E13935893202601271529YV9B1m6o2Ih",
    "created_at": "2025-01-27T12:29:21.000Z"
  },
  "payer": {
    "name": "Company Name Ltda",
    "document": "12.345.678/0001-90",
    "bank_name": "CELCOIN IP S.A.",
    "ispb": "13935893",
    "branch": "0001",
    "account": "123456"
  },
  "receiver": {
    "name": "John Doe",
    "document": "***.456.789-**",
    "bank_name": "BCO SANTANDER (BRASIL) S.A.",
    "ispb": "90400888",
    "branch": "2305",
    "account": "010227424"
  },
  "pdf_file_base64": "JVBERi0xLjQK..."
}

CPF documents are masked for privacy (e.g., ***.456.789-**), while CNPJ documents are shown in full.

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)

Next steps

PIX Payments

Process instant PIX payments

Pricing

Understand fee and cost policies

Getting started

Core concepts

Guides

Banking

Bank accounts

Entity relationships

Creating a bank account

Account types

Primary account

Adding balance in sandbox

Add balance to a merchant account

Add balance to an organization account

Checking balance

Account statements

Cashouts

Cashout flow

Cashout requirements

Cashout status

Cashout returns

Cashout pricing

Cashout receipts

Internal transfers

Internal transfer requirements

Automatic transfers

Next steps

PIX Payments

Pricing

Getting started

Core concepts

Guides

​Bank accounts

​Entity relationships

​Creating a bank account

​Account types

​Primary account

​Adding balance in sandbox

​Add balance to a merchant account

​Add balance to an organization account

​Checking balance

​Account statements

​Cashouts

​Cashout flow

​Cashout requirements

​Cashout status

​Cashout returns

​Cashout pricing

​Cashout receipts

​Internal transfers

​Internal transfer requirements

​Automatic transfers

​Next steps

PIX Payments

Pricing

Bank accounts

Entity relationships

Creating a bank account

Account types

Primary account

Adding balance in sandbox

Add balance to a merchant account

Add balance to an organization account

Checking balance

Account statements

Cashouts

Cashout flow

Cashout requirements

Cashout status

Cashout returns

Cashout pricing

Cashout receipts

Internal transfers

Internal transfer requirements

Automatic transfers

Next steps