Banking

Manage balances, review statements, receive PIX payments, perform internal transfers, and configure automatic settlements

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 '{
    "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
}

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