Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Keys

Create key entry

Creates a new DICT key entry for the user.

The Banco Central do Brazil (BCB) maintains Pix keys in the Diretório de Identificadores de Contas Transacionais (DICT), a national Pix key registry and database.

On PSP timeout, a 202 Accepted with a key status = PROCESSING reponse is returned and the process continues asynchronously, eventually emitting a success or error event.

This endpoint generates a <a href="https://developers.pismo.io/events/docs/pix-dict-key-status-change-1" >Pix key status changed</a> event.

For more information, refer to the Pix instant payments guide.

post/v2/pix/keys

Headers

Authorizationstring required
Example:Bearer eyJhbGci...IUzUx

Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.

Idempotency-Keystring required

A unique ID to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.

Request body

keystring required

Pix key value.

key_type'CPF' | 'CNPJ' | 'PHONE' | 'EMAIL' | 'EVP' required

User information that can be used to create a Pix key:

  • CPF - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US.
  • CNPJ - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil
  • EMAIL - Email
  • PHONE - Phone number
  • EVP - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.
reason'USER_REQUESTED' | 'RECONCILIATION' required

Reason for entry creation

name_type'REGISTRATION_NAME' | 'SOCIAL_NAME'

Name type:

  • REGISTRATION_NAME - Name assigned at birth
  • SOCIAL_NAME - Preferred name, not necessarily REGISTRATION_NAME

Example request

{
  "key": "email@email.com",
  "key_type": "EMAIL",
  "reason": "USER_REQUESTED",
  "bank_account": {
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "name_type": "SOCIAL_NAME"
}

Response

Created

creation_datetimestring date-time required

Creation datetime. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

keystring required

Pix key value.

key_type'CPF' | 'CNPJ' | 'PHONE' | 'EMAIL' | 'EVP' required

User information that can be used to create a Pix key:

  • CPF - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US.
  • CNPJ - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil
  • EMAIL - Email
  • PHONE - Phone number
  • EVP - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.
reasonstring required

Reason that indicates why the card was added to the Protection Bulletin.

request_idstring

Request ID

ownership_datetimestring date-time

Ownership date time. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

correlation_idstring

The Correlation identifier field is used to link related API requests and events. The CID can help the Pismo engineering team track everything related to a call. If not passed, a random one is generated. You can find the CID in the response header.

bacen_processed_datetimestring date-time

Banco Central do Brasil (Central Bank of Brazil) processed datetime. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

claim_requested_datetimestring date-time

Claim requested date time. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

account_idinteger

Account ID

status'ACTIVE' | 'DELETED' | 'PROCESSING'

Key status:

  • ACTIVE - Key is active
  • DELETED - Key was removed
  • PROCESSING - An error occurred during the request to the PSP. The process continues asynchronously in this case.

Example response

{
  "bank_account": {
    "participant": "00115678",
    "account_number": "98765432",
    "account_type": "TRAN",
    "branch": "011",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "creation_datetime": "2020-08-13T13:49:03Z",
  "key": "email@email.com",
  "key_type": "EMAIL",
  "owner": {
    "document_number": "7777888hh",
    "name": "Jerry Atrick",
    "type": "NATURAL_PERSON",
    "trade_name": "Acme Widgets"
  },
  "reason": "L",
  "request_id": "8bfde840-bef5-42b7-bef2-350475ffb9e1",
  "ownership_datetime": "2020-08-13T13:49:03Z",
  "correlation_id": "c737895c-8159-4c0c-a92a-a4f8600bff37",
  "bacen_processed_datetime": "2020-08-13T13:49:03Z",
  "claim_requested_datetime": "2020-08-13T13:49:03Z",
  "account_id": 6912345
}