Managing Pix keys

A Pix key (also called an alias) is generated by encrypting one of the following types of identifying personal data, such as:

  • Taxpayer ID number (CPF for individuals, CNPJ for companies)
  • Email address
  • Cellular telephone number
  • Random key (a randomly generated alphanumeric string)
  • QR code (static or dynamic)

All Pix keys are registered with the Banco Central do Brasil (BCB), which maintains the Diretório de Identificadores de Contas Transacionais (DICT). This is a national registry and database of all Pix keys. Individual users can have up to five keys for each account they own. Institutional users can have up to 20 keys. Each key must be associated with only one bank account.

There are two ways to receive payments with Pix:

  • Share your Pix key
  • Generate and share a QR code
  • Use NFC mobile payment at a point of sale terminal

Random keys and QR codes

A random key is generated either by a commercial establishment or by an individual through a payment service provider (PSP). For example, it can be created by encrypting a phone number. A random key is useful when you don’t want to share personal data.

📘

Random keys are not transferable.

A QR code is a machine-readable label that contains data about a Pix transaction and its participants. QR codes can be static or dynamic. A static code is designed to be reusable and contains only the data necessary to complete a transaction. When using static QR code, the transaction amount must be provided manually. For dynamic QR codes, the amount and other details are included automatically.

Register a key

Request

{
  "bank_account": {
    "account_number": "112",
    "account_type": "CACC",
    "branch": "99",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "key": "[email protected]",
  "key_type": "EMAIL",
  "reason": "USER_REQUESTED"
}

Response

{
  "bank_account": {
    "account_number": "112",
    "account_type": "CACC",
    "branch": "99",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "creation_datetime": "2020-08-13T13:49:03Z",
  "key": "[email protected]",
  "key_type": "EMAIL",
  "open_claim_creation_datetime": "2020-08-13T13:49:03Z",
  "owner": {
    "document_number": "12345678900",
    "name": "John Doe",
    "trade_name": "John Doe company",
    "type": "LEGAL_PERSON"
  },
  "ownership_datetime": "2020-08-13T13:49:03Z",
  "reason": "USER_REQUESTED"
}
{
  "code": "EPIX0001",
  "details": "Details about the specific error",
  "message": "Some error message"
}

Claim a key

You use a key claim to manage the ownership of a key. There are two key claim types (determined by the type attribute):

  • Ownership – Transfers ownership of a key between individuals in the same or another bank.
  • Portability – Transfers ownership a key for the same individual to another bank.

The process looks like this:

  1. Notify the original bank that you want to transfer a key: Create a key claim.
  2. Original bank asks for confirmation: Confirm a key claim
    1. If no confirmation is received after seven days, the original bank proceeds with the transfer automatically.
    2. Cancel a claim in progress: Cancel a key claim.
  3. BCB receives this confirmation and contacts the receiving bank.
  4. Receiving bank acknowledges transfer.
  5. BCB notifies the original bank that the transfer is completed.
  6. Customer acknowledges the transfer: Confirm a key claim.

Request

{
  "key": "[email protected]",
  "key_type": "EMAIL"
}

Response

{
  "bank_account": {
    "account_number": "112",
    "account_type": "CACC",
    "branch": "99",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "creation_datetime": "2020-08-13T13:49:03Z",
  "end_to_end_id": "E3030629420200808195101608910248",
  "key": "[email protected]",
  "key_type": "EMAIL",
  "open_claim_creation_datetime": "2020-08-13T13:49:03Z",
  "owner": {
    "document_number": "12345678900",
    "name": "John Doe",
    "trade_name": "John Doe company",
    "type": "LEGAL_PERSON"
  },
  "ownership_datetime": "2020-08-13T13:49:03Z"
}
{
  "code": "EPIX0001",
  "details": "Details about the specific error",
  "message": "Some error message"
}

Get claims

Lists any open claims you already have at other banks.
GET /v1/pix/claims?type=[ownership] / [portability]

Execute a claim

Request

{
  "key": "[email protected]",
  "key_type": "EMAIL",
  "reason": "USER_REQUESTED"
}

Response

No Content
{
  "code": "EPIX0001",
  "details": "Details about the specific error",
  "message": "Some error message"
}

Validate keys

Key reconciliation is the process used to validate locally registered keys, using the Central Bank as the source of truth. To keep the national keys registry up to date, participants in the Pix network are obliged to perform local synchronization of all keys under their responsibility.

Before making the pix-out call, it is necessary to first call Validate a key. This endpoint validates a key locally (if requested by the owner) or through DICT (if requested by someone else). This call then returns the necessary information, along with the endToEndId that is assigned at the start of a Pix transaction.

🚧

Request key validation

All calls to this endpoint should be made only to initiate payments. The endpoint includes a step to trace who is requesting the key validation.

Active keys in the system are those that return an ACTIVE status.