Create a company PIX key

Requires the banking.create permission.

Registers a new PIX key for the authenticated company. A DICT lookup is always 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 request fails with 404 if no active valid affiliation with a bank account is found for the company.

POST /v1/companies/me/pix-keys

Create a company PIX key

cURL

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": "[e-mail]",
  "primary": false
}
'

201

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "key_type": "EMAIL",
  "key": "[e-mail]",
  "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
  }
}

Authorizations

x-api-key · string · header · required

Company API key for authentication

Body

application/json

Schema for creating a new company PIX key

key · string · required

PIX key value

Example:

"[e-mail]"

primary · boolean

Whether this is the primary PIX key

Example:

false

Response

201

application/json

PIX key created successfully. The response always includes dict_key_information (object from DICT when available, or null).

Company PIX key response

id · string<uuid> · required

PIX key ID

Example:

"123e4567-e89b-12d3-a456-426614174001"

company_id · string<uuid> · required

Company ID

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

key_type · enum<string> · required

PIX key type

Available options: CPF, CNPJ, EMAIL, PHONE, EVP

Example:

"EMAIL"

key · string · required

PIX key value

Example:

"[e-mail]"

primary · boolean · required

Whether this is the primary PIX key

Example:

false

status · enum<string> · required

PIX key status

Available options: ACTIVE, DELETED

Example:

"ACTIVE"

deleted_at · string<date-time> | null · required

Deletion timestamp (null if not deleted)

Example:

null

created_at · string<date-time> · required

Creation timestamp

Example:

"2025-01-01T10:00:00.000Z"

updated_at · string<date-time> · required

Last update timestamp

Example:

"2025-01-01T10:05:00.000Z"

dict_key_information · object · required

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