Rinne API Documentation

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)
Register affiliation PIX keys for receiving payments (PIX 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

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

# 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

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.

Declared income ranges (contact)

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

Net worth ranges (contact)

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

Declared revenue ranges (company)

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

Getting started

Core concepts

Guides

Organizations and merchants

Company types

Organizations

Merchants

Company hierarchy

Key differences

Authentication scope

Creating merchants

Document requirements

CNPJ companies (legal entities)

CPF companies (individuals)

Updating document_tax_type

Financial information

Contact financial fields

Company financial fields

Celcoin provider translation

Occupation values

Next steps

Affiliations

Transactions

​Company types

​Organizations

​Merchants

​Company hierarchy

​Key differences

​Authentication scope

​Creating merchants

​Document requirements

​CNPJ companies (legal entities)

​CPF companies (individuals)

​Updating document_tax_type

​Financial information

​Contact financial fields

​Company financial fields

​Celcoin provider translation

​Occupation values

​Next steps

Affiliations

Transactions

Company types

Organizations

Merchants

Company hierarchy

Key differences

Authentication scope

Creating merchants

Document requirements

CNPJ companies (legal entities)

CPF companies (individuals)

Updating document_tax_type

Financial information

Contact financial fields

Company financial fields

Celcoin provider translation

Occupation values

Next steps