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:

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

Key Types Allowed:

• Phone number
• Email
• CPF
• CNPJ

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:

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

Key Types Allowed:

• Phone number
• CPF
• CNPJ

Key Types for Claims

Supported Key Types

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

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)