Delete PIX key

Deletes a PIX key by its value. Only ACTIVE or INACTIVE keys can be deleted. Keys under claim or pending BACEN sync are rejected. A key under a BCB judicial block is refused with the EntryBlocked token and HTTP 400, the same answer BACEN gives (DICT 8.4 section 1.1).

DELETE /api/v1/dict/keys

Delete PIX key

cURL

curl --request DELETE \
  --url https://spi.sandbox.lerian.net/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"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key, max 255 characters

Body

application/json

PIX key value to delete; only ACTIVE or INACTIVE keys are deletable

keyValue · string · required

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

Example:

"12345678901"

participantISPB · string · required

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-9]{8}$

Example:

"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.

Available options: USER_REQUESTED, ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, RFB_VALIDATION

Example:

"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, and the DICT re-checks it ("chave deve pertencer ao usuário que solicitou a exclusão"). 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.

Example:

"12345678901"

Response

204

No Content