Skip to main content
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 their own bank accounts
  • Create PIX keys 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: Each merchant operates independently with:
  • Unique API key
  • Isolated transaction data
  • Separate bank accounts
  • Individual provider affiliations
  • Custom transfer configurations

​
Key differences

FeatureOrganizationMerchant
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 
# List all merchants
GET /v1/merchants

# View all merchant transactions
GET /v1/merchants/transactions
Merchant API key: Access only to own data 
# View own transactions
GET /v1/transactions

# Manage own affiliations
GET /v1/affiliations

​
Creating merchants

Organizations create merchants using the /v1/merchants endpoint: 
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": "[email protected]",
      "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

  • 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

​
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

FieldTypeDescription
declared_incomeintegerMonthly income in whole reais. Default: 5000 (R$ 5.000)
occupationstringContact’s occupation. Default: OTHER
net_worthintegerTotal net worth in whole reais. Default: 50000 (R$ 50.000)

​
Company financial fields

FieldTypeDescription
declared_revenueintegerAnnual 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,000Very low income tier
5,001 - 10,000Low income tier
10,001 - 30,000Medium income tier
30,001 - 100,000High income tier
> 100,000Very high income tier
Total net worth values are mapped to the following tiers:
Value Range (reais)Description
≤ 50,000Very low net worth tier
50,001 - 200,000Low net worth tier
200,001 - 1,000,000Medium net worth tier
1,000,001 - 5,000,000High net worth tier
> 5,000,000Very high net worth tier
Annual revenue values are mapped to Brazilian company size classifications:
Value Range (reais)Description
≤ 81,000MEI
81,001 - 360,000Microempresa
360,001 - 4,800,000Empresa de Pequeno Porte (EPP)
4,800,001 - 78,000,000Média Empresa
> 78,000,000Grande 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

Affiliations

Connect merchants to payment providers

Transactions

Learn about payment processing