--- title: "Create key entry" method: POST path: "/v2/pix/keys" tags: ["Keys"] --- # Create key entry `POST /v2/pix/keys` ## Request - Base URL: `https://sandbox.pismolabs.io/pix-dict` - URL: `https://sandbox.pismolabs.io/pix-dict/v2/pix/keys` - Auth: HTTP bearer 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 Pix key status changed event. For more information, refer to the [Pix instant payments](doc:pix-instant-payments) guide. ## Headers - `Authorization` string, required - `Idempotency-Key` string, required ## Request body - PresenterCreationRequest - `key` string, required: Value, based on a key's type, used to encrypt Pix key. - `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 - `bank_account` PresenterCreationBankAccount, required - `opening_datetime` string, date-time, required: Opening date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `name_type` 'REGISTRATION_NAME' | 'SOCIAL_NAME': Name type: * `REGISTRATION_NAME` - Name assigned at birth * `SOCIAL_NAME` - Preferred name, not necessarily `REGISTRATION_NAME` ## Response `201` Created - PresenterCreationResponse - `bank_account` PresenterBankAccount, required - `participant` string, required: Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value. - `account_number` string, required: Account number. - `account_type` 'CACC' | 'SLRY' | 'SVGS' | 'TRAN', required: Account type: `CACC` - Checking account `SVGS` - Savings account `TRAN` - Transactional account (Brazil only). Also known as "conta corrente" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. `SLRY` - Salary account. Employer deposits a fixed amount every month. - `branch` string, required: Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value. - `opening_datetime` string, date-time, required: Opening date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `creation_datetime` string, date-time, required: Creation datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `key` string, required: Value, based on a key's type, used to encrypt Pix key. - `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. - `owner` PresenterOwner, required - `document_number` string, required: A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits. - `name` string, required: Person's name - `type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights * `NATURAL_PERSON` - An entity, such as an organization or company. - `trade_name` string: Name under which the business operates. Not necessarily the same as the legal name. - `reason` 'USER_REQUESTED' | 'ACCOUNT_CLOSURE' | 'BRANCH_TRANSFER' | 'RECONCILIATION' | 'FRAUD' | 'DEFAULT_OPERATION' | 'RFB_VALIDATION', required: Reason for request - `request_id` string: Request ID - `ownership_datetime` string, date-time: Ownership date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `correlation_id` string, uuid: The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header. - `bacen_processed_datetime` string, 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_datetime` string, date-time: Claim requested date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `account_id` string: Pismo 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. ## Other responses - `202`: Accepted - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Resource Not Found - `409`: Conflict - `429`: Too many requests - `500`: Internal Server Error - `502`: Bad Gateway - `503`: Service Unavailable - `504`: Gateway Timeout --- [API](https://skmtc.dev/pismo/apis/instant-payments-pix-management.md) - [All operations](https://skmtc.dev/pismo/apis/instant-payments-pix-management/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/instant-payments-pix-management/revisions/eb540c289547?raw)