Managing Pix keys [beta]

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 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. The endpoint is /v1/pix/claims. There are two key claim types:

  • 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 (POST /v1/pix/claims).
  2. Original bank asks for confirmation (POST /v1/pix/claims/confirm).
    1. If no confirmation is received after seven days, the original bank proceeds with the transfer automatically.
    2. Cancel a claim in progress (POST /v1/pix/claims/cancel).
  3. BCB receives this confirmation and contacts the receiving bank.
  4. Receiving bank acknowledges this.
  5. BCB notifies the original bank that the transfer is completed.
  6. Customer acknowledges the transfer (POST /v1/pix/claims/complete).

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 /v1/pix/keys/validate to validate the key. This endpoint /v1/pix/keys/validate validates a key locally (if we hold the ownership of it) or directly in DICT (if it is owned by someone else). This call then returns the necessary information, along with the endToEndId that is assigned at the start of a Pix transaction.

🚧

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

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


Did this page help you?