Delete PIX key

Deletes a PIX key by its value through BACEN DICT (signed deleteEntry), then removes this service’s own record of it, if it holds one. A key this service does not hold (for example one rebuilt by the participant’s VSync) is still deleted at BACEN. A held key under claim is rejected with 409 SPI-3006 before BACEN is called. When a claim freezes the key while the BACEN deletion is in flight, BACEN has removed the entry but this service keeps its record for the claim flow and answers 409 SPI-3007. A BACEN refusal such as EntryBlocked (judicial block) is relayed with its own token and HTTP status, and nothing local changes. BACEN’s own NotFound (the directory holds no entry for the key) is relayed the same way, as 404 with code NotFound; a 404 with code SPI-0010 is a not-found BACEN did not name.

DELETE /api/v1/dict/keys

Delete PIX key

cURL

curl --request DELETE \
  --url https://api.example.com/api/v1/dict/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "keyValue": "12345678901",
  "participantISPB": "12345678",
  "reason": "USER_REQUESTED",
  "requesterTaxId": "12345678901"
}
'

400

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Idempotency key, max 255 characters

Corpo

application/json

PIX key value to delete; a held key is deletable only while ACTIVE

keyValue · string · obrigatório

PIX key value identifying the key to delete, in its canonical format for the key type. At most 77 characters, the ceiling BACEN publishes on a DICT key.

Required string length: 1 - 77

Exemplo:

"12345678901"

participantISPB · string · obrigatório

ISPB of the participant the key is bound to. Must be the key's stored owning participant and a participant this deployment is authorized to act for; any other value is rejected.

Pattern: ^[0-9A-Z]{8}$

Exemplo:

"12345678"

reason · enum<string>

Deletion reason reported to BACEN, defaulting to USER_REQUESTED; the enum is the set deleteEntry accepts. FRAUD and RFB_VALIDATION are MANDATED by DICT 8.4 section 4.1 for a removal forced by incompatibility with the Receita Federal registry — FRAUD when the name divergence or the irregular CPF/CNPJ is fraud, RFB_VALIDATION in the other cases. ACCOUNT_CLOSURE, RECONCILIATION, FRAUD and RFB_VALIDATION are participant-initiated (sections 4.4/4.5): no end user asks, so requesterTaxId is not demanded for them.

Opções disponíveis: USER_REQUESTED, ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, RFB_VALIDATION

Exemplo:

"USER_REQUESTED"

requesterTaxId · string

CPF or CNPJ of the END USER asking for the removal. MANDATORY when reason is USER_REQUESTED (the default): DICT 8.4 section 4.2 obliges the PSP to check that the user requesting the exclusão is the user the key is bound to. Omitted for the PSP-initiated reasons — ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, RFB_VALIDATION — where no end user is asking; supplied on any of them it is still compared against the stored owner. A value that does not match the stored owner is refused with the same answer as an unauthorized participant, so this route cannot be used to discover who owns a key.

Exemplo:

"12345678901"

Resposta

204

No Content