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 us at [email protected])
An API key for your organization — see the Authentication guide to create one
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": "52601815906",
      "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 at the background check, once documents are submitted
Ending with 3: Affiliation rejected after document processing

The contact’s CPF decides the biometric verification: an even last digit approves it and an odd one reproves it, which leaves the affiliation waiting. See Test onboarding in the sandbox 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 is created with status WAITING_DOCUMENTS and an onboarding_url: the provider needs the contact’s identity document and biometric verification, and the merchant’s articles of incorporation, before it can decide. Open onboarding_url on a phone and complete it, or supply the items through the API. Once the last one is in, Rinne submits the affiliation, and when the provider approves it the status changes to ACTIVE.

See Onboarding for the onboarding link, the API flow and how to test each outcome in the sandbox.

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