Cancel a PIX key claim

Abandons a claim. Either side may call it - the claimer giving up, or the holder refusing to hand the key over (§8.2.11). claimId is in the path; the body carries key and accountId.

A CLAIMER is the caller whose local row carries the claimId. A row at status 5 or 7 is live at DICT and is cancelled there with reason 0; anything else - notably status 4, recognised as claimable but never opened at DICT - is cancelled locally with NO DICT call, the fail-closed direction, because a spurious DICT cancel has no undo; and a row that cannot be cancelled (an ACTIVE row of a concluded claim) is 422 PIX-0073. The row ends CANCELLED (-1) and soft-deleted.

A HOLDER (DONOR) has no such row: the claim is read from DICT first (§8.2.15) and must be one this account answers as holder, else 404 PIX-0020, on a key that is the caller’s, else 404 PIX-0069. It is refusable while open (situation 0 or 1) and, for a possession claim, while Confirmed until its conclusion deadline; otherwise 422 PIX-0073. One DICT already holds Cancelled by the holder (or with no canceller stated) is a retry answered 200 without cancelling again. The reason follows the §8.2.11 matrix for the claim type DICT states: 0 for portability, 4 = fraud for possession, the only value the Posse-Doador column accepts. Refusing a possession claim is therefore a fraud statement the holder must make explicitly: without fraudDeclared=true it is 400 PIX-0061 naming fraudDeclared, after the claim is read and before anything is sent to DICT; the field is ignored on a portability refusal and on a claimer cancellation. The holder KEEPS the key: its row returns to (or stays) ACTIVE and is never deleted.

Which of this deployment’s direct participants writes to the national directory is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

DELETE /v1/claims/{claimId}

Cancel a PIX key claim

cURL

curl --request DELETE \
  --url https://api.example.com/v1/claims/{claimId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "key": "11122233300",
  "fraudDeclared": true,
  "ispb": "12345678"
}
'

200

{
  "claimId": "claim-123",
  "status": "DONATED"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

claimId · string · required

The claim id.

Example:

"claim-123"

Body

application/json

accountId · string · required

The Midaz ledger account id of the caller.

Example:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

key · string · required

The PIX key the claim targets.

Example:

"11122233300"

fraudDeclared · boolean

The holder's (donor's) declaration that the POSSESSION claim it refuses is fraudulent. REQUIRED true when refusing a possession claim as holder: §8.2.11 accepts only reason 4 (fraud) from a possession holder, so that refusal is a fraud statement sent to Bacen, and without it the request is 400 PIX-0061 naming fraudDeclared, before anything is sent to DICT. IGNORED when refusing a portability claim (reason 0) and on every claimer cancellation. Optional; absent reads as false.

Example:

true

ispb · string

The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

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

Example:

"12345678"

Response

200

application/json

OK

claimId · string · required

The claim id.

Example:

"claim-123"

status · string · required

Human-readable eKeyStatus label.

Example:

"DONATED"