Skip to main content
The Rinne API is organized around REST principles. It uses standard HTTP methods, authentication, and status codes. All requests and responses use JSON format.

​
Base URLs

https://api-sandbox.rinne.com.br/core

​
Authentication

The API uses API key authentication via the x-api-key header: 
curl https://api-sandbox.rinne.com.br/core/v1/companies/me \
  -H "x-api-key: YOUR_API_KEY"
Some endpoints also support JWT authentication via the Authorization header: 
curl https://api-sandbox.rinne.com.br/core/v1/auth/me \
  -H "Authorization: Bearer JWT_TOKEN"
See the Authentication guide for details.

​
Request format

All POST, PATCH, and PUT requests must include a Content-Type: application/json header and a JSON body: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Store Name Ltda.",
    "document_number": "16525269000121",
    ...
  }'

​
Response format

​
Success responses

Successful requests return the requested data directly: 
{
  "id": "merchant-123",
  "name": "My Store",
  "status": "ACTIVE",
  ...
}

​
Error responses

Errors return an error object with detailed information: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [...]
    }
  }
}
See the Error handling guide for details.

​
Pagination

List endpoints support pagination through query parameters:
  • page: Page number (default: 1)
  • limit: Items per page (default: 20, maximum: 100)
curl "https://api-sandbox.rinne.com.br/core/v1/merchants?page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
Response includes pagination metadata: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

​
Filtering and sorting

Many list endpoints support filtering and sorting:

​
Filtering

# Filter by status
GET /v1/merchants?status=ACTIVE,INACTIVE

# Filter by date range
GET /v1/transactions?created_at_from=2025-01-01T00:00:00Z&created_at_to=2025-01-31T23:59:59Z

# Filter by amount range
GET /v1/transactions?amount_from=5000&amount_to=20000

​
Sorting

Use the sort parameter with field names. Prefix with - for descending order: 
# Sort by creation date (newest first)
GET /v1/merchants?sort=-created_at

# Multiple sort fields
GET /v1/transactions?sort=-created_at,amount

​
Idempotency

Use the request_id field to make requests idempotent: 
{
  "request_id": "unique-request-123",
  "amount": 10000,
  ...
}
If you retry a request with the same request_id, you’ll receive the existing resource instead of creating a duplicate.

​
Amounts in cents

All monetary values are represented as integers in cents:
  • 10000 = R$ 100.00
  • 1050 = R$ 10.50
  • 99 = R$ 0.99
Never use decimal values or floating-point numbers for amounts.

​
Date and time format

All timestamps use ISO 8601 format with UTC timezone: 
2025-01-21T10:30:00.000Z

​
Supported providers

The API supports multiple payment providers:
  • CELCOIN: PIX integration and banking services
  • RINNE: Internal provider
Provider names are case-insensitive in requests but always returned in uppercase.

​
Rate limiting

The API implements rate limiting to ensure platform stability. If you exceed limits, you’ll receive a 429 status code with a retry_after value in seconds. Implement exponential backoff for retries.

​
Webhooks

Rinne sends webhooks for real-time event notifications. See the Webhooks guide for setup and handling.

​
API versioning

The current API version is v1, indicated in the URL path: 
/v1/transactions
/v1/merchants
Future versions will be released as v2, v3, etc. Version 1 will remain supported for backward compatibility.

​
Next steps

Merchants

Merchant management endpoints

Transactions

Transaction processing endpoints

Banking

Banking operation endpoints

Webhooks

Webhook event schemas