Rinne API Documentation

curl --request PATCH \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Updated Merchant Name",
  "contact": {
    "email": "[email protected]",
    "phone": "+5511999999999"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": false,
    "transfer_frequency": "MONTHLY"
  },
  "metadata": {
    "updated_reason": "contact_information_change",
    "last_modified_by": "organization"
  }
}
'

{
  "id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "name": "Example Company",
  "full_name": "Example Company LTDA",
  "document_number": "16525269000121",
  "document_type": "CNPJ",
  "contact": {
    "first_name": "John",
    "last_name": "Silva",
    "phone": "+551199999999",
    "email": "[email protected]",
    "mother_name": "Maria Silva",
    "birth_date": "15-08-1990",
    "document_number": "81146431023",
    "politically_exposed": false,
    "declared_income": 5000,
    "occupation": "SOFTWARE_DEVELOPER",
    "net_worth": 50000,
    "role": "PARTNER",
    "address": {
      "street": "Contact Street",
      "street_number": "456",
      "complement": "Apt 201",
      "neighborhood": "Contact Neighborhood",
      "zipcode": "87654321",
      "country": "076",
      "state": "RJ",
      "city": "Rio de Janeiro"
    }
  },
  "status": "ACTIVE",
  "address": {
    "street": "Example Street",
    "street_number": "123",
    "complement": "Suite 101",
    "neighborhood": "Downtown",
    "zipcode": "12345678",
    "country": "076",
    "state": "SP",
    "city": "São Paulo"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": true,
    "transfer_frequency": "DAILY",
    "rail": "PIX",
    "utc_hour_of_day": 12,
    "day_of_week": 1,
    "day_of_month": 1,
    "min_balance": 1000
  },
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "document_tax_type": "PJ",
  "company_logo_url": "https://example.com/logo.png",
  "website_url": "https://example.com",
  "webhook_enabled": false,
  "kyc_enabled": false,
  "declared_revenue": 50000
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

PATCH

merchants

{merchantId}

curl --request PATCH \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Updated Merchant Name",
  "contact": {
    "email": "[email protected]",
    "phone": "+5511999999999"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": false,
    "transfer_frequency": "MONTHLY"
  },
  "metadata": {
    "updated_reason": "contact_information_change",
    "last_modified_by": "organization"
  }
}
'

{
  "id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "name": "Example Company",
  "full_name": "Example Company LTDA",
  "document_number": "16525269000121",
  "document_type": "CNPJ",
  "contact": {
    "first_name": "John",
    "last_name": "Silva",
    "phone": "+551199999999",
    "email": "[email protected]",
    "mother_name": "Maria Silva",
    "birth_date": "15-08-1990",
    "document_number": "81146431023",
    "politically_exposed": false,
    "declared_income": 5000,
    "occupation": "SOFTWARE_DEVELOPER",
    "net_worth": 50000,
    "role": "PARTNER",
    "address": {
      "street": "Contact Street",
      "street_number": "456",
      "complement": "Apt 201",
      "neighborhood": "Contact Neighborhood",
      "zipcode": "87654321",
      "country": "076",
      "state": "RJ",
      "city": "Rio de Janeiro"
    }
  },
  "status": "ACTIVE",
  "address": {
    "street": "Example Street",
    "street_number": "123",
    "complement": "Suite 101",
    "neighborhood": "Downtown",
    "zipcode": "12345678",
    "country": "076",
    "state": "SP",
    "city": "São Paulo"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": true,
    "transfer_frequency": "DAILY",
    "rail": "PIX",
    "utc_hour_of_day": 12,
    "day_of_week": 1,
    "day_of_month": 1,
    "min_balance": 1000
  },
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "document_tax_type": "PJ",
  "company_logo_url": "https://example.com/logo.png",
  "website_url": "https://example.com",
  "webhook_enabled": false,
  "kyc_enabled": false,
  "declared_revenue": 50000
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

Authorizations

x-api-key

string

header

required

Company API key for authentication

Path Parameters

merchantId

string

required

Merchant ID

Body

application/json

Schema for updating a merchant. Extends the company update fields with the merchant's active fee policy. Only specific fields can be updated for security reasons.

name

string

Company display name

Example:

"Updated Company Name"

full_name

string

Company full legal name

Example:

"Updated Company Full Legal Name"

document_tax_type

enum<string>

Tax classification type. Can only be updated when the company has no affiliations in non-final statuses (only FAILED/REJECTED are allowed). Must be PF for CPF companies; PJ, MEI, or ME for CNPJ companies.

Available options:

PJ,

MEI,

ME,

PF

Example:

"MEI"

company_logo_url

string

URL for company logo image

Example:

"https://example.com/new-logo.png"

contact

object

Contact information (partial update supported)

Show child attributes

website_url

string

Company website URL

Example:

"https://company.com"

address

object

Company address (partial update supported)

Show child attributes

transfer_configurations

object

Transfer configurations (partial update supported)

Show child attributes

declared_revenue

integer

Annual revenue in whole reais (BRL) for Banco Central compliance (Circular 3.978/2020)

Required range: x >= 0

Example:

50000

metadata

object

Additional metadata as JSON object

Example:

{
  "industry": "technology",
  "tier": "enterprise"
}

fee_policy_id

string<uuid>

ID of the fee policy to apply to this merchant. Must belong to the merchant's organization. This is the merchant's active fee policy used to price transactions and cashouts.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Merchant updated successfully

Transformed company data returned by the API

string

required

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

name

string

required

Example:

"Example Company"

full_name

string

required

Example:

"Example Company LTDA"

document_number

string

required

CPF (11 digits) or CNPJ (14 characters). CNPJ may be numeric or alphanumeric (IN RFB 2229/2024): first 12 positions are [A-Z0-9], last 2 are numeric check digits. Formatting is stripped and letters are uppercased on input.

Example:

"16525269000121"

document_type

enum<string>

required

Available options:

CNPJ,

CPF

Example:

"CNPJ"

contact

object

required

Show child attributes

status

enum<string>

required

Available options:

PENDING_ACTIVATION,

ACTIVE,

INACTIVE,

BLOCKED

Example:

"ACTIVE"

address

object

required

Show child attributes

transfer_configurations

object

required

Show child attributes

created_at

string<date-time>

required

Example:

"2023-01-01T00:00:00Z"

updated_at

string<date-time>

required

Example:

"2023-01-01T00:00:00Z"

document_tax_type

enum<string>

Document tax type:

PF: Pessoa Física (Individual) - for CPF companies
PJ: Pessoa Jurídica (Legal Entity) - for CNPJ companies
MEI: Microempreendedor Individual - for CNPJ companies
ME: Microempresa (Micro Enterprise) - for CNPJ companies

Available options:

PJ,

MEI,

ME,

PF

Example:

"PJ"

company_logo_url

string

Example:

"https://example.com/logo.png"

website_url

string

Example:

"https://example.com"

webhook_enabled

boolean

Whether webhooks are enabled for this company

Example:

false

kyc_enabled

boolean | null

Whether the organization's merchants undergo KYC. Managed by Rinne staff. Null on merchant responses.

Example:

false

declared_revenue

integer | null

Annual revenue in whole reais (BRL) for Banco Central compliance (Circular 3.978/2020)

Required range: x >= 0

Example:

50000

Introduction

Merchants

Pricing

Tap-on-Phone

Webhooks

Organization Management

User Management

System

Update merchant

Authorizations

Path Parameters

Body

Response