Skip to main content
POST
Confirm a Pix key claim
This can’t be undone. To keep the key, cancel the claim instead. If the bank throttles the request, you get a 429: wait and retry. Only an organization admin can confirm a claim.

Headers

x-environment
enum<string>

Environment of the claim: LIVE (production) or TEST (sandbox). When you omit it, TEST is used; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization.

Format: UUID

id
string<uuid>
required

ID of the claim — its id field, not its _id.

Format: UUID

Response

Successful response

A claim another institution opened, on behalf of one of its customers, for a Pix key registered in one of your wallets. With a portability claim the key's owner wants to move it to their account at the other institution; with an ownership claim someone else says the key (an e-mail address or a phone number) is theirs.

_id
string
required

Internal ID of the record. To confirm or cancel the claim, use id.

Example:

"672a0c4fb4d3e80012c9a6b2"

id
string
required

ID of the claim in the Pix directory — use it as id to confirm or cancel the claim.

Example:

"3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13"

realmId
string
required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string
required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the wallet that holds the claimed key.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment
enum<string>
required

Environment of the claim: LIVE or TEST.

Available options:
LIVE,
TEST
Example:

"LIVE"

key
string
required

The claimed key, as registered.

Example:

"12345678000190"

keyType
string
required

Kind of the claimed key: CNPJ, CPF, EMAIL or PHONE.

Example:

"CNPJ"

type
string
required

portability (the key's owner moves it to another institution) or ownership (someone else says the key is theirs).

Example:

"portability"

status
string
required

Status of the claim, as last notified:

  • waiting — waiting for your answer: confirm or cancel it before resolutionPeriodEnd.
  • processing_confirm — your confirmation is being processed.
  • confirmed — the claim was confirmed: the key is released to the claimer. It is marked REMOVED in your wallet when the Pix directory notifies the confirmation, which can come after the confirmation's response.
  • completed — the claimer's institution finished moving the key.
  • canceled — the claim was cancelled: the key stays in your wallet.

Other values the Pix directory defines may appear. A waiting claim past resolutionPeriodEnd may have been settled without a notification reaching us.

Example:

"waiting"

claimer
object
required

Who claims the key.

claimerAccount
object
required

The account the claimer wants the key to point to, at the other institution.

donorBankIspb
number
required

ISPB code of the institution that holds the key today — Portão 3's banking partner.

Example:

12345678

external
object
required

The claimed key's account identifiers at Portão 3's banking partner.

insertedAt
string
required

When the claim was opened in the Pix directory (UTC, without a time zone suffix).

Example:

"2026-11-03T23:25:04"

resolutionPeriodEnd
string
required

Deadline to confirm or cancel the claim (ISO 8601, UTC).

Example:

"2026-11-10T23:25:04Z"

createdAt
string
required

When we received the claim (ISO 8601).

Example:

"2026-11-03T23:25:06.013Z"

updatedAt
string
required

When the record was last updated, as text in English with the time zone spelled out — not ISO 8601.

Example:

"Tue Nov 03 2026 23:25:06 GMT+0000 (Coordinated Universal Time)"

__v
number
required

Internal version of the record.

Example:

0

completionPeriodEnd
string | null

Deadline for the claim to be completed (ISO 8601, UTC), when the claim already carried one as it reached us — not updated afterwards. null or absent on most claims.

Example:

null

cancelReason
string | null

Reason the claim was cancelled, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null

canceledBy
string | null

Who cancelled the claim, when the claim carried it as it reached us — not updated afterwards. null or absent: no claim received so far carried it.

Example:

null

confirmReason
string | null

Reason the claim was confirmed, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null

errorReason
string | null

Error reported for the claim, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null