DICT API

Manage PIX keys registration, verification, and ownership claims

DICT API

The DICT (Diretório de Identificadores de Contas Transacionais) API provides endpoints to manage PIX keys in the Brazilian PIX system. Register, verify, exclude, and claim ownership of PIX keys for your accounts.

Key Features

• PIX Key Registration: Register CPF, CNPJ, email, phone, and random keys (EVP)
• Key Verification: Request and verify ownership of email and phone keys
• Key Management: Exclude existing PIX keys from accounts
• Ownership Claims: Claim and manage PIX key portability between institutions

Available Endpoints

Key Management

• Include PIX Key - Register a new PIX key for an account
• Exclude PIX Key - Remove a PIX key from an account
• Request PIX Key Verification - Request OTP for email/phone verification

PIX Key Claim (Portability)

• Create PIX Key Claim - Initiate a portability claim
• Get PIX Key Claim - Query existing claims
• Confirm PIX Key Claim - Confirm a claim
• Conclude PIX Key Claim - Complete the transfer
• Cancel PIX Key Claim - Cancel a claim

PIX Key Types

The DICT API supports five types of PIX keys:

Type	Description	Example
CPF	Brazilian individual taxpayer ID (11 digits)	12345678901
CNPJ	Brazilian company taxpayer ID (14 digits)	12345678000190
EMAIL	Email address	[email protected]
CELL_PHONE	Phone number with country code	[phone]
EVP	Random key (UUID format)	12345678-9abc-def0-1234-56789abcdef0

Authentication

All DICT API endpoints require:

• Bearer Token: Include in the Authorization header
• HMAC Signature: Include in the hmac header for authentication
• OTP Token: Required for EMAIL and CELL_PHONE types (obtained via verification request)

Key Registration Flow

For EMAIL and CELL_PHONE:

The registration process for email and phone keys requires a two-step verification:

Step 1: Request OTP Code
┌─────────────────────────────────────────┐
│  POST /v3/key/verifications/send        │
│  ────────────────────────────────────   │
│  • key_type: EMAIL or CELL_PHONE        │
│  • key_value: [email protected] or      │
│    [phone]                       │
│  • account details                      │
└──────────────┬──────────────────────────┘
               │
               │ API generates 6-digit OTP
               │ (valid for 3 minutes)
               ↓
┌─────────────────────────────────────────┐
│  OTP Code Sent                          │
│  • Email → [email protected]             │
│  • SMS → [phone]                 │
│                                         │
│  Code: 123456                           │
└──────────────┬──────────────────────────┘
               │
               │ User receives code
               ↓
         ┌──────────────┐
         │ verification │
         │ request_id   │  ← Store this ID
         │ expires_at   │
         └──────┬───────┘
                │
                │
                │ Wait for user to input code
                │
                ↓

Step 2: Register PIX Key
┌─────────────────────────────────────────┐
│  POST /v3/key                           │
│  ────────────────────────                │
│  • verification_request_id              │
│  • token: 123456 (OTP from email/SMS)  │
│  • account details                      │
└──────────────┬──────────────────────────┘
               │
               │ API validates OTP code
               │ and registers key in DICT
               ↓
         ┌────────────┐
         │   SUCCESS  │  ← PIX key registered
         └────────────┘

Step-by-step:

1. Call Request PIX Key Verification - Returns verification_request_id
2. User receives 6-digit OTP code via email or SMS (expires in 3 minutes)
3. Call Include PIX Key with verification_request_id and OTP token

For CPF, CNPJ, EVP:

• Call Include PIX Key with HMAC authentication

Key Ownership Claims

When a PIX key is already registered at another institution, you can initiate an ownership claim (portability):

1. Create PIX Key Claim - Start the claim process
2. Confirm PIX Key Claim - Confirm the claim
3. Conclude PIX Key Claim - Finalize the transfer
4. Cancel PIX Key Claim - Cancel if needed
5. Get PIX Key Claim - View claim status

Business Rules

• Maximum PIX keys per account varies by type:
  • CPF/CNPJ: 1 key per account
  • EMAIL/CELL_PHONE: Multiple allowed
  • EVP: 20 keys per account
• Keys must be unique across the entire PIX system
• Account holder document must match CPF/CNPJ key
• Phone numbers must include country code (+55 for Brazil)