List Account PIX Keys

Time	Status	User Agent
Retrieving recent requests…

Endpoint

GET /v2/list-my-pix-keys

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Query Parameters

Parameter	Type	Description	Required	Example
account_branch_identifier	String	Bank branch/agency number of the account. Format varies by institution (e.g., "0001", "1234-5").	required	0001
account_number	String	Account number. Format varies by institution (e.g., "12345678-9", "123456").	required	12345678-9

Request Examples

Get PIX keys for an account:

GET /v2/list-my-pix-keys?account_branch_identifier=0001&account_number=12345678-9

Get PIX keys with encoded parameters:

GET /v2/list-my-pix-keys?account_branch_identifier=1234-5&account_number=98765432-1

Response Details

{
  "worked": true,
  "keys": [
    {
      "key": "+5511987654321",
      "name_account": "João da Silva",
      "document_account": "123.456.789-00"
    },
    {
      "key": "[email protected]",
      "name_account": "João da Silva",
      "document_account": "123.456.789-00"
    },
    {
      "key": "12345678-9abc-def0-1234-56789abcdef0",
      "name_account": "João da Silva",
      "document_account": "123.456.789-00"
    }
  ]
}

Empty result (no PIX keys registered):

{
  "worked": true,
  "keys": []
}

Response Fields

Field	Description
worked	Always returns `true` when the request is successful
keys	Array of PIX key objects. Empty array `[]` if no keys are registered for this account.

PIX Key Object Fields

Field	Description
key	The PIX key value. Can be CPF, CNPJ, phone number, email, or random key (EVP).
name_account	Name of the account holder. Shows "-" if not available.
document_account	CPF or CNPJ of the account holder (formatted with dots and dashes). Shows "-" if not available.

PIX Key Types:

CPF: 11 digits (e.g., 123.456.789-00 or 12345678900)
CNPJ: 14 digits (e.g., 12.345.678/0001-90 or 12345678000190)
Phone: Format +5511987654321 (country code + area code + number)
Email: Valid email address (e.g., [email protected])
EVP (Random Key): UUID format (e.g., 12345678-9abc-def0-1234-56789abcdef0)

Error Responses

HTTP Code	Error Message	Description
400	Account not found	The account was not found or you don't have permission to access it.
400	Account is closed	The account exists but is in `CLOSED` status. Cannot list PIX keys for closed accounts.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature.
403	Forbidden	You do not have access to PIX keys for this account.
404	Account not found	The account with the specified branch and account number does not exist.
422	Validation error	One or more query parameters are invalid or missing. Check that both `account_branch_identifier` and `account_number` are provided.

Business Rules

Account Validation:

Account must exist in the system
Account must belong to your account
Account must not be in CLOSED status
You must have access to the specified account

PIX Key Status:

Only returns active PIX keys (is_active=True)
Deleted or inactive keys are not included in the response
Keys are returned in the order they were created

Use Cases

1. Display User's PIX Keys:
Show all registered PIX keys in account management dashboard or settings page.

2. Payment Form Selection:
Allow users to select from their registered PIX keys when making payments.

3. PIX Key Management:
List existing keys before allowing user to register new ones or delete existing ones.

4. Account Overview:
Display PIX keys as part of complete account information view.

5. Multi-Key Support:
Handle accounts with multiple PIX keys (phone, email, CPF, random key).

6. Validation Before Actions:
Check if account has any PIX keys before allowing PIX-related operations.

Best Practices

Display Formatting:

CPF/CNPJ: Display with formatting (dots and dashes)
Phone: Display with country code and formatting: +55 (11) 98765-4321
Email: Display as-is
EVP: Show first 8 characters + "..." or use a friendly label like "Random Key"

UI/UX Recommendations:

// Format PIX key for display
const formatPixKey = (key) => {
  // Check key type by pattern
  if (/^\d{11}$/.test(key.replace(/\D/g, ''))) {
    // CPF
    const digits = key.replace(/\D/g, '');
    return `${digits.slice(0,3)}.${digits.slice(3,6)}.${digits.slice(6,9)}-${digits.slice(9)}`;
  }
  if (/^\d{14}$/.test(key.replace(/\D/g, ''))) {
    // CNPJ
    const digits = key.replace(/\D/g, '');
    return `${digits.slice(0,2)}.${digits.slice(2,5)}.${digits.slice(5,8)}/${digits.slice(8,12)}-${digits.slice(12)}`;
  }
  if (/^\+\d{13}$/.test(key)) {
    // Phone
    return `+${key.slice(1,3)} (${key.slice(3,5)}) ${key.slice(5,10)}-${key.slice(10)}`;
  }
  if (/^[a-f0-9-]{36}$/i.test(key)) {
    // EVP/Random
    return `${key.slice(0,8)}... (Random Key)`;
  }
  // Email or unknown format
  return key;
};

Key Type Detection:

// Detect PIX key type
const detectKeyType = (key) => {
  const digits = key.replace(/\D/g, '');
  
  if (digits.length === 11 && /^\d{11}$/.test(digits)) {
    return 'CPF';
  }
  if (digits.length === 14 && /^\d{14}$/.test(digits)) {
    return 'CNPJ';
  }
  if (/^\+\d{13}$/.test(key)) {
    return 'PHONE';
  }
  if (/^[a-f0-9-]{36}$/i.test(key)) {
    return 'EVP';
  }
  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(key)) {
    return 'EMAIL';
  }
  return 'UNKNOWN';
};

Error Handling:

const listPixKeys = async (branch, account) => {
  try {
    const params = new URLSearchParams({
      account_branch_identifier: branch,
      account_number: account
    });
    
    const response = await fetch(`/list-my-pix-keys?${params}`, {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'hmac': 'YOUR_HMAC'
      }
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      if (response.status === 400 && error.detail === 'Account is closed') {
        throw new Error('This account is closed and cannot be used');
      }
      if (response.status === 400 || response.status === 404) {
        throw new Error('Account not found. Please check your credentials.');
      }
      if (response.status === 403) {
        throw new Error('You do not have permission to access this account');
      }
      
      throw new Error(error.detail || 'Failed to fetch PIX keys');
    }
    
    const data = await response.json();
    
    if (data.keys.length === 0) {
      console.info('No PIX keys registered for this account');
    }
    
    return data.keys;
    
  } catch (error) {
    console.error('Error fetching PIX keys:', error);
    throw error;
  }
};

Caching Strategy:

// Cache PIX keys to reduce API calls
const pixKeyCache = new Map();

const getCachedPixKeys = async (branch, account) => {
  const cacheKey = `${branch}:${account}`;
  
  // Check cache
  if (pixKeyCache.has(cacheKey)) {
    const cached = pixKeyCache.get(cacheKey);
    // Cache valid for 5 minutes
    if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
      return cached.keys;
    }
  }
  
  // Fetch fresh data
  const keys = await listPixKeys(branch, account);
  
  // Save to cache
  pixKeyCache.set(cacheKey, {
    keys,
    timestamp: Date.now()
  });
  
  return keys;
};

// Invalidate cache when keys are added/removed
const invalidatePixKeyCache = (branch, account) => {
  const cacheKey = `${branch}:${account}`;
  pixKeyCache.delete(cacheKey);
};

Display Components:

// React component example
const PixKeyList = ({ branch, account }) => {
  const [keys, setKeys] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    const fetchKeys = async () => {
      try {
        setLoading(true);
        const data = await listPixKeys(branch, account);
        setKeys(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };
    
    fetchKeys();
  }, [branch, account]);
  
  if (loading) return <Spinner />;
  if (error) return <Alert type="error">{error}</Alert>;
  if (keys.length === 0) {
    return (
      <EmptyState
        icon={<KeyIcon />}
        title="No PIX keys registered"
        description="Register a PIX key to start receiving instant payments"
        action={<Button>Register PIX Key</Button>}
      />
    );
  }
  
  return (
    <List>
      {keys.map((key, index) => (
        <ListItem key={index}>
          <KeyIcon type={detectKeyType(key.key)} />
          <div>
            <Text weight="bold">{formatPixKey(key.key)}</Text>
            <Text size="small" color="gray">
              {key.name_account} • {key.document_account}
            </Text>
          </div>
          <Badge>{detectKeyType(key.key)}</Badge>
        </ListItem>
      ))}
    </List>
  );
};

Validation:

Always validate both account_branch_identifier and account_number are provided
Handle empty results gracefully (show "No keys registered" message)
Validate account access before displaying keys
Consider account status (don't allow operations on closed accounts)

Security:

Never expose PIX keys in logs or public URLs
Always validate account access before displaying keys
Use HTTPS for all requests
Implement proper access controls
Consider masking sensitive information (document numbers)
Audit all PIX key access

Performance:

Cache results for frequently accessed accounts
Recommended cache duration: 5 minutes
Invalidate cache when keys are added, removed, or modified
Consider lazy loading if displaying many accounts

Integration Patterns:

// Complete example: Fetch and display PIX keys
const displayAccountPixKeys = async (branch, account) => {
  try {
    console.log(`Fetching PIX keys for account ${branch}/${account}`);
    
    const keys = await listPixKeys(branch, account);
    
    if (keys.length === 0) {
      console.log('No PIX keys registered');
      return null;
    }
    
    console.log(`Found ${keys.length} PIX key(s):`);
    keys.forEach((key, index) => {
      console.log(`  ${index + 1}. ${formatPixKey(key.key)}`);
      console.log(`     Type: ${detectKeyType(key.key)}`);
      console.log(`     Owner: ${key.name_account}`);
      console.log(`     Document: ${key.document_account}`);
    });
    
    return keys;
    
  } catch (error) {
    console.error('Failed to fetch PIX keys:', error.message);
    throw error;
  }
};

// Usage
displayAccountPixKeys('0001', '12345678-9');

Important Notes

Multiple Keys:

An account can have multiple PIX keys (up to the limit defined by the Central Bank)
Each key must be unique across the entire PIX system
Keys can be of different types (one CPF, one phone, one email, etc.)

Key Portability:

PIX keys can be transferred between institutions
The keys returned are those currently active for this account
After portability, old keys will no longer appear

Data Availability:

name_account and document_account may show "-" if data is not available
This can happen with incomplete registrations
The key itself is always present