PIX Key Claims

Welcome to the PIX Key Claims documentation. This guide provides a comprehensive overview of how to claim ownership or request portability of PIX keys registered in the Brazilian DICT (Diretório de Identificadores de Contas Transacionais).

What is PIX Key Claim?

PIX Key Claim is the process of claiming ownership or requesting portability of a PIX key that is already registered in DICT. This mechanism allows users to:

Transfer a key between accounts at the same institution (portability)
Claim ownership of a key registered by another person
Recover keys that were incorrectly registered
Migrate keys between different PSPs (Payment Service Providers)

Claim Types

Our API supports two types of PIX key claims:

Portability Claim

Use Case: Transfer a PIX key from one account to another within the same CPF/CNPJ (same owner).

Scenario Example:

User has a PIX key registered at PSP "A"
User opens an account at PSP "B"
User wants to transfer the same key to PSP "B"
The key owner (CPF/CNPJ) remains the same

Workflow:

Claimer (new PSP) initiates the claim
Donor (current PSP) receives notification
Donor can confirm or wait for automatic resolution (7 days)
Once confirmed, key is automatically transferred to the new PSP

Key Types Allowed:

Phone number
Email
CPF
CNPJ

📘
Email keys can only be used for portability claims, not ownership claims.

Ownership Claim

Use Case: Claim a PIX key that is registered with a different CPF/CNPJ (different owner).

Scenario Example:

A phone number is registered to person "A"
Person "B" now owns the phone number
Person "B" wants to claim ownership of the key

Workflow:

Claimer (new owner) initiates the claim
Donor (current owner) receives notification
Donor must confirm the claim (required action)
After donor confirmation, claimer must conclude the process with OTP verification
Once concluded, key ownership is transferred

Key Types Allowed:

Phone number
CPF
CNPJ

📘
Email and EVP (random) keys cannot be used for ownership claims.

Key Types for Claims

Supported Key Types

Key Type	Portability Claim	Ownership Claim	Notes
Phone Number	✅ Yes	✅ Yes	Format: +5511999999999
Email	✅ Yes	❌ No	Email keys can only be transferred between same owner
CPF	✅ Yes	✅ Yes	11 digits, no formatting
CNPJ	✅ Yes	✅ Yes	14 digits, no formatting
EVP (Random Key)	❌ No	❌ No	Random keys cannot be claimed - user must create a new one

Verification Requirements

Different key types require different verification methods:

For Phone Number and Email (Portability Claims):

Requires OTP verification (verification_request_id + token)
Verification purpose: CLAIM_INCLUSION

For Phone Number (Ownership Claims - Conclusion):

Requires OTP verification (verification_request_id + token)
Verification purpose: CLAIM_CONCLUSION

For CPF/CNPJ:

Requires HMAC signature for authentication

For Email (Ownership Claims):

Not supported - email keys can only be used for portability

Claim Status Flow

Status Progression

OPEN → WAITING_RESOLUTION → CONFIRMED → COMPLETED
         ↓                      ↓
      CANCELLED            CANCELLED

Status Descriptions

Status	Description	Who Can Act	Next Actions
OPEN	Claim initiated, waiting for donor to read	Claimer or Donor	Cancel
WAITING_RESOLUTION	Donor has read the claim	Claimer or Donor	Confirm, Cancel
CONFIRMED	Donor confirmed the claim	Claimer only	Conclude (ownership), or auto-complete (portability)
COMPLETED	Claim successfully concluded	N/A	None - final state
CANCELLED	Claim was cancelled	N/A	None - final state

Automatic Resolution

Portability Claims:

If donor doesn't respond within 7 days, claim is automatically confirmed
After confirmation, key transfer happens automatically

Ownership Claims:

If donor doesn't respond within 7 days, claim is automatically confirmed
After confirmation, claimer must still conclude the claim with verification
Claimer has 2 days to conclude after confirmation

Common Business Rules

Portability Claims

Requirements:

Key type must be: Phone, Email, CPF, or CNPJ
Key must be registered to the same CPF/CNPJ as the claimer
Account must be active and not blocked

Verification:

Phone/Email: OTP verification required at inclusion
CPF/CNPJ: HMAC signature for authentication

Timeline:

Donor has 7 days to respond
Automatic confirmation after 7 days if no response
Key transfer happens automatically after confirmation

Ownership Claims

Requirements:

Key type must be: Phone, CPF, or CNPJ (Email NOT allowed)
Key must be registered to a different CPF/CNPJ
Account must be active and not blocked

Verification:

At inclusion: OTP (phone) or HMAC signature (CPF/CNPJ)
At conclusion: OTP (phone/email) or HMAC signature (CPF/CNPJ)

Timeline:

Donor has 7 days to confirm
After confirmation, claimer has 2 days to conclude
Donor confirmation is required (no automatic confirmation)

Cancellation

Who can cancel:

Claimer: Can cancel claims in OPEN or WAITING_RESOLUTION status
Donor: Can cancel claims in OPEN or WAITING_RESOLUTION status

Cancellation Reasons:

Claimer can use: User requested, Reconciliation
Donor can use: User requested, Fraud

Important Notes

Security:

All claim operations require strong authentication
OTP tokens must be validated before processing
HMAC signatures ensure request integrity

Account Validation:

Only account owners or authorized users can manage claims
You must have access to the accounts involved in claims

Key Restrictions:

EVP (random) keys cannot be claimed - users must create new ones
Email keys can only be used for portability claims
Maximum of 20 keys per account

Available Endpoints

Use the endpoints below to manage PIX key claims:

List Claims - List all claims for your account
Create Claim - Initiate a claim for key portability or ownership
Confirm Claim - Confirm acceptance of a claim request (donor action)
Cancel Claim - Cancel a pending claim
Conclude Claim - Complete the ownership claim process (claimer action)