Guias

Gestão de chaves Pix

Cada conta pode ter múltiplas chaves. Contas sem chave podem receber provisionamento automático de uma chave aleatória (EVP).

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.

Listar chaves

GET/integration/v1/pix/key

curl "https://apiapp.dev.ideabank.com.br/integration/v1/pix/key" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br"

Cadastrar chave

POST/integration/v1/pix/key

Campos

Campo	Tipo	Descrição
account-id*	uuid (header)	Conta destinatária da chave — o accountId recebido no onboarding. Alternativas: wallet-id ou tax-identifier.
pixType*	int	1=CPF/CNPJ, 2=EMAIL, 3=PHONE, 4=EVP.
key	string	Obrigatório para EMAIL e PHONE. Omita para EVP (a chave é gerada).

curl -X POST "https://apiapp.dev.ideabank.com.br/integration/v1/pix/key" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br" -H "Content-Type: application/json" \
  -d '{ "pixType": 4 }'

Excluir chave

DELETE/integration/v1/pix/key/{key}

curl -X DELETE "https://apiapp.dev.ideabank.com.br/integration/v1/pix/key/%2B5511999999999" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br"

Formato das chaves

CPF/CNPJ: somente dígitos, sem máscara.
E-mail: endereço literal em minúsculas.
Telefone: E.164, ex.: +5511999999999.
EVP: UUID gerado pelo PSP.