Skip to main content
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

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": "[email protected]",
      "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): 
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": "[email protected]",
      "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: 
{
  "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: 
{
  "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

​
Automatic 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 PIX keys

Merchants can create additional PIX keys: 
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 PIX keys

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: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/refund \
  -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.
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.

​
Pay a merchant’s transaction

Use this endpoint when paying a transaction that belongs to a specific merchant: 
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. 
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"
  }'
Only companies with type ORGANIZATION can use the /v1/transactions/{transactionId}/pay endpoint.
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

  • 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)
Monitor for expired transactions and notify customers to create a new payment.
Don’t poll for transaction status. Use webhooks to receive real-time updates.
Ensure customer CPF/CNPJ is valid before creating transactions to reduce fraud.
For invoice payments, use due_date with appropriate pricing modifiers to encourage early payment and handle late payments.

​
Next steps

Webhooks

Receive real-time payment notifications

Banking

Manage settlements and transfers