curl --request POST \
--url https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"key": "[email protected]",
"primary": false
}
'import requests
url = "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys"
payload = {
"key": "[email protected]",
"primary": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({key: '[email protected]', primary: false})
};
fetch('https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'key' => '[email protected]',
'primary' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys"
payload := strings.NewReader("{\n \"key\": \"[email protected]\",\n \"primary\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"key\": \"[email protected]\",\n \"primary\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"key\": \"[email protected]\",\n \"primary\": false\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174001",
"company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
"key_type": "EMAIL",
"key": "[email protected]",
"primary": false,
"status": "ACTIVE",
"deleted_at": null,
"created_at": "2025-01-01T10:00:00.000Z",
"updated_at": "2025-01-01T10:05:00.000Z",
"dict_key_information": {
"bank": "18236120",
"account": "********",
"branch": "0",
"account_type": "********",
"owner_name": "teste celcoin",
"owner_document": "***778477**",
"is_owned_by_company": true
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation error",
"status": 400,
"details": {
"issues": [
{
"field": "email",
"type": "REQUIRED",
"message": "Field 'email' is required",
"value": "invalid_value",
"constraints": {
"min": 18,
"max": 120
}
}
]
},
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication required to access this resource",
"status": 401,
"details": {
"reason": "Invalid API key"
},
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "You need 'admin' permissions to access this resource",
"status": 403,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Company with ID '123' not found",
"status": 404,
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "CONFLICT_ERROR",
"message": "A Resource with this origin_bank_account_id + request_id already exists",
"status": 409,
"details": {
"field": "origin_bank_account_id + request_id",
"value": "12345678"
},
"path": "/companies/bank-accounts",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred",
"status": 500,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}Create a company PIX key
Requires the banking.create permission.
Registers a new PIX key for the authenticated company. A DICT lookup is
performed against the company’s active affiliation bank account before
creating the key, and the result is returned in dict_key_information. Per BACEN’s
external DICT API, several fields may be masked (e.g. account number, account type,
owner document) as part of DICT’s read-attack prevention; values should be passed
through as returned when initiating payments.
The key is normalized and validated before the lookup: CPF/CNPJ keys are stored
bare (123.456.789-09 → 12345678909, alphanumeric CNPJs uppercased), phone
keys must be in international format and lose their separators
(+55 (11) 98765-4321 → +5511987654321), email keys are lowercased, and EVPs
are lowercase UUIDs. A key matching none of these forms is rejected with 400
before any DICT lookup.
If the company already has an active PIX key with the same key (after
normalization), the request fails with 409 and no DICT lookup is performed.
The request fails with 404 if no active valid affiliation with a bank account is found for the company.
curl --request POST \
--url https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"key": "[email protected]",
"primary": false
}
'import requests
url = "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys"
payload = {
"key": "[email protected]",
"primary": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({key: '[email protected]', primary: false})
};
fetch('https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'key' => '[email protected]',
'primary' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys"
payload := strings.NewReader("{\n \"key\": \"[email protected]\",\n \"primary\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"key\": \"[email protected]\",\n \"primary\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.rinne.com.br/core/v1/companies/me/pix-keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"key\": \"[email protected]\",\n \"primary\": false\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174001",
"company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
"key_type": "EMAIL",
"key": "[email protected]",
"primary": false,
"status": "ACTIVE",
"deleted_at": null,
"created_at": "2025-01-01T10:00:00.000Z",
"updated_at": "2025-01-01T10:05:00.000Z",
"dict_key_information": {
"bank": "18236120",
"account": "********",
"branch": "0",
"account_type": "********",
"owner_name": "teste celcoin",
"owner_document": "***778477**",
"is_owned_by_company": true
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation error",
"status": 400,
"details": {
"issues": [
{
"field": "email",
"type": "REQUIRED",
"message": "Field 'email' is required",
"value": "invalid_value",
"constraints": {
"min": 18,
"max": 120
}
}
]
},
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication required to access this resource",
"status": 401,
"details": {
"reason": "Invalid API key"
},
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "You need 'admin' permissions to access this resource",
"status": 403,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Company with ID '123' not found",
"status": 404,
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "CONFLICT_ERROR",
"message": "A Resource with this origin_bank_account_id + request_id already exists",
"status": 409,
"details": {
"field": "origin_bank_account_id + request_id",
"value": "12345678"
},
"path": "/companies/bank-accounts",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred",
"status": 500,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}Authorizations
Company API key for authentication
Body
Schema for creating a new company PIX key
PIX key value
Whether this is the primary PIX key
false
Response
PIX key created successfully. The response always includes
dict_key_information (object from DICT when available, or null).
Company PIX key response
PIX key ID
"123e4567-e89b-12d3-a456-426614174001"
Company ID
"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"
PIX key type
CPF, CNPJ, EMAIL, PHONE, EVP "EMAIL"
PIX key value
Whether this is the primary PIX key
false
PIX key status
ACTIVE, DELETED "ACTIVE"
Deletion timestamp (null if not deleted)
null
Creation timestamp
"2025-01-01T10:00:00.000Z"
Last update timestamp
"2025-01-01T10:05:00.000Z"
Last persisted DICT key lookup snapshot for this PIX key (from create or
update). Always present on every company and merchant PIX key response; use
null when no snapshot is stored (for example legacy keys) or the stored
snapshot is invalid.
Per BACEN's rules, DICT applies masking to protect against read attacks; fields such as account number, account type, and owner document may appear partially or fully masked (e.g. asterisks). Use the values as returned for any follow-up payment initiation on the same flow.
Show child attributes
Show child attributes

