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

# Pricing

> Flexible rule-based pricing for fees and costs

Rinne uses a dynamic pricing system based on policies and rules. This allows you to configure different pricing for various transaction types, payment methods, and merchant categories.

## Pricing components

Every transaction has two pricing components:

### Entity relationships

```mermaid theme={null}
graph LR
    O[Organization] -->|creates| FP[Fee Policies]
    FP -->|applied to| T[Transaction]
    CP[Cost Policies] -->|applied to| T
    P[Provider] -->|defines| CP
    MCC[Merchant MCC] -->|determines| CP
    FP -->|contains| FR[Fee Rules]
    CP -->|contains| CR[Cost Rules]
    FR -->|evaluates| C[Conditions]
    CR -->|evaluates| C
    
    style O fill:#5B68EB,color:#fff
    style FP fill:#7B89FF,color:#fff
    style CP fill:#4A56D9,color:#fff
    style T fill:#7B89FF,color:#fff
    style P fill:#5B68EB,color:#fff
    style MCC fill:#7B89FF,color:#fff
```

### Fee policies

Fees are what you charge to merchants for processing transactions. Fee policies are configured at the organization level and inherited by merchants.

```json theme={null}
{
  "fee": {
    "percentage": 3.5,
    "flat": 0,
    "minimum_price": 100
  }
}
```

### Cost policies

Costs are what providers charge you for processing transactions. Cost policies are configured per provider and MCC (Merchant Category Code).

```json theme={null}
{
  "cost": {
    "percentage": 0.5,
    "flat": 0,
    "minimum_price": 50
  }
}
```

## Pricing structure

Each pricing value can include:

* **percentage**: Percentage of transaction amount (e.g., 3.5%)
* **flat**: Fixed amount in cents (e.g., 50 cents)
* **minimum\_price**: Minimum fee/cost in cents

At least one component must be specified.

## Rule-based pricing

Pricing policies use rules with conditions to apply different pricing based on transaction attributes.

### Example fee policy

```json theme={null}
{
  "name": "standard-card-fees",
  "description": "Standard fee structure for card transactions",
  "is_active": true,
  "cashout_price": 350,
  "rules": [
    {
      "conditions": [
        {
          "field": "transaction.payment_method",
          "operator": "EQUALS",
          "value": "CREDIT_CARD"
        },
        {
          "field": "transaction.installments",
          "operator": "EQUALS",
          "value": 1
        }
      ],
      "price": {
        "percentage": 2.3
      },
      "priority": 1
    },
    {
      "conditions": [
        {
          "field": "transaction.payment_method",
          "operator": "EQUALS",
          "value": "PIX"
        }
      ],
      "price": {
        "percentage": 0.99
      },
      "priority": 2
    },
    {
      "conditions": [],
      "price": {
        "percentage": 3.0
      },
      "priority": 99
    }
  ]
}
```

### How rules work

1. Rules are evaluated in priority order (1 = highest)
2. First rule where all conditions match is applied
3. Empty conditions array = default rule (matches everything)
4. Each policy should have a default rule with lowest priority

### Rule evaluation flow

```mermaid theme={null}
flowchart TD
    Start[Transaction created] --> Sort[Sort rules by priority]
    Sort --> Eval{Evaluate rule conditions}
    Eval -->|All match| Apply[Apply rule price]
    Eval -->|No match| Next{More rules?}
    Next -->|Yes| Eval
    Next -->|No| Default[Apply default rule]
    Apply --> End[Price calculated]
    Default --> End
    
    style Start fill:#5B68EB,color:#fff
    style Apply fill:#7B89FF,color:#fff
    style Default fill:#4A56D9,color:#fff
    style End fill:#5B68EB,color:#fff
```

## Condition operators

| Operator           | Description      | Example                                    |
| ------------------ | ---------------- | ------------------------------------------ |
| `EQUALS`           | Exact match      | `payment_method = "PIX"`                   |
| `NOT_EQUALS`       | Not equal        | `payment_method != "PIX"`                  |
| `GREATER_THAN`     | Greater than     | `amount > 10000`                           |
| `LESS_THAN`        | Less than        | `amount < 50000`                           |
| `GREATER_OR_EQUAL` | Greater or equal | `installments >= 3`                        |
| `LESS_OR_EQUAL`    | Less or equal    | `installments <= 12`                       |
| `IN`               | In array         | `payment_method IN ["PIX", "CREDIT_CARD"]` |
| `NOT_IN`           | Not in array     | `payment_method NOT IN ["BOLETO"]`         |

## Transaction fields

You can create conditions based on these transaction fields:

* `transaction.amount`: Transaction amount in cents
* `transaction.payment_method`: Payment method (PIX, CREDIT\_CARD, etc.)
* `transaction.installments`: Number of installments
* `transaction.capture_method`: Capture method (ECOMMERCE, EMV, etc.)
* `transaction.automatic_anticipation`: Whether the transaction was automatically anticipated (`true` or `false`)

## Cashout pricing

Both fee and cost policies include a `cashout_price` field (in cents) that defines the fixed fee/cost for cashout operations:

```json theme={null}
{
  "cashout_price": 350
}
```

This is charged when merchants transfer funds from their provider account to external bank accounts.

## Managing fee policies

### Listing fee policies

List all fee policies for your organization:

```bash theme={null}
curl https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies \
  -H "x-api-key: YOUR_ORG_API_KEY"
```

The response includes a `companies_with_fee_policy` field for each policy, showing how many companies are using that fee policy:

```json theme={null}
{
  "data": [
    {
      "id": "fee-policy-123",
      "name": "standard-fees",
      "is_active": true,
      "companies_with_fee_policy": 5,
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

### Creating fee policies

Organizations can create custom fee policies:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "premium-merchant-fees",
    "description": "Reduced fees for premium merchants",
    "is_active": true,
    "cashout_price": 250,
    "rules": [
      {
        "conditions": [
          {
            "field": "transaction.payment_method",
            "operator": "EQUALS",
            "value": "PIX"
          }
        ],
        "price": {
          "percentage": 0.5
        },
        "priority": 1
      },
      {
        "conditions": [],
        "price": {
          "percentage": 2.0
        },
        "priority": 99
      }
    ]
  }'
```

### Updating fee policies

You can update existing fee policies using partial updates. All fields are optional:

```bash theme={null}
curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies/{id} \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-premium-fees",
    "is_active": false
  }'
```

#### Updating rules

Rules can be selectively updated, added, or preserved:

* **Rules with IDs**: Updates those specific rules while preserving unmentioned rules
* **Rules without IDs**: Creates new rules and adds them to the policy
* **Rules not mentioned**: Remain unchanged and preserved

**Update a specific rule:**

```bash theme={null}
curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies/{id} \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "conditions": [
          {
            "field": "transaction.amount",
            "operator": "GREATER_THAN",
            "value": 10000
          }
        ],
        "price": {
          "percentage": 1.5,
          "flat": 50
        },
        "priority": 1
      }
    ]
  }'
```

**Add a new rule:**

```bash theme={null}
curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/pricing/fee-policies/{id} \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "conditions": [
          {
            "field": "transaction.installments",
            "operator": "GREATER_OR_EQUAL",
            "value": 12
          }
        ],
        "price": {
          "percentage": 4.0,
          "flat": 200
        },
        "priority": 3
      }
    ]
  }'
```

<Note>
  When updating a rule's conditions, the conditions for that specific rule are replaced (not merged). Other rules remain unchanged.
</Note>

## Cost policies

Cost policies are configured by Rinne administrators for each provider and MCC combination. They define what the provider charges for processing transactions.

Organizations can view their cost policies:

```bash theme={null}
curl "https://api-sandbox.rinne.com.br/core/v1/pricing/cost-policies?provider=CELCOIN&mcc=5912" \
  -H "x-api-key: YOUR_API_KEY"
```

## MCC (Merchant Category Code)

Each merchant is assigned an MCC that categorizes their business type. The MCC determines which cost policy applies to their transactions.

Common MCCs:

* `5912`: Drug stores and pharmacies
* `5411`: Grocery stores and supermarkets
* `5812`: Restaurants
* `5999`: Miscellaneous retail

List available MCCs for your organization:

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

## Per-transaction fee policy

You can override the default fee policy for specific transactions:

```json theme={null}
{
  "fee_policy_id": "custom-fee-policy-123",
  "amount": 10000,
  "payment_method": "PIX"
}
```

The specified fee policy must belong to your organization.

## Next steps

<CardGroup cols={2}>
  <Card title="Transactions" icon="credit-card" href="/concepts/transactions">
    Learn about transaction processing
  </Card>

  <Card title="Banking" icon="building-columns" href="/concepts/banking">
    Manage banking operations
  </Card>
</CardGroup>