> ## 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.
# Organizations and merchants
> Understand the company hierarchy in Rinne's B2B2B model
Rinne uses a hierarchical company structure that enables B2B2B marketplace functionality. This model allows organizations to manage multiple merchants with complete data isolation and custom configurations.
## Company types
### Organizations
Organizations are parent companies that manage multiple merchants. They have the ability to:
* Create and manage merchants
* View aggregated data across all merchants
* Configure pricing policies for merchants
* Access consolidated transaction reports
* Manage users and permissions across the hierarchy
Organizations are created by Rinne administrators and receive an API key for authentication.
### Merchants
Merchants are child companies that belong to an organization. They can:
* Process payment transactions
* Manage external bank accounts and PIX destinations for cashouts ([Cashouts](/concepts/cashouts))
* Register affiliation PIX keys for receiving payments ([PIX Payments](/guides/pix-payments#pix-key-management-for-receiving-payments))
* Access their own transaction history
* Configure transfer settings
Merchants are created by organizations through the API and automatically inherit the organization's pricing policies.
## Company hierarchy
The following diagram illustrates the B2B2B hierarchical structure:
```mermaid theme={null}
graph TD
O[Organization
Parent Company] --> M1[Merchant A]
O --> M2[Merchant B]
O --> M3[Merchant C]
M1 -.-> T1[Transactions]
M1 -.-> B1[Bank Accounts]
M1 -.-> A1[Affiliations]
M2 -.-> T2[Transactions]
M2 -.-> B2[Bank Accounts]
M2 -.-> A2[Affiliations]
M3 -.-> T3[Transactions]
M3 -.-> B3[Bank Accounts]
M3 -.-> A3[Affiliations]
style O fill:#5B68EB,color:#fff
style M1 fill:#7B89FF,color:#fff
style M2 fill:#7B89FF,color:#fff
style M3 fill:#7B89FF,color:#fff
```
Each merchant operates independently with:
* Unique API key
* Isolated transaction data
* Separate bank accounts
* Individual provider affiliations
* Custom transfer configurations
## Key differences
| Feature | Organization | Merchant |
| ---------------------- | ------------ | -------- |
| Create merchants | ✅ Yes | ❌ No |
| Process transactions | ✅ Yes | ✅ Yes |
| View all merchant data | ✅ Yes | ❌ No |
| Set pricing policies | ✅ Yes | ❌ No |
| Manage affiliations | ✅ Yes | ✅ Yes |
## Authentication scope
When you authenticate with an API key, the scope depends on the company type:
**Organization API key**: Access to all merchants and aggregated data
```bash theme={null}
# List all merchants
GET /v1/merchants
# View all merchant transactions
GET /v1/merchants/transactions
```
**Merchant API key**: Access only to own data
```bash theme={null}
# View own transactions
GET /v1/transactions
# Manage own affiliations
GET /v1/affiliations
```
## Creating merchants
Organizations create merchants using the `/v1/merchants` endpoint:
```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants \
-H "x-api-key: YOUR_ORG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"full_name": "Store Name Ltda.",
"document_number": "16525269000121",
"document_type": "CNPJ",
"document_tax_type": "PJ",
"mcc": "5912",
"contact": {
"first_name": "John",
"last_name": "Silva",
"phone": "+5511999999991",
"email": "contact@store.com",
"mother_name": "Maria Silva",
"birth_date": "15-08-1990",
"document_number": "81146431023",
"politically_exposed": false,
"declared_income": 15000,
"occupation": "ADMINISTRATOR_MANAGER",
"net_worth": 100000,
"address": { ... }
},
"address": { ... },
"transfer_configurations": { ... },
"declared_revenue": 500000
}'
```
The merchant is automatically linked to your organization and inherits your pricing policies.
## Document requirements
### CNPJ companies (legal entities)
* Document must be exactly 14 digits
* Tax type must be one of: `PJ`, `MEI`, or `ME`
* Contact document (CPF) can be different from company document
* `declared_revenue` is required
### CPF companies (individuals)
* Document must be exactly 11 digits
* Tax type must be `PF`
* Contact document must match company document
### Updating document\_tax\_type
The `document_tax_type` field can be updated after company creation, but only when the company has no affiliations in non-final statuses. This means:
* **Allowed**: Company has no affiliations, or only `FAILED`/`REJECTED` affiliations
* **Blocked**: Company has affiliations in `PENDING`, `IN_PROGRESS`, `ACTIVE`, or other non-final statuses
When updating, the same document type compatibility rules apply:
* CPF companies can only have `PF` tax type
* CNPJ companies can have `PJ`, `MEI`, or `ME` tax type
If you need to change the tax type for a company with active affiliations, you must wait for those affiliations to reach a final status (FAILED or REJECTED) or create a new company.
## Financial information
Financial information fields are required for provider affiliation and regulatory compliance. All monetary values are stored as whole reais (BRL), not cents.
### Contact financial fields
| Field | Type | Description |
| ----------------- | ------- | ----------------------------------------------------------- |
| `declared_income` | integer | Monthly income in whole reais. Default: 5000 (R\$ 5.000) |
| `occupation` | string | Contact's occupation. Default: `OTHER` |
| `net_worth` | integer | Total net worth in whole reais. Default: 50000 (R\$ 50.000) |
### Company financial fields
| Field | Type | Description |
| ------------------ | ------- | --------------------------------------------------------------------------------------- |
| `declared_revenue` | integer | Annual revenue in whole reais. Default: 50000 (R\$ 50.000). Required for CNPJ companies |
### Celcoin provider translation
When affiliating a merchant with the Celcoin provider, financial values are translated into income/revenue tiers. Understanding these ranges helps you provide accurate financial information.
Monthly income values are mapped to the following tiers:
| Value Range (reais) | Description |
| ------------------- | --------------------- |
| ≤ 5,000 | Very low income tier |
| 5,001 - 10,000 | Low income tier |
| 10,001 - 30,000 | Medium income tier |
| 30,001 - 100,000 | High income tier |
| > 100,000 | Very high income tier |
Total net worth values are mapped to the following tiers:
| Value Range (reais) | Description |
| --------------------- | ------------------------ |
| ≤ 50,000 | Very low net worth tier |
| 50,001 - 200,000 | Low net worth tier |
| 200,001 - 1,000,000 | Medium net worth tier |
| 1,000,001 - 5,000,000 | High net worth tier |
| > 5,000,000 | Very high net worth tier |
Annual revenue values are mapped to Brazilian company size classifications:
| Value Range (reais) | Description |
| ---------------------- | ------------------------------ |
| ≤ 81,000 | MEI |
| 81,001 - 360,000 | Microempresa |
| 360,001 - 4,800,000 | Empresa de Pequeno Porte (EPP) |
| 4,800,001 - 78,000,000 | Média Empresa |
| > 78,000,000 | Grande Empresa |
### Occupation values
The following occupation values are supported:
`ADMINISTRATOR_MANAGER`, `SALES_REPRESENTATIVE`, `HR_ANALYST`, `FINANCIAL_ANALYST`, `SOFTWARE_DEVELOPER`, `MARKETING_PROFESSIONAL`, `HEALTHCARE_PROFESSIONAL`, `TEACHER`, `ENGINEER`, `LAWYER`, `GENERAL_SERVICES`, `CONSTRUCTION_WORKER`, `DRIVER`, `RECEPTIONIST`, `TECHNICIAN`, `DESIGNER`, `MACHINE_OPERATOR`, `CONSULTANT`, `BEAUTY_PROFESSIONAL`, `SECURITY_AGENT`, `AGRICULTURAL_WORKER`, `TRAVEL_AGENT`, `JOURNALIST`, `PSYCHOLOGIST`, `PUBLIC_SERVANT`, `RESEARCHER`, `ARTISAN`, `RETIRED`, `STUDENT`, `SELF_EMPLOYED`, `OTHER`
## Next steps
Connect merchants to payment providers
Learn about payment processing