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

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-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: QR code expiration time (1-86400 seconds, default: 86400)

​
Consumer information

For PIX transactions, provide customer details:
  • full_name: Customer’s full name
  • email: Customer’s email
  • document_type: CPF or CNPJ
  • document_number: Customer’s document number

​
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 in sandbox

In the sandbox environment, you can simulate PIX payments: 
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 '{
    "amount": 10000,
    "payer_company_id": "payer-merchant-id"
  }'
This simulates a customer paying the PIX QR code.

​
Best practices

  • E-commerce: 15-30 minutes (900-1800 seconds)
  • In-person: 5-10 minutes (300-600 seconds)
  • Invoices: 24 hours (86400 seconds)
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.

​
Next steps

Webhooks

Receive real-time payment notifications

Banking

Manage settlements and transfers