Rinne API Documentation

This guide will help you create your first transaction using the Rinne API.

Prerequisites

Before you begin, you need:

A Rinne organization account (contact [email protected])
Your API key from the Rinne dashboard
A merchant created under your organization

Base URLs

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

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

Use the sandbox environment for testing. All examples in this guide use the sandbox URL.

Step 1: Authenticate your requests

All API requests require authentication using your API key in the x-api-key header.

curl https://api-sandbox.rinne.com.br/core/v1/companies/me \
  -H "x-api-key: YOUR_API_KEY"

For more details on authentication methods and best practices, see the Authentication guide.

Step 2: Create a fee policy

Before creating merchants, set up a fee policy to define how much you’ll charge for processing transactions.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default-fees",
    "description": "Default fee structure for merchants",
    "is_active": true,
    "cashout_price": 350,
    "rules": [
      {
        "conditions": [
          {
            "field": "transaction.payment_method",
            "operator": "EQUALS",
            "value": "PIX"
          }
        ],
        "price": {
          "percentage": 0.99
        },
        "priority": 1
      },
      {
        "conditions": [],
        "price": {
          "percentage": 3.0
        },
        "priority": 99
      }
    ]
  }'

This creates a simple fee policy that charges 0.99% for PIX transactions and 3.0% for all other payment methods. Save the policy id from the response.

Learn more about fee policies and pricing rules in the Pricing concept guide.

Step 3: Create a merchant

Organizations can create merchants to process payments on their behalf.

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": "My Store Ltda.",
    "name": "My Store",
    "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": "SOFTWARE_DEVELOPER",
      "net_worth": 100000,
      "address": {
        "street": "Rua das Flores",
        "street_number": "123",
        "neighborhood": "Centro",
        "zipcode": "01234567",
        "country": "076",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "address": {
      "street": "Av Paulista",
      "street_number": "1000",
      "neighborhood": "Bela Vista",
      "zipcode": "01310100",
      "country": "076",
      "state": "SP",
      "city": "São Paulo"
    },
    "transfer_configurations": {
      "automatic_transfer_enabled": true,
      "transfer_frequency": "DAILY",
      "transfer_date": 1,
      "rail": "PIX"
    },
    "declared_revenue": 500000,
    "bank_account": {
      "branch_number": "0001",
      "account_number": "123456",
      "account_type": "CHECKING",
      "account_holder_name": "My Store Ltda.",
      "account_holder_document_number": "16525269000121",
      "ispb": "00000000"
    }
  }'

Save the merchant id from the response. You’ll need it for the next steps.

Sandbox testing: In sandbox, the contact phone number’s last digit controls affiliation behavior:

Ending with 1: Affiliation approved after document processing
Ending with 2: Affiliation rejected before requesting documents
Ending with 3: Affiliation rejected after document processing

See the Affiliations guide for details.

For more details on merchants and the company hierarchy, see the Organizations & Merchants guide.

Step 4: Create an affiliation

Before processing transactions, create an affiliation with a payment provider.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "allowed_capture_methods": ["ECOMMERCE"],
    "allowed_payment_methods": ["PIX"]
  }'

The affiliation will be created with status PENDING_APPROVAL. Once approved by the provider, it will change to ACTIVE.

Learn more about affiliations and payment providers in the Affiliations concept guide.

Step 5: Create a PIX transaction

Once your affiliation is active, you can create transactions.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "request_id": "unique-request-123",
    "amount": 10000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "PIX",
    "pix_data": {
      "description": "Payment for order #123",
      "expiration_in_seconds": 3600
    },
    "consumer": {
      "full_name": "João Silva",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "81146431023"
    }
  }'

The response includes a PIX QR code that your customer can scan to complete the payment:

{
  "id": "tx_123456789",
  "status": "WAITING_PAYMENT",
  "amount": 10000,
  "pix_data": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "expires_at": "2025-01-21T11:00:00Z"
  }
}

For more details on PIX payments and transaction flows, see the PIX Payments guide and Transactions concept guide.

Step 6: Monitor transaction status

You can check the transaction status at any time:

curl https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID \
  -H "x-api-key: YOUR_API_KEY"

Or set up webhooks to receive real-time status updates:

{
  "type": "transaction.status-changed",
  "payload": {
    "transaction_id": "tx_123456789",
    "old_status": "WAITING_PAYMENT",
    "new_status": "APPROVED"
  }
}

Learn how to set up webhooks for real-time notifications in the Webhooks guide.

Next steps

rinne-js SDK

Accept Apple Pay & Google Pay on the web

Authentication

Learn about API authentication

PIX Payments

Process instant PIX payments

Webhooks

Set up event notifications

Getting started

Core concepts

Guides

Quickstart

Prerequisites

Base URLs

Step 1: Authenticate your requests

Step 2: Create a fee policy

Step 3: Create a merchant

Step 4: Create an affiliation

Step 5: Create a PIX transaction

Step 6: Monitor transaction status

Next steps

rinne-js SDK

Authentication

PIX Payments

Webhooks

​Prerequisites

​Base URLs

​Step 1: Authenticate your requests

​Step 2: Create a fee policy

​Step 3: Create a merchant

​Step 4: Create an affiliation

​Step 5: Create a PIX transaction

​Step 6: Monitor transaction status

​Next steps

rinne-js SDK

Authentication

PIX Payments

Webhooks

Prerequisites

Base URLs

Step 1: Authenticate your requests

Step 2: Create a fee policy

Step 3: Create a merchant

Step 4: Create an affiliation

Step 5: Create a PIX transaction

Step 6: Monitor transaction status

Next steps