Developer center
Documentação API
Integre depósitos Pix, saques e consulta de saldo do ZHOX. A API não expõe as credenciais dos provedores; use sua API key no backend do seu produto.
1. Autenticação
Crie uma API key no painel do cliente e mantenha o valor somente no servidor.
Base URL: https://zhox.digital/v1 Authorization: Bearer nx_live_sua_chave
Não coloque a chave em frontend, aplicativo público, HTML ou repositório. Gere uma chave nova se houver suspeita de exposição.
2. Criar depósito Pix
O retorno traz o identificador público para acompanhar a cobrança.
POST /v1/deposits
Content-Type: application/json
{
"amount": 100.00,
"external_id": "pedido-1042",
"webhook_url": "https://cliente.example/webhooks/zhox",
"webhook_secret": "segredo-compartilhado"
}
O valor usa reais com duas casas. A cobrança começa como pending e muda para completed após confirmação do provedor.
3. Webhook do seu sistema
Use o webhook para atualizar o pedido sem polling contínuo.
POST https://cliente.example/webhooks/zhox
X-ZHOX-Event: deposit.completed
X-ZHOX-Signature: sha256=<hmac_sha256_do_body>
X-Webhook-Id: nx_...
{
"id": "nx_...",
"event": "deposit.completed",
"data": {
"status": "completed",
"amount": 100.00,
"fee": 1.50,
"net": 98.50,
"external_id": "pedido-1042"
}
}
Calcule HMAC-SHA256 no corpo bruto com o segredo informado na criação. Responda HTTP 2xx e processe o mesmo id de forma idempotente.
4. Saques Pix
O saque é criado para aprovação ou envio automático conforme a configuração administrativa.
POST /v1/withdrawals
Content-Type: application/json
{
"amount": 50.00,
"pix_key": "[email protected]",
"pix_key_type": "email",
"document": "12345678909"
}
Para saque instantâneo, envie document com o CPF/CNPJ do titular quando a chave não for CPF. Se pix_key_type for cpf, a própria chave é usada como documento. Nome, e-mail e telefone vêm do cadastro do usuário.
5. Consultas
Use as rotas abaixo para conciliar seu sistema.
| Método | Rota | Uso |
|---|---|---|
| GET | /v1/health | Verifica disponibilidade |
| GET | /v1/balance | Saldo BRL e ativos |
| GET | /v1/transactions | Histórico com filtros |
| GET | /v1/deposits/:id | Status da cobrança |
6. Recebimento crypto
O fluxo crypto é configurado pelo administrador e operado no painel em Receber crypto.
O cliente informa o valor em BRL e escolhe um ativo habilitado. O ZHOX cria o pagamento no NOWPayments, exibe endereço e QR Code e só libera o crédito após o IPN assinado informar finished. Configure a API key, o IPN Secret, as moedas e a taxa em Admin → Configurações.
IPN callback: https://zhox.digital/webhooks/nowpayments Header: x-nowpayments-sig Algoritmo: HMAC-SHA512 Crédito automático: somente payment_status = finished
Respostas e erros
As respostas são JSON e não expõem detalhes internos.
{
"ok": false,
"error": {
"code": "invalid_request",
"message": "Descrição segura para o cliente"
}
}