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.

​
Permissions

JWT-authenticated requests are subject to permission checks. Each endpoint requires specific permissions in the format resource[.subresource].action (e.g., transaction.list, merchant.company.create).
  • API key auth: Bypasses permission checks
  • JWT auth: Permissions are validated against the user’s roles
Wildcard permissions grant broader access:
  • resource.*: All actions for a resource
  • merchant.*: All merchant-scoped operations
  • *.*: All permissions
See the User management guide for the full permission list.

​
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

All list endpoints return paginated responses with a unified structure. Use query parameters to control pagination:
ParameterTypeDefaultDescription
pageinteger1Page number to retrieve
limitinteger20Items per page (maximum: 100)
curl "https://api-sandbox.rinne.com.br/core/v1/merchants?page=2&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
Every paginated response wraps the results in a data array and includes a pagination object: 
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

​
Pagination fields

FieldTypeDescription
pageintegerCurrent page number
limitintegerNumber of items per page
totalintegerTotal number of items matching the query
totalPagesintegerTotal number of pages
hasNextbooleanWhether a next page exists
hasPrevbooleanWhether a previous page exists

​
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

Card transactions

Implement credit and debit card API flows

Wallet transactions

Process Apple Pay and Google Pay via backend APIs

3D Secure authentication

Implement session-first and transaction-first 3DS flows

PIX payments

Build QR code and due date payment flows