---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# 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 Pix key status changed event.
For more information, refer to the [Pix instant payments](doc:pix-instant-payments) guide.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Pix management",
"description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
},
"version": "0.0.1"
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/pix-dict",
"description": "Sandbox API server for testing."
}
],
"tags": [
{
"name": "Keys",
"description": "Manage DICT keys endpoints"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
},
"IdempotencyKeyHeader": {
"name": "Idempotency-Key",
"in": "header",
"description": "A unique UUID identifier 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.\n",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
},
"headers": {
"XCidResponseHeader": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"schemas": {
"AccountID": {
"type": "string",
"description": "Pismo account ID",
"example": "8675309"
},
"AccountNumber": {
"type": "string",
"description": "Account number.",
"maxLength": 20,
"example": "98765432"
},
"AccountType": {
"type": "string",
"enum": [
"CACC",
"SLRY",
"SVGS",
"TRAN"
],
"maxLength": 4,
"description": "Account type: \n `CACC` - Checking account\n `SVGS` - Savings account\n `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. \n `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
"example": "TRAN"
},
"BacenProcessedDatetime": {
"type": "string",
"description": "Banco Central do Brasil (Central Bank of Brazil) processed datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
"format": "date-time",
"example": "2020-08-13T13:49:03Z"
},
"Branch": {
"type": "string",
"description": "Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"example": "011"
},
"ClaimRequestedDatetime": {
"type": "string",
"description": "Claim requested date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
"format": "date-time",
"example": "2020-08-13T13:49:03Z"
},
"CorrelationID": {
"type": "string",
"format": "uuid",
"description": "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.\n",
"example": "ea8bc045-9ff7-439f-a318-2e6f974707a5"
},
"CreationDatetime": {
"type": "string",
"description": "Creation datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
"format": "date-time",
"example": "2020-08-13T13:49:03Z"
},
"DocumentNumber": {
"type": "string",
"description": "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.\n",
"minLength": 11,
"maxLength": 14,
"example": "123412341234"
},
"Key": {
"type": "string",
"description": "Value, based on a key's type, used to encrypt Pix key.",
"maxLength": 77,
"example": "al_fresco@bourdain.com"
},
"KeyStatus": {
"type": "string",
"description": "Key status: \n * `ACTIVE` - Key is active\n * `DELETED` - Key was removed\n * `PROCESSING` - An error occurred during the request to the PSP. The process continues asynchronously in this case.\n",
"enum": [
"ACTIVE",
"DELETED",
"PROCESSING"
]
},
"KeyType": {
"type": "string",
"description": "User information that can be used to create a Pix key:\n* `CPF` - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US. \n* `CNPJ` - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil\n* `EMAIL` - Email \n* `PHONE` - Phone number\n* `EVP` - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.\n",
"enum": [
"CPF",
"CNPJ",
"PHONE",
"EMAIL",
"EVP"
],
"example": "EMAIL"
},
"message.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.PayloadMessage"
}
}
}
},
"message.ExternalMessage": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.Message": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "EPDA0001"
},
"details": {
"$ref": "#/components/schemas/message.DetailMessage"
},
"message": {
"type": "string",
"description": "Error message",
"example": "User not found"
}
}
},
"message.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Parameter in error",
"example": "query parameter"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Field in error",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Error messsage",
"example": "Generic error"
}
}
},
"NameType": {
"type": "string",
"description": "Name type: \n * `REGISTRATION_NAME` - Name assigned at birth \n * `SOCIAL_NAME` - Preferred name, not necessarily `REGISTRATION_NAME`\n",
"enum": [
"REGISTRATION_NAME",
"SOCIAL_NAME"
],
"example": "SOCIAL_NAME"
},
"OpeningDatetime": {
"type": "string",
"description": "Opening date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
"format": "date-time",
"example": "2020-08-13T13:49:03Z"
},
"OwnershipDatetime": {
"type": "string",
"description": "Ownership date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
"format": "date-time",
"example": "2020-08-13T13:49:03Z"
},
"Participant": {
"type": "string",
"description": "Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"maxLength": 8,
"example": "00115678"
},
"PersonName": {
"type": "string",
"description": "Person's name",
"maxLength": 100,
"example": "Jerry Atrick"
},
"PersonType": {
"type": "string",
"description": "Person type: \n* `LEGAL_PERSON` - An actual person with legal rights\n* `NATURAL_PERSON` - An entity, such as an organization or company.\n",
"enum": [
"LEGAL_PERSON",
"NATURAL_PERSON"
],
"example": "NATURAL_PERSON"
},
"presenter.BankAccount": {
"type": "object",
"required": [
"participant",
"account_number",
"account_type",
"branch",
"opening_datetime"
],
"properties": {
"participant": {
"$ref": "#/components/schemas/Participant"
},
"account_number": {
"$ref": "#/components/schemas/AccountNumber"
},
"account_type": {
"$ref": "#/components/schemas/AccountType"
},
"branch": {
"$ref": "#/components/schemas/Branch"
},
"opening_datetime": {
"$ref": "#/components/schemas/OpeningDatetime"
}
}
},
"presenter.CreationBankAccount": {
"type": "object",
"required": [
"opening_datetime"
],
"properties": {
"opening_datetime": {
"$ref": "#/components/schemas/OpeningDatetime"
}
}
},
"presenter.CreationRequest": {
"type": "object",
"required": [
"key",
"key_type",
"reason",
"bank_account"
],
"properties": {
"key": {
"$ref": "#/components/schemas/Key"
},
"key_type": {
"$ref": "#/components/schemas/KeyType"
},
"reason": {
"$ref": "#/components/schemas/EntryCreationReason"
},
"bank_account": {
"$ref": "#/components/schemas/presenter.CreationBankAccount"
},
"name_type": {
"$ref": "#/components/schemas/NameType"
}
}
},
"presenter.CreationResponse": {
"type": "object",
"required": [
"bank_account",
"creation_datetime",
"key",
"key_type",
"owner",
"reason"
],
"properties": {
"bank_account": {
"$ref": "#/components/schemas/presenter.BankAccount"
},
"creation_datetime": {
"$ref": "#/components/schemas/CreationDatetime"
},
"key": {
"$ref": "#/components/schemas/Key"
},
"key_type": {
"$ref": "#/components/schemas/KeyType"
},
"owner": {
"$ref": "#/components/schemas/presenter.Owner"
},
"reason": {
"$ref": "#/components/schemas/Reason"
},
"request_id": {
"type": "string",
"description": "Request ID",
"example": "8bfde840-bef5-42b7-bef2-350475ffb9e1"
},
"ownership_datetime": {
"$ref": "#/components/schemas/OwnershipDatetime"
},
"correlation_id": {
"$ref": "#/components/schemas/CorrelationID"
},
"bacen_processed_datetime": {
"$ref": "#/components/schemas/BacenProcessedDatetime"
},
"claim_requested_datetime": {
"$ref": "#/components/schemas/ClaimRequestedDatetime"
},
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"status": {
"$ref": "#/components/schemas/KeyStatus"
}
}
},
"presenter.Owner": {
"type": "object",
"required": [
"document_number",
"name",
"type"
],
"properties": {
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"name": {
"$ref": "#/components/schemas/PersonName"
},
"type": {
"$ref": "#/components/schemas/PersonType"
},
"trade_name": {
"$ref": "#/components/schemas/TradeName"
}
}
},
"EntryCreationReason": {
"type": "string",
"description": "Reason for entry creation",
"example": "USER_REQUESTED",
"enum": [
"USER_REQUESTED",
"RECONCILIATION"
]
},
"Reason": {
"type": "string",
"description": "Reason for request",
"example": "USER_REQUESTED",
"enum": [
"USER_REQUESTED",
"ACCOUNT_CLOSURE",
"BRANCH_TRANSFER",
"RECONCILIATION",
"FRAUD",
"DEFAULT_OPERATION",
"RFB_VALIDATION"
]
},
"TradeName": {
"type": "string",
"description": "Name under which the business operates. Not necessarily the same as the legal name.",
"maxLength": 100,
"example": "Acme Widgets"
}
},
"responses": {
"202Accepted": {
"description": "Accepted",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Request accepted and will processed async": {
"value": {
"code": "EPDA0169",
"message": "Request was accepted and gonna be processed asynchronously"
}
}
}
}
}
},
"401Unauthorized": {
"description": "Unauthorized",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service error": {
"value": {
"code": "EPDG0013",
"message": "Unauthorized access to the provider service"
}
}
}
}
}
},
"403Forbidden": {
"description": "Forbidden",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"EPDA0009": {
"summary": "Missing required header 'x-tenant'",
"value": {
"code": "EPDA0009",
"message": "Missing required header 'x-tenant'"
}
},
"EPDA0010": {
"summary": "Missing required header 'x-account-id'",
"value": {
"code": "EPDA0010",
"message": "Missing required header 'x-account-id'"
}
},
"EPDA0152": {
"summary": "Missing required param 'id'",
"value": {
"code": "EPDA0152",
"message": "Missing required param 'id'"
}
}
}
}
}
},
"429TooManyRequests": {
"description": "Too many requests",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
}
}
}
},
"502BadGateway": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider authentication service error": {
"value": {
"code": "EPDG0020",
"message": "Provider authentication service is unable to complete the request"
}
}
}
}
}
},
"504GatewayTimeout2": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Service timeout": {
"value": {
"code": "EPDA0000",
"message": "Timeout while executing the request"
}
},
"Provider timeout": {
"value": {
"code": "EPDG0000",
"message": "Timeout while executing the request"
}
}
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
],
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-enabled": true
},
"paths": {
"/v2/pix/keys": {
"post": {
"summary": "Create key entry",
"description": "Creates a new DICT key entry for the user.\n\nThe 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.\n\nOn 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.\n\nThis endpoint generates a Pix key status changed event. \n\nFor more information, refer to the [Pix instant payments](https://developers.pismo.io/pismo-docs/docs/pix-instant-payments) guide.\n",
"operationId": "post-v2-pix-keys-create",
"tags": [
"Keys"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
}
],
"requestBody": {
"description": "Create a new key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/presenter.CreationRequest"
},
"examples": {
"Create Key": {
"value": {
"bank_account": {
"opening_datetime": "2020-08-13T13:49:03Z"
},
"key": "email@email.com",
"key_type": "EMAIL",
"reason": "USER_REQUESTED"
}
},
"Create Key EVP": {
"value": {
"bank_account": {
"opening_datetime": "2020-08-13T13:49:03Z"
},
"key": "8d33a43c-0d22-4974-9652-30c80f2d6b0e",
"key_type": "EVP",
"reason": "USER_REQUESTED"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/presenter.CreationResponse"
}
}
}
},
"202": {
"$ref": "#/components/responses/202Accepted"
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Invalid binding": {
"value": {
"code": "EPDA0002",
"message": "Failed to unmarshal request body"
}
},
"Validate errors": {
"value": {
"code": "EPDA0003",
"message": "There are invalid fields when trying to validate request body",
"details": {
"payload": [
{
"field": "DeleteKeyRequest.reason",
"message": "Field validation for 'reason' failed on the 'oneof' tag"
}
]
}
}
},
"Invalid key type create": {
"summary": "Invalid Key Type",
"value": {
"code": "EPDA0038",
"message": "Invalid Key Type"
}
},
"Invalid cpf create": {
"summary": "Invalid CPF",
"value": {
"code": "EPDA0039",
"message": "Invalid CPF"
}
},
"Invalid cnpj create": {
"summary": "Invalid CNPJ",
"value": {
"code": "EPDA0040",
"message": "Invalid CNPJ"
}
},
"Invalid phone create": {
"summary": "Invalid PHONE",
"value": {
"code": "EPDA0041",
"message": "Invalid PHONE"
}
},
"Invalid email create": {
"summary": "Invalid EMAIL",
"value": {
"code": "EPDA0042",
"message": "Invalid EMAIL"
}
},
"Invalid evp create": {
"summary": "Invalid EVP",
"value": {
"code": "EPDA0043",
"message": "Invalid EVP"
}
},
"Missing tenant header": {
"value": {
"code": "EPDG0001",
"message": "Missing x-tenant header"
}
},
"Provider service error request": {
"value": {
"code": "EPDG0011",
"message": "Bad request while accessing the provider service",
"details": {
"external": [
{
"code": "PBE353",
"message": "Entity not found"
}
]
}
}
},
"Invalid provider service response": {
"value": {
"code": "EPDG0018",
"message": "Provider service returned a status {http_status} which was not expected"
}
},
"Provider authentication service error request": {
"value": {
"code": "EPDG0019",
"message": "Provider authentication service rejected request due to a client payload misconfiguration"
}
},
"Entry owned by different person": {
"summary": "Entry owned by different person",
"value": {
"code": "EPDG0035",
"message": "Entry owned by different person"
}
},
"Entry owned by same person but different participant": {
"summary": "Entry owned by same person, but with different participant",
"value": {
"code": "EPDG0036",
"message": "Entry owned by same person, but with different participant"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"description": "Resource Not Found",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Participant not found create": {
"summary": "Participant Not Found",
"value": {
"code": "EPDA0023",
"message": "Participant not found for org {orgId}"
}
},
"Account not found create": {
"summary": "Account Not Found",
"value": {
"code": "EPDA0024",
"message": "Account not found for ID {accountId}"
}
},
"Provider service error": {
"value": {
"code": "EPDG0014",
"message": "Resource not found on the provider service",
"details": {
"external": [
{
"code": "PBE353",
"message": "Entity not found"
}
]
}
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Key exists create": {
"summary": "Key already exists in database",
"value": {
"code": "EPDA0025",
"message": "Key already exists in database"
}
},
"Account blocked cancelled create": {
"summary": "Account status blocked or cancelled",
"value": {
"code": "EPDA0028",
"message": "Account status blocked or cancelled"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/429TooManyRequests"
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service communication error": {
"value": {
"code": "EPDA0029",
"message": "Internal errors while attempting to communicate with the provider service"
}
},
"Invalid client error": {
"value": {
"code": "EPDG0005",
"message": "Invalid Pix provider '{provider_name}'"
}
},
"Failed marshalling object": {
"value": {
"code": "EPDG0006",
"message": "Failed to marshal JSON object"
}
},
"Failed unmarshalling object": {
"value": {
"code": "EPDG0007",
"message": "Failed to unmarshal JSON object"
}
},
"Error reading response data": {
"value": {
"code": "EPDG0010",
"message": "I/O error while reading response data: '{details}'"
}
},
"Provider service error": {
"value": {
"code": "EPDG0016",
"message": "Provider service returned an internal error while trying to access the resource",
"details": {
"external": [
{
"code": "PBE315",
"message": "Generic error"
}
]
}
}
}
}
}
}
},
"502": {
"$ref": "#/components/responses/502BadGateway"
},
"503": {
"description": "Service Unavailable",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service unavailable": {
"value": {
"code": "EPDG0017",
"message": "Provider service resource is unavailable"
}
},
"Provider authentication service unavailable": {
"value": {
"code": "EPDG0021",
"message": "Provider authentication service is unavailable"
}
}
}
}
}
},
"504": {
"$ref": "#/components/responses/504GatewayTimeout2"
}
}
}
}
}
}
```