Guias

Validar chave Pix

Antes de confirmar um Pix Out, valide a chave para exibir o titular ao seu usuário. Reduz fraude e devolução por 'destinatário incorreto'.

Referência de conta e headers

Toda request sobre uma conta identifica a conta por header: envie account-id (o accountId recebido no onboarding), wallet-id ou tax-identifier — precedência wallet-id > tax-identifier > account-id. Some a isso Authorization e tenantid; em DEV, também hostdevelop: apiapp.dev.ideabank.com.br. Sem nenhum header de conta a API responde 422 (account, wallet or tax-identifier header is required); se a integração não estiver vinculada à conta, 403.

GET/integration/v1/pix/key/validate?key={CHAVE}&pixKeyType={TIPO}

curl "https://apiapp.dev.ideabank.com.br/integration/v1/pix/key/validate?key=%2B5511999999999&pixKeyType=3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br"

pixKeyType: 1=CPF/CNPJ, 2=EMAIL, 3=PHONE, 4=EVP. A conta é identificada pelo header account-id (ou wallet-id / tax-identifier).

A resposta traz o nome, tax identifier mascarado, ISPB e tipo da conta — apresente-os para confirmação do usuário antes de disparar o Pix Out.

Custo e cache

A validação consulta o DICT do BACEN. Cachear por curto período (segundos) por chave reduz custo em fluxos com múltiplas confirmações do operador.