Skip to main content
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

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": "12345-6",
    "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
  }'

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

​
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

StatusDescription
PENDINGCashout created, awaiting processing
PROCESSINGBeing processed by provider
COMPLETEDSuccessfully transferred
PARTIALLY_RETURNEDPart of the cashout amount has been returned
RETURNEDFull cashout amount has been returned
FAILEDTransfer 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"
    }
  ]
}
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"
}

​
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
  }'

​
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