Validar Chave Pix

Consulta e valida uma chave Pix antes de realizar um saque. Retorna os dados do titular da chave para conferência.

GET /api/withdraws/validate-pix

Endpoint

GET https://api.divipay.com.br/api/withdraws/validate-pix

Headers

Header	Valor	Obrigatório
Authorization	Bearer	Sim

Query Parameters

Campo	Tipo	Descrição	Obrigatório
key	string	Chave Pix (CPF, CNPJ, e-mail, telefone ou chave aleatória)	Sim
customerId	string	Id da sub-conta	Não

Exemplo de Requisição

cURL

curl -X GET "https://api.divipay.com.br/api/withdraws/validate-pix?key=joao@email.com" \
  -H "Authorization: Bearer SEU_TOKEN"

JavaScript

const key = encodeURIComponent('joao@email.com');
const response = await fetch(
  `https://api.divipay.com.br/api/withdraws/validate-pix?key=${key}`,
  {
    headers: {
      'Authorization': 'Bearer SEU_TOKEN'
    }
  }
);

const pixData = await response.json();
console.log('Titular:', pixData.name);
console.log('Token:', pixData.consultToken);

Python

import requests

response = requests.get(
    'https://api.divipay.com.br/api/withdraws/validate-pix',
    params={'key': 'joao@email.com'},
    headers={
        'Authorization': 'Bearer SEU_TOKEN'
    }
)

pix_data = response.json()
print(f"Titular: {pix_data['name']}")
print(f"Token: {pix_data.get('consultToken')}")

PHP

<?php
$key = urlencode('joao@email.com');
$ch = curl_init("https://api.divipay.com.br/api/withdraws/validate-pix?key={$key}");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer SEU_TOKEN'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo 'Titular: ' . $data['name'];
echo 'Token: ' . ($data['consultToken'] ?? 'N/A');
?>

Resposta de Sucesso

Status: 200 OK

Consulta Nova (dados frescos do DICT)

{
  "name": "João da Silva",
  "keyType": "EMAIL",
  "key": "joao@email.com",
  "document": "123.***.**8-90",
  "ispb": "00000000",
  "consultToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Consulta em Cache (dados já consultados recentemente)

{
  "name": "João da Silva",
  "key": "joao@email.com",
  "document": "123.***.**8-90",
  "ispb": "00000000"
}

IMPORTANTE

O campo consultToken só é retornado em consultas novas (quando os dados são buscados diretamente no DICT/banco). Em consultas em cache, ele não é retornado.

Guarde o consultToken para enviar no campo consultId ao criar o saque.

Campo	Tipo	Descrição
name	string	Nome do titular da chave
tradeName	string	Nome fantasia (quando aplicável)
keyType	string	Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP
key	string	Chave Pix consultada
document	string	CPF/CNPJ do titular
ispb	string	Código ISPB do banco
consultToken	string	Token de consulta para usar na criação do saque (apenas em consultas novas)

Respostas de Erro

400 Bad Request

Chave Pix inválida.

{
  "statusCode": 400,
  "message": "Chave Pix inválida"
}

404 Not Found

Conta não encontrada.

Fluxo Recomendado

O fluxo ideal para realizar um saque Pix com validação prévia:

// 1. Validar a chave Pix
const pixData = await fetch(
  `https://api.divipay.com.br/api/withdraws/validate-pix?key=${key}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
).then(r => r.json());

// 2. Exibir dados para o usuário confirmar
console.log(`Titular: ${pixData.name}`);
console.log(`Documento: ${pixData.document}`);

// 3. Criar o saque com o consultToken
const withdraw = await fetch(
  'https://api.divipay.com.br/api/withdraws',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'DICT',
      amount: 500.00,
      keyPix: key,
      consultId: pixData.consultToken // token da validação
    })
  }
).then(r => r.json());

Proximos Passos

• Criar Saque - Crie o saque usando o consultToken
• Consultar Saldo - Verifique o saldo antes de criar o saque