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

# Quickstart

> Get started with Rinne API in minutes

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

## Prerequisites

Before you begin, you need:

* A Rinne organization account (contact [sales@rinne.com.br](mailto:sales@rinne.com.br))
* Your API key from the Rinne dashboard
* A merchant created under your organization

## Base URLs

<CodeGroup>
  ```bash Sandbox theme={null}
  https://api-sandbox.rinne.com.br/core
  ```

  ```bash Production theme={null}
  https://api.rinne.com.br/core
  ```
</CodeGroup>

<Note>
  Use the sandbox environment for testing. All examples in this guide use the sandbox URL.
</Note>

## Step 1: Authenticate your requests

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

```bash theme={null}
curl https://api-sandbox.rinne.com.br/core/v1/companies/me \
  -H "x-api-key: YOUR_API_KEY"
```

<Tip>
  For more details on authentication methods and best practices, see the [Authentication guide](/guides/authentication).
</Tip>

## Step 2: Create a fee policy

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

```bash theme={null}
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
      }
    ]
  }'
```

<Note>
  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.
</Note>

<Tip>
  Learn more about fee policies and pricing rules in the [Pricing concept guide](/concepts/pricing).
</Tip>

## Step 3: Create a merchant

Organizations can create merchants to process payments on their behalf.

```bash theme={null}
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": "contact@mystore.com",
      "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"
    }
  }'
```

<Note>
  Save the merchant `id` from the response. You'll need it for the next steps.
</Note>

<Warning>
  **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](/concepts/affiliations#sandbox-testing-behavior) for details.
</Warning>

<Tip>
  For more details on merchants and the company hierarchy, see the [Organizations & Merchants guide](/concepts/organizations-and-merchants).
</Tip>

## Step 4: Create an affiliation

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

```bash theme={null}
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`.

<Tip>
  Learn more about affiliations and payment providers in the [Affiliations concept guide](/concepts/affiliations).
</Tip>

## Step 5: Create a PIX transaction

Once your affiliation is active, you can create transactions.

```bash theme={null}
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": "joao@example.com",
      "document_type": "CPF",
      "document_number": "81146431023"
    }
  }'
```

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

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

<Tip>
  For more details on PIX payments and transaction flows, see the [PIX Payments guide](/guides/pix-payments) and [Transactions concept guide](/concepts/transactions).
</Tip>

## Step 6: Monitor transaction status

You can check the transaction status at any time:

```bash theme={null}
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:

```json theme={null}
{
  "type": "transaction.status-changed",
  "payload": {
    "transaction_id": "tx_123456789",
    "old_status": "WAITING_PAYMENT",
    "new_status": "APPROVED"
  }
}
```

<Tip>
  Learn how to set up webhooks for real-time notifications in the [Webhooks guide](/guides/webhooks).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="rinne-js SDK" icon="js" href="/rinne-js">
    Accept Apple Pay & Google Pay on the web
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    Learn about API authentication
  </Card>

  <Card title="PIX Payments" icon="qrcode" href="/guides/pix-payments">
    Process instant PIX payments
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Set up event notifications
  </Card>
</CardGroup>