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	user@example.com
CELL_PHONE	Phone number with country code	+5511987654321
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@example.com or      │
│    +5511999999999                       │
│  • account details                      │
└──────────────┬──────────────────────────┘
               │
               │ API generates 6-digit OTP
               │ (valid for 3 minutes)
               ↓
┌─────────────────────────────────────────┐
│  OTP Code Sent                          │
│  • Email → user@example.com             │
│  • SMS → +5511999999999                 │
│                                         │
│  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:

Call Request PIX Key Verification - Returns verification_request_id
User receives 6-digit OTP code via email or SMS (expires in 3 minutes)
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):

Create PIX Key Claim - Start the claim process
Confirm PIX Key Claim - Confirm the claim
Conclude PIX Key Claim - Finalize the transfer
Cancel PIX Key Claim - Cancel if needed
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)