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
}'
{
"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
}
PIX key status
| Status | Description |
|---|
ACTIVE | Key is registered and can receive payments |
INACTIVE | Key is registered but temporarily disabled |
PENDING_DELETION | Deletion requested, awaiting provider confirmation |
DELETED | Key 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": "[email protected]"
}'
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
}
}
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
