Contas

Consultar chave PIX

Consulta dados mascarados de uma chave PIX (CPF/CNPJ, e-mail, telefone ou EVP). Útil para conferir o destinatário antes de iniciar um PIX de saída.

POST/v1/accounts/:accountId/pix-keys/lookup

Escopo: accounts:read.

A consulta é feita sempre no contexto da conta informada na URL. Os dados retornados pelo provedor financeiro vêm mascarados (nomes e documentos parcialmente ocultos).

Corpo da requisição

Body (JSON)

keystringrequired

Chave PIX a consultar (CPF/CNPJ, e-mail, telefone ou EVP). Mínimo de 2 caracteres.

Exemplo

bash

curl -X POST "https://stater.stric.io/v1/accounts/acc_123/pix-keys/lookup" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"14*******47"}'

Resposta

O campo provider contém o retorno bruto da financeira. A estrutura pode variar conforme o tipo de chave, mas costuma incluir nome do correntista, tipo de chave, banco e documento — todos mascarados.

json· 200 OK

{
  "accountId": "acc_123",
  "provider": {
    "status": 200,
    "data": {
      "chave": "14*******47",
      "tipoChave": 0,
      "nomeCorrentista": "Fulano de tal",
      "sucesso": true,
      "owner": {
        "name": "Fulano de tal",
        "taxIdNumber": "***815687**"
      },
      "account": {
        "bankName": "BANK"
      }
    }
  }
}

Erros

400 invalid_request — corpo inválido (ex.: key ausente ou muito curta).

401 unauthorized — token ausente ou inválido.

403 forbidden — cliente OAuth restrito a outra conta.

404 account_not_found — conta não encontrada para o tenant.

422 account_not_transactable — operação não disponível para esta conta.

422 finance_not_configured — credenciais ausentes para consultar o provedor.

422 pix_key_lookup_failed — o provedor retornou falha de negócio (campo reason opcional com detalhe).

502 pix_key_lookup_unreachable — falha de rede ao falar com o provedor.

Endpoints relacionados

GET /v1/accounts/:accountId/pix-keys — lista as chaves cadastradas na própria conta.
POST /v1/accounts/:accountId/pix/payouts — inicia uma transferência PIX para a chave consultada.

bash

curl -X POST https://stater.stric.io/v1/accounts/$ID/pix-keys/lookup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"14*******47"}'

json· 200 OK

{
  "accountId": "acc_123",
  "provider": {
    "status": 200,
    "data": {
      "chave": "14*******47",
      "tipoChave": 0,
      "nomeCorrentista": "Fulano de tal",
      "sucesso": true,
      "owner": {
        "name": "Fulano de tal",
        "taxIdNumber": "***815687**"
      },
      "account": {
        "bankName": "BANK"
      }
    }
  }
}