Cash Out

Consultar Chave PIX

POST/v1/pix/query

Consulta os dados de uma chave PIX a partir do seu tipo e valor, retornando titular, banco e o identificador end-to-end (E2E). Útil para validar uma chave antes de iniciar um cashout.

Parâmetros

Campo	Tipo	Descrição
`pix_key`obrigatório	`string`	Chave PIX a ser consultada. Deve estar no formato correto conforme pix_type.
`pix_type`obrigatório	`PixKeyType`	Tipo da chave PIX: CPF, CNPJ, EMAIL, PHONE ou RANDOM.

Campos da Resposta

Campo	Tipo	Descrição
`success`	`boolean`	Indica se a consulta foi realizada com sucesso
`data`	`object`	Dados da chave PIX consultada
`data.pix_key`	`string`	Chave PIX informada na consulta
`data.pix_type`	`string`	Tipo da chave PIX informado na consulta
`data.owner_name`	`string \| null`	Nome do titular da conta vinculada à chave PIX
`data.bank_name`	`string \| null`	Nome do banco vinculado à chave PIX
`data.e2e_id`	`string`	Identificador end-to-end (E2E) gerado para a chave consultada

Formatos de Chave PIX

Tipo	Formato	Exemplo
`CPF`	11 dígitos numéricos	`12345678901`
`CNPJ`	14 dígitos numéricos	`12345678000195`
`EMAIL`	Endereço de email válido	`usuario@exemplo.com`
`PHONE`	+55 seguido de 10-11 dígitos	`+5511999999999`
`RANDOM`	UUID (32-36 caracteres)	`123e4567-e12b-12d3-a456-426614174000`

A chave PIX deve corresponder exatamente ao tipo especificado em pix_type. Uma inconsistência resultará em erro 400.

Exemplo em JavaScript

Node.js (axios)javascript

const axios = require('axios');

async function consultarChavePix(pixKey, pixType) {
  const response = await axios.post(
    `${BASE_URL}/v1/pix/query`,
    { pix_key: pixKey, pix_type: pixType },
    {
      headers: { 'api-secret': process.env.API_SECRET }
    }
  );

  return response.data; // JSON com os dados da chave PIX
}

Erros Possíveis

400Chave PIX inválida ou incompatível com o tipo informado

400Não foi possível consultar a chave PIX (chave inexistente ou indisponível)

401API Secret ausente ou inválido

503Provedor de consulta de chave PIX não configurado ou indisponível

POSThttps://api.connectpay.vc/v1/pix/query

Headers

api-secret: seu_api_secret_aqui
Content-Type: application/json

Request Body (JSON)

{
  "pix_key": "joao.silva@exemplo.com",
  "pix_type": "EMAIL"
}

cURL

curl -X POST "https://api.connectpay.vc/v1/pix/query" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "pix_key": "joao.silva@exemplo.com",
    "pix_type": "EMAIL"
  }'

Response 200

{
  "success": true,
  "data": {
    "pix_key": "joao.silva@exemplo.com",
    "pix_type": "EMAIL",
    "owner_name": "João Silva",
    "bank_name": "Banco Exemplo S.A.",
    "e2e_id": "E00000000202401151030abcdef123456"
  }
}