Create PIX key claim

POST

/order/v1/banking/accounts/{accountId}/keys/claims

• Production
• Sandbox

Request a PIX key claim (PORTABILITY or CLAIM_OWNERSHIP) for a key not currently linked to this account. Used when this account is the one requesting the key (claimer side). For EMAIL and PHONE keys, this starts a confirmation flow instead of requesting the claim right away: the response comes back as PENDING and a confirmation code is sent to the claimed target, proving the requester currently controls that contact. Call POST :accountId/keys/claims/confirm with the returned validationId and the code to finish requesting the claim. CPF and CNPJ claims are requested immediately, without OTP.

Authorizations

• Bearer

Parameters

Path Parameters

accountId

required

string format: uuid

Identifier of the account

Header Parameters

idempotency-key

required

string format: uuid

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body ^required

object

claimType

required

Type of claim. PORTABILITY moves an existing key from another PSP into this account. CLAIM_OWNERSHIP disputes the ownership of a key already registered elsewhere.

string

Allowed values: PORTABILITY CLAIM_OWNERSHIP

Example

PORTABILITY

type

required

Type of the PIX key being claimed. RANDOM keys cannot be claimed.

string

Allowed values: CPF CNPJ EMAIL PHONE

Example

EMAIL

key

required

PIX key value being claimed

string

Example

[email protected]

Responses

200

The resource was returned successfully

object

claimId

required

Identifier of the claim, used on subsequent operations.

string

Example

a8f2b9c4-1e6a-4c3f-9d7b-2a1e8f9c5d10

status

required

Status of the claim

string

Example

PENDING

201

Validation started for EMAIL/PHONE claims; call the confirm endpoint next.

object

validationId

required

Identifier of the validation. Must be sent back on the confirm endpoint.

string

Example

a8f2b9c4-1e6a-4c3f-9d7b-2a1e8f9c5d10

status

required

Status of the validation

string

Example

PENDING

expiresAt

required

Expiration date of the confirmation code

string

Example

2025-12-18T10:15:30Z

400

object

error

string

Example

INVALID_REQUEST

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[
  {
    "field": "field_name",
    "issue": "INVALID",
    "description": "Field is invalid"
  }
]

401

Unauthorized Request

object

error

string

Example

UNAUTHORIZED

message

string

Example

Unauthorized Request

details

Array<object>

object

field

string

issue

string

description

string

Example

[]

500

object

error

string

Example

INTERNAL_ERROR

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[]