Consultar chave PIX
Consulta os dados de uma chave PIX (titular e cidade) antes de enviar o pagamento. Use para exibir confirmação ao usuário.
Overview
Recomendado chamar antes de Enviar valor para chave, para exibir o nome do destinatário e evitar erros.
Fluxo cash-out
POST /pix/query → exibir titular → POST /pix/payment.
Endpoint
POSTPOST /pix/query
Base URL:
https://api.onnixpay.com/api/v1/sdkHeaders
| Header | Obrigatório | Descrição |
|---|---|---|
| X-API-Key | Sim | Sua API Key. |
| Content-Type | Sim | Obrigatório. |
Body Parameters
Todas as propriedades do corpo da requisição, com tipo, obrigatoriedade, restrições e exemplo.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| keyType | string | Sim | Tipo da chave PIX a ser consultada. Define o formato esperado em keyValue. |
| keyValue | string | Sim | Valor da chave: CPF/CNPJ (apenas números), e-mail, telefone com DDD, ou chave aleatória (EVP).Formato válido conforme keyType. CPF 11 dígitos; CNPJ 14 dígitos. |
Exemplo cURL
cURL
curl -X POST "https://api.onnixpay.com/api/v1/sdk/pix/query" \
-H "X-API-Key: ox_sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{"keyType": "EMAIL", "keyValue": "pagador@email.com"}'Response — Sucesso (200)
JSON
{
"keyType": "email",
"keyValue": "pagador@email.com",
"accountHolderName": "Nome do Titular",
"accountHolderCity": "SAO PAULO"
}Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| keyType | string | Tipo da chave consultada. |
| keyValue | string | Valor da chave (pode ser mascarado). |
| accountHolderName | string | Nome do titular para exibição/confirmação. |
| accountHolderCity | string | Cidade do titular (sigla ou nome). |
Status codes e erros comuns
| Status | Código | Mensagem |
|---|---|---|
| 400 | INVALID_REQUEST | Chave inválida ou não encontrada. |
| 401 | INVALID_API_KEY | Chave de API inválida ou ausente. |
Exemplo de resposta de erro
JSON
{
"code": "INVALID_REQUEST",
"message": "Chave não encontrada ou inválida."
}