Confirm PIX key ownership

curl --request POST \
  --url https://api.example.com/v1/entries/{entryId}/confirmation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "token": "123456",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/entries/{entryId}/confirmation"

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

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({accountId: 'acc-123', token: '123456', ispb: '12345678'})
};

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

import requests

url = "https://api.example.com/v1/entries/{entryId}/confirmation"

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

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

print(response.text)

{
  "key": "11122233300",
  "keyType": 4,
  "status": 1,
  "statusDescription": "ACTIVE"
}

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

Confirm PIX key ownership

Confirms ownership of an EMAIL or PHONE key with the 6-digit code POST /v1/entries delivered. entryId is the key VALUE, URL-encoded; the body carries token and accountId. On success the key is registered at DICT and the local row becomes FINALIZED (0); if that registration comes back claim-pending instead, the response carries THAT status and no key was bound.

The route is dual-purpose, and the second purpose runs FIRST and ignores the code entirely: if DICT reports a CONFIRMED claim on this key - the holder has already agreed to give it away - the service concludes that claim at DICT (§8.2.12), soft-deletes the local pending row, and answers 200 with an EMPTY CreateEntryResponse - the JSON object , because every field is omitempty - and NOT an absent body. A generated client deserializes it normally; what it reads is every field unset, which is the signal that this branch ran and no key was bound here. That conclusion is irreversible, so a caller expecting a rejected code can find the transfer completed instead.

Otherwise the code decides. It is matched by hash, so a code that fits no pending row of this account is 401 PIX-0059 - the same answer as a missing code, with nothing in the response distinguishing the two. A row that is not awaiting confirmation is 422 PIX-0073.

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.

POST

entries

{entryId}

confirmation

Confirm PIX key ownership

curl --request POST \
  --url https://api.example.com/v1/entries/{entryId}/confirmation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "token": "123456",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/entries/{entryId}/confirmation"

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

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({accountId: 'acc-123', token: '123456', ispb: '12345678'})
};

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

import requests

url = "https://api.example.com/v1/entries/{entryId}/confirmation"

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

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

print(response.text)

{
  "key": "11122233300",
  "keyType": 4,
  "status": 1,
  "statusDescription": "ACTIVE"
}

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

entryId

string

required

The PIX key value (URL-encoded).

Example:

"foo@bar.com"

Body

application/json

accountId

string

required

The CRM account id of the key owner.

Example:

"acc-123"

token

string

required

The OTP ownership-confirmation code.

Example:

"123456"

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

key

string

The PIX key value.

Example:

"11122233300"

keyType

integer<int64>

Numeric eKeyType.

Example:

4

status

integer<int64>

Numeric eKeyStatus.

Example:

1

statusDescription

string

Human-readable eKeyStatus label.

Example:

"ACTIVE"

Direct participant APIs

Indirect participant APIs

Confirm PIX key ownership

Authorizations

Path Parameters

Body

Response