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

# PIX payments

> Process instant payments using Brazil's PIX system

PIX is Brazil's instant payment system that enables real-time transfers 24/7. Rinne provides full support for PIX payments through integrated providers.

## How PIX works

1. Merchant creates a PIX transaction with a QR code
2. Customer scans the QR code with their banking app
3. Customer confirms the payment
4. Merchant receives instant notification
5. Funds are settled to merchant's account

## Prerequisites

Before processing PIX payments, ensure:

* Merchant has an active affiliation with a provider
* Affiliation includes `PIX` in `allowed_payment_methods`
* Merchant has at least one active PIX key

## Creating a PIX transaction

### Immediate PIX payment

```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": "order-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"
    }
  }'
```

### PIX with due date

Create PIX payments with a due date and optional pricing modifiers (interest, fine, discount, abatement):

```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": "order-124",
    "amount": 100000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "PIX",
    "pix_data": {
      "description": "Invoice payment with due date",
      "due_date": "2025-12-31",
      "expiration_in_days_after_due_date": 30,
      "interest": {
        "percentage": 2.0,
        "modality": "PERCENTAGE_PER_MONTH"
      },
      "fine": {
        "percentage": 5.0,
        "modality": "PERCENTAGE"
      },
      "discount": {
        "modality": "PERCENTAGE_UNTIL_DATE",
        "discount_dates_config": [
          {
            "until_date": "2025-12-15",
            "percentage": 10.0
          },
          {
            "until_date": "2025-12-25",
            "percentage": 5.0
          }
        ]
      },
      "abatement": {
        "amount": 1000,
        "modality": "FIXED"
      }
    },
    "consumer": {
      "full_name": "Maria Santos",
      "email": "maria@example.com",
      "document_type": "CPF",
      "document_number": "12345678901"
    }
  }'
```

### PIX-specific fields

#### pix\_data

* `pix_key_id` (optional): Specific PIX key to use. If not provided, uses merchant's primary key
* `description` (optional): Description shown to the payer
* `expiration_in_seconds` (optional): QR code expiration time (1-86400 seconds, default: 86400). Must NOT be provided when `due_date` is provided
* `due_date` (optional): Due date for the payment in YYYY-MM-DD format. Must be today or later. Required when using interest, fine, discount, or abatement
* `expiration_in_days_after_due_date` (optional): Days after due date before expiration (1-365, default: 30). Must NOT be provided if `due_date` is also not provided

#### Consumer information

For PIX transactions, provide customer details:

* `full_name`: Customer's full name (required when `due_date` is provided)
* `email`: Customer's email
* `document_type`: `CPF` or `CNPJ` (required when `due_date` is provided)
* `document_number`: Customer's document number (required when `due_date` is provided)

## PIX QR code

The response includes a PIX QR code that customers can scan:

```json theme={null}
{
  "id": "tx_123456789",
  "status": "WAITING_PAYMENT",
  "pix_data": {
    "qr_code": "00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Store Name6008São Paulo62070503***6304E2CA",
    "expires_at": "2025-01-21T11:00:00Z",
    "pix_key_id": "pix-key-123"
  }
}
```

Display the QR code to your customer using a QR code library or image generator.

## PIX transaction lifecycle

### 1. Transaction created

Status: `WAITING_PAYMENT`

The transaction is created with a QR code. Customer has until expiration to pay.

### 2. Payment received

Status: `APPROVED`

When the customer pays, you receive a webhook notification. The event includes a `payload` with the transaction id and status transition, plus standard metadata on the same object (such as `id`, `version`, `timestamp`, `source`, and `company_id`). See the **transaction.status-changed** event in the API reference for the full shape.

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

### 3. Settlement

Funds are settled to the merchant's bank account according to transfer configurations.

### 4. Expiration (if not paid)

Status: `EXPIRED`

If the customer doesn't pay before expiration, the transaction expires automatically.

## PIX key management for receiving payments

The `/pix/keys` endpoints in this guide manage affiliation PIX keys used to receive PIX payments.

<Info>
  For cashouts, use external PIX keys under `/pix-keys`. See <a href="/guides/cashouts">Cashouts guide</a>.
</Info>

### Automatic affiliation PIX key creation

When a merchant's affiliation is activated, Rinne automatically creates a primary EVP (random) PIX key. This ensures merchants can immediately receive PIX payments.

### Creating additional affiliation PIX keys

Create additional affiliation PIX keys when you need more receiving keys:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/pix/keys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "key_type": "EVP",
    "primary": false
  }'
```

### Listing affiliation PIX keys

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

## PIX refunds

Refund PIX transactions using the refund endpoint:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/refunds \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_amount": 10000,
    "refund_reason": "CUSTOMER_REQUEST",
    "description": "Customer requested refund"
  }'
```

### PIX refund reasons

* `CUSTOMER_REQUEST`: Customer requested refund
* `FRAUD`: Fraudulent transaction
* `BANKING_ERROR`: Banking system error
* `PIX_WITHDRAWAL_OR_CHANGE_ERROR`: PIX withdrawal or change error

## Testing PIX and BOLEPIX in sandbox

In the sandbox environment, you can simulate PIX and BOLEPIX payments. Two endpoints are available depending on your use case.

<Warning>
  The `payer_company_id` must be different from the transaction owner (merchant or organization). Providing the same company ID as the transaction owner returns a `400` validation error.
</Warning>

### Pay a merchant's transaction

Use this endpoint when paying a transaction that belongs to a specific merchant:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/pay \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_company_id": "PAYER_COMPANY_ID"
  }'
```

### Pay an organization's own transaction

Use this endpoint when paying a transaction owned by the authenticated organization company. No `merchantId` parameter is needed — the transaction is looked up using the authenticated organization's company ID.

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/transactions/TRANSACTION_ID/pay \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_company_id": "PAYER_COMPANY_ID"
  }'
```

<Note>
  Only companies with type `ORGANIZATION` can use the `/v1/transactions/{transactionId}/pay` endpoint.
</Note>

Both endpoints automatically detect the payment method based on the transaction:

* **PIX transactions**: Uses the QR code from `pix_data.qr_code`
* **BOLEPIX transactions**: Uses the PIX EMV code from `bolepix_data.pix_emv`

The payment is always for the full transaction amount.

## PIX with due date features

### Interest

Interest is applied when payment is made after the due date. Configure using:

* `amount`: Fixed amount in cents per period
* `percentage`: Percentage per period (0-100, up to 2 decimal places)
* `modality`: Calculation method

**Interest modalities:**

* `AMOUNT_PER_DAY`: Fixed amount per day
* `PERCENTAGE_PER_DAY`: Percentage per day
* `PERCENTAGE_PER_MONTH`: Percentage per month
* `PERCENTAGE_PER_YEAR`: Percentage per year
* `AMOUNT_PER_WORKING_DAY`: Fixed amount per working day
* `PERCENTAGE_PER_WORKING_DAY`: Percentage per working day
* `PERCENTAGE_PER_WORKING_MONTH`: Percentage per working month
* `PERCENTAGE_PER_WORKING_YEAR`: Percentage per working year

### Fine

Fine is a one-time charge applied when payment is made after the due date:

* `amount`: Fixed amount in cents
* `percentage`: Percentage of transaction amount (0-100)
* `modality`: `FIXED` or `PERCENTAGE`

### Discount

Discount reduces the payment amount when paid before or on specific dates:

* `modality`: Discount calculation method
* `discount_dates_config`: Array of up to 3 discount periods (for date-based modalities)
* `amount` or `percentage`: Value for per-day modalities

**Discount modalities:**

* `FIXED_AMOUNT_UNTIL_DATE`: Fixed amounts valid until specific dates
* `PERCENTAGE_UNTIL_DATE`: Percentages valid until specific dates
* `AMOUNT_PER_DAY`: Amount reduction per day
* `AMOUNT_PER_WORKING_DAY`: Amount reduction per working day
* `PERCENTAGE_PER_DAY`: Percentage reduction per day
* `PERCENTAGE_PER_WORKING_DAY`: Percentage reduction per working day

### Abatement

Abatement permanently reduces the transaction amount:

* `amount`: Fixed amount in cents
* `percentage`: Percentage of transaction amount (0-100)
* `modality`: `FIXED` or `PERCENTAGE`

## Best practices

<AccordionGroup>
  <Accordion title="Set appropriate expiration times">
    * E-commerce: 15-30 minutes (900-1800 seconds)
    * In-person: 5-10 minutes (300-600 seconds)
    * Invoices: 24 hours (86400 seconds)
    * Due date payments: Use `expiration_in_days_after_due_date` (default: 30 days)
  </Accordion>

  <Accordion title="Handle expired transactions">
    Monitor for expired transactions and notify customers to create a new payment.
  </Accordion>

  <Accordion title="Use webhooks for status updates">
    Don't poll for transaction status. Use webhooks to receive real-time updates.
  </Accordion>

  <Accordion title="Validate customer documents">
    Ensure customer CPF/CNPJ is valid before creating transactions to reduce fraud.
  </Accordion>

  <Accordion title="Use due dates for invoices">
    For invoice payments, use `due_date` with appropriate pricing modifiers to encourage early payment and handle late payments.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time payment notifications
  </Card>

  <Card title="Banking" icon="building-columns" href="/concepts/banking">
    Bank accounts, balances, statements, and internal transfers
  </Card>

  <Card title="Cashouts" icon="arrow-right-from-bracket" href="/concepts/cashouts">
    Cashouts and external destinations
  </Card>
</CardGroup>