API Reference
Consultar chave Pix (DICT)
POST /v1/dict/lookup — titular, banco e dados da chave.
Consulta titular e dados da chave Pix
Consulta o DICT (Diretório de Identificadores de Contas Transacionais) e retorna nome do titular, banco e ISPB. O id pode ser enviado em POST /v1/payouts como dictLookupId para correlacionar a consulta com a transferência (recomendado para auditoria).
POST/v1/dict/lookup
owner.document sempre vem mascarado por regulação do BCB — você não recebe o documento completo do titular pelo DICT. branch, account e accountType normalmente vêm null porque o DICT padrão não expõe esses dados; quando a chave aponta para uma conta na própria Stater (transação intra-PSP), os campos podem ser preenchidos. Para reduzir custos e latência, consultas repetidas da mesma chave costumam vir com cached: true (TTL curto).
Headers
- AuthorizationObrigatóriostringBearer SUA_API_KEY
- X-Pix-Account-IdstringSeleciona a conta quando a chave tem acesso a várias.
- Content-TypeObrigatóriostringapplication/json
Body
- pixKeyObrigatóriostringValor bruto da chave Pix.
- pixKeyTypeObrigatório"EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP"Tipo da chave.
Exemplo de requisição
bash
curl -X POST https://api.staterpay.io/v1/dict/lookup \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pixKey": "fulano@example.com", "pixKeyType": "EMAIL" }'Resposta
- idstringIdentificador da consulta. Use em POST /v1/payouts como dictLookupId.
- keystringChave consultada (eco do request).
- keyType"EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP"Tipo da chave (eco).
- owner.namestringNome do titular.
- owner.documentstringCPF/CNPJ do titular, mascarado conforme regulação BCB (ex.: ***456789** para CPF).
- bankNamestringNome do banco do titular.
- ispbstringCódigo ISPB (8 dígitos) da instituição.
- branchstring | nullAgência. Costuma vir null pelo DICT padrão.
- accountstring | nullConta. Costuma vir null pelo DICT padrão.
- accountType"PAYMENT" | "CURRENT" | "SAVINGS" | nullTipo da conta. Costuma vir null pelo DICT padrão.
- cachedbooleantrue quando a resposta veio de cache interno (não acionou o DICT). Reduz custo e latência em consultas repetidas.
json
{ "id": "cmoxample0001qkxyzdictentry", "key": "fulano@example.com", "keyType": "EMAIL", "owner": { "name": "Fulano de Tal", "document": "***456789**" }, "bankName": "BANCO EXEMPLO S.A.", "ispb": "18236120", "branch": null, "account": null, "accountType": null, "cached": false}URL base:
https://api.staterpay.io