> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/concepts/cashouts).
## Bank accounts
Merchants can register multiple bank accounts for receiving settlements and processing transfers.
### Entity relationships
```mermaid theme={null}
graph LR
M[Merchant] -->|has many| BA[Bank Accounts]
BA -->|linked to| A[Affiliation]
BA -->|receives| S[Settlements]
BA -->|source for| CO[Cashouts]
BA -->|used in| IT[Internal Transfers]
M -->|checks| B[Balance]
M -->|views| ST[Statement]
style M fill:#7B89FF,color:#fff
style BA fill:#5B68EB,color:#fff
style A fill:#4A56D9,color:#fff
style S fill:#7B89FF,color:#fff
style CO fill:#5B68EB,color:#fff
style IT fill:#4A56D9,color:#fff
style B fill:#7B89FF,color:#fff
style ST fill:#5B68EB,color:#fff
```
### Creating a bank account
Account numbers must contain only digits. Do not include dashes, spaces, or other special characters.
```bash theme={null}
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:
```bash theme={null}
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
```bash theme={null}
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.
```bash theme={null}
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:
```json theme={null}
{
"request_id": "f9b978a6-ab7e-4460-997d-1234567890ab",
"status": "CONFIRMED"
}
```
## Checking balance
Get the current balance for a merchant's account:
```bash theme={null}
curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/balance?provider=CELCOIN" \
-H "x-api-key: YOUR_API_KEY"
```
Response:
```json theme={null}
{
"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:
```bash theme={null}
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:
```json theme={null}
{
"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).
```bash theme={null}
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:
```json theme={null}
{
"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
Process instant PIX payments
Understand fee and cost policies