Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt

Use this file to discover all available pages before exploring further.

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
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