Cancel a PIX key claim

curl --request DELETE \
  --url https://api.example.com/v1/claims/{claimId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "key": "11122233300",
  "ispb": "12345678"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/claims/{claimId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"key\": \"11122233300\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("DELETE", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'DELETE',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({accountId: 'acc-123', key: '11122233300', ispb: '12345678'})
};

fetch('https://api.example.com/v1/claims/{claimId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/claims/{claimId}"

payload = {
    "accountId": "acc-123",
    "key": "11122233300",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

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

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

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. The claim must resolve to a local row for the pair (claimId, your account), else 404 PIX-0020.

What reaches DICT depends on how far the claim got, and the counterparty can tell the difference. A row at status 5, 6 or 7 is live at DICT and is cancelled there. Anything else - notably status 4, recognised as claimable but never opened at DICT - is cancelled locally with NO DICT call, which is the fail-closed direction, because a spurious DICT cancel is the step that has no undo. The motivo follows the §8.2.11 matrix for the side and the claim type: a claimer (status 5 or 7) sends 0 = Solicitação do Usuário; a DONOR (status 6) sends 0 for a portability claim but 4 = Fraude for a possession claim, because 4 is the only value the Posse-Doador column accepts - so a possession refusal is recorded at Bacen as fraud rather than as a preference.

Either way the key row ends CANCELLED (-1) and soft-deleted. CANCELLED is terminal - the state machine has no edge out of it - so the claim cannot be revived; start over with POST /v1/entries followed by POST /v1/claims.

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. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

DELETE

claims

{claimId}

Cancel a PIX key claim

curl --request DELETE \
  --url https://api.example.com/v1/claims/{claimId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "key": "11122233300",
  "ispb": "12345678"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/claims/{claimId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"key\": \"11122233300\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("DELETE", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'DELETE',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({accountId: 'acc-123', key: '11122233300', ispb: '12345678'})
};

fetch('https://api.example.com/v1/claims/{claimId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/claims/{claimId}"

payload = {
    "accountId": "acc-123",
    "key": "11122233300",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

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

{
  "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"
  }
}

{
  "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"
  }
}

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

Path Parameters

claimId

string

required

The claim id.

Example:

"claim-123"

Body

application/json

accountId

string

required

The CRM account id of the caller.

Example:

"acc-123"

key

string

required

The PIX key the claim targets.

Example:

"11122233300"

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

Example:

"12345678"

Response

claimId

string

required

The claim id.

Example:

"claim-123"

status

string

required

Human-readable eKeyStatus label.

Example:

"DONATED"

Direct participant APIs

Indirect participant APIs

Cancel a PIX key claim

Authorizations

Path Parameters

Body

Response