Sign in

v1

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

Update key entry

Update the DICT key entry.

On PSP timeout, a 202 Accepted response with a key status = PROCESSING 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.

patch/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' | 'BRANCH_TRANSFER' | 'RECONCILIATION' | 'RFB_VALIDATION' required

Reason for request

  • USER_REQUESTED - EVP keys are not supported
name_type'REGISTRATION_NAME' | 'SOCIAL_NAME'

Name type:

  • REGISTRATION_NAME - Name assigned at birth
  • SOCIAL_NAME - Preferred name, not necessarily REGISTRATION_NAME (not supported when key owner is a LEGAL_PERSON)

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

OK

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.

open_claim_creation_datetimestring date-time

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

ownership_datetimestring date-time

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

account_idinteger

Account ID

content_idstring

Content ID. This is a hashed value created from a number of key-related fields in the Pismo database. This is meant for you to store and send to Pismo in case there is any problem with the key.

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.

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",
  "open_claim_creation_datetime": "2020-08-13T13:49:03Z",
  "ownership_datetime": "2020-08-13T13:49:03Z",
  "account_id": 6912345,
  "content_id": "4a46173b40f861f769ea00ef14aea3d3b7e12f730a7caba61c7fbbe437c1da65",
  "correlation_id": "c737895c-8159-4c0c-a92a-a4f8600bff37"
}