Skip to main content
PIX keys are unique identifiers that allow merchants to receive instant payments through Brazil’s PIX system. Each merchant can register multiple PIX keys with different providers.

​
What is a PIX key?

A PIX key is an alias that simplifies receiving payments. Instead of sharing bank account details, customers can send money using:
  • Email address
  • Phone number
  • CPF/CNPJ document
  • Random key (EVP)

​
Entity relationships

​
Key types

​
EVP (Random key)

A random key generated by the provider. This is the most common type and is automatically created when an affiliation is activated. 
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": true
  }'
The provider generates the key value automatically: 
{
  "id": "pix-key-123",
  "key_type": "EVP",
  "key": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "status": "ACTIVE",
  "primary": true
}

​
Automatic PIX key creation

When a merchant’s affiliation is activated, Rinne automatically creates a primary EVP PIX key for that affiliation. This ensures merchants can immediately receive PIX payments without manual setup.

​
Primary PIX key

Each merchant should have one primary PIX key per provider. The primary key is used by default when creating PIX transactions. 
# Set a key as primary
{
  "primary": true
}
When you set a key as primary, any existing primary key for that provider becomes non-primary.

​
PIX key status

StatusDescription
ACTIVEKey is registered and can receive payments
INACTIVEKey is registered but temporarily disabled
PENDING_DELETIONDeletion requested, awaiting provider confirmation
DELETEDKey has been deleted

​
Managing PIX keys

​
List PIX keys

curl https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/pix/keys \
  -H "x-api-key: YOUR_API_KEY"

​
Delete a PIX key

curl -X DELETE 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": "merchant@store.com"
  }'
Deleting a PIX key will prevent receiving payments to that key. Ensure you have another active key before deletion.

​
Using PIX keys in transactions

When creating a PIX transaction, you can specify which PIX key to use: 
{
  "payment_method": "PIX",
  "pix_data": {
    "pix_key_id": "pix-key-123",
    "description": "Payment for order #123",
    "expiration_in_seconds": 3600
  }
}
If you don’t specify a pix_key_id, the merchant’s primary PIX key is used automatically.

​
PIX key requirements

  • Merchant must have an active affiliation with the provider
  • Key format must match the key type (email format for EMAIL, etc.)
  • Keys must be unique across the provider’s system
  • EVP keys don’t require a key value (generated by provider)

​
Next steps

PIX Payments

Process PIX transactions

Banking

Manage bank accounts and transfers