API Nethook
Receba por PIX (cash-in) e pague por PIX (cash-out) a partir do seu servidor. Todas as rotas usam JSON e ficam em https://api.nethook.com.br/v1.
4990 = R$ 49,90. Datas em ISO 8601 (UTC).Toda resposta de sucesso traz "success": true. Erros trazem "success": false, uma mensagem em error e um code estável para o seu código tratar (veja Erros).
Autenticação
Envie a chave secreta no header x-api-key (ou Authorization: Bearer). Gere a chave no painel em API/Plugins → Nova API/Plugin: cada aplicação tem nome, ambiente, escopos e, se quiser, IPs próprios. A chave aparece completa uma única vez; revogue uma aplicação a qualquer momento sem afetar as outras.
| Prefixo | Ambiente |
|---|---|
| sk_test_… | Teste: nenhum dinheiro é movimentado. |
| sk_live_… | Produção: liberada após a aprovação do cadastro. |
Escopos
Uma aplicação criada com escopos só acessa o que recebeu. GET exige <recurso>:read; os demais métodos, <recurso>:write. Sem o escopo, a resposta é 403 missing_scope; fora dos IPs da aplicação, 403 ip_not_allowed.
| Recurso | Rotas |
|---|---|
| charges | /v1/charges |
| refunds | /v1/charges/{id}/refunds |
| payouts | /v1/payouts |
| balance | /v1/balance, /v1/statement (só leitura) |
| customers · payment_links · subscriptions · disputes | /v1/customers, /v1/payment_links, /v1/subscriptions, /v1/disputes |
| webhooks | /v1/webhook_endpoints, /v1/events |
Ambiente de teste
Toda conta tem sandbox desde o cadastro, inclusive enquanto o cadastro está em análise. No painel, o seletor Produção / Teste fica em API/Plugins → Ambiente de teste. Com uma chave sk_test_, as mesmas rotas funcionam sem dinheiro de verdade e os webhooks são entregues normalmente. Para simular eventos:
POST /v1/sandbox/charges/{id}/pay // cobrança paga
POST /v1/sandbox/charges/{id}/expire // cobrança expirada
POST /v1/sandbox/charges/{id}/dispute // MED aberto pelo banco do pagador
POST /v1/sandbox/payouts/{id}/complete // saque concluído
Criar cobrança
POST/v1/charges
| Campo | Descrição |
|---|---|
| amount | Obrigatório. Inteiro em centavos, de 100 a 100.000.000. |
| customer.name | Obrigatório. Nome de quem paga (3 a 100 caracteres). |
| customer.document | Obrigatório. CPF ou CNPJ válido, com ou sem pontuação. |
| customer.email | Opcional. |
| customer.phone | Opcional. DDD + número. |
| external_id | Recomendado. Id do pedido no seu sistema (1 a 64: letras, números, . _ : -). Repetir o mesmo devolve a cobrança original com "duplicate": true. |
| description | Opcional, até 140 caracteres. |
| site_url | Opcional. Página https onde a venda aconteceu. |
| expires_in | Opcional. Segundos até expirar (300 a 604800). Padrão: 3600. |
| metadata | Opcional. Objeto com textos seus; volta igual na consulta e no webhook. |
| splits | Opcional. Até 10 destinatários { "pix_key", "amount", "description" }. Quando o dinheiro da venda fica disponível no seu saldo, a Nethook envia a parte de cada um por Pix (um saque por destinatário, com a tarifa de Pix). A soma, com as tarifas, precisa caber no líquido; senão, 422 splits_exceed_net. A cobrança mostra splits_status: scheduled, retrying ou sent. |
curl -X POST https://api.nethook.com.br/v1/charges \
-H "x-api-key: $NETHOOK_SECRET_KEY" -H "Content-Type: application/json" \
-d '{ "amount": 4990, "external_id": "pedido-1042",
"customer": { "name": "Maria Oliveira", "document": "52998224725", "email": "maria@email.com" } }'
Resposta 201
{
"success": true,
"duplicate": false,
"charge": {
"id": "txn_8b1f…", "object": "charge", "mode": "live",
"external_id": "pedido-1042", "status": "pending",
"amount": 4990, "fee": 75, "net_amount": 4915,
"pix_copy_paste": "00020101021226…", "pix_qrcode_image": "https://…",
"customer": { "name": "Maria Oliveira", "document": "52998224725", "email": "maria@email.com", "phone": null },
"expires_at": "2026-11-19T15:00:00.000Z", "paid_at": null, "created_at": "2026-11-19T14:00:00.000Z"
}
}
Status: pending → paid | expired. Uma cobrança paga pode virar refunded.
charge.paid (ou quando a consulta mostrar paid). Nunca pela criação.Consultar cobrança
GET/v1/charges/{id}
GET/v1/charges?external_id=pedido-1042
GET/v1/charges?status=paid&limit=20&offset=0
A listagem devolve data (mais recentes primeiro) e pagination.has_more.
Devolução
POST/v1/charges/{id}/refund
{ "reason": "Cliente desistiu da compra" }
Devolve o valor total ao pagador. O valor bruto é debitado do seu saldo (a taxa da cobrança não volta). Precisa de saldo suficiente; senão, 403 insufficient_balance. Repetir a chamada devolve a mesma cobrança com "duplicate": true.
Clientes
Toda cobrança com customer.name e customer.document cria ou atualiza o cliente (chave: CPF/CNPJ). Você também pode cadastrar antes.
POST/v1/customers GET/v1/customers?q=… GET/v1/customers/{id}
{ "name": "Maria Oliveira", "document": "52998224725", "email": "maria@email.com", "phone": "48991457227" }
A consulta devolve também total_paid e paid_count. Para ver as compras: GET /v1/charges?customer_id=cus_….
Links de pagamento
Venda sem site: crie o link e envie por WhatsApp, e-mail ou redes. O cliente informa nome e CPF, paga com PIX numa página hospedada pela Nethook e você recebe o mesmo charge.paid das cobranças pela API.
POST/v1/payment_links GET/v1/payment_links
| Campo | Descrição |
|---|---|
| title | Nome que aparece na página (obrigatório sem product_id). |
| amount | Valor fixo em centavos. Sem ele, o cliente escolhe entre min_amount e max_amount. |
| product_id | Usa nome e preço de um produto cadastrado no painel. |
| max_uses | Quantos pagamentos o link aceita (ex.: vagas de uma turma). |
| expires_at | Data limite (ISO 8601). |
| success_url | Página https para onde o cliente vai depois de pagar. |
{ "success": true, "payment_link": { "id": "pl_…", "code": "k3Hq9ZbT1x", "url": "https://app.nethook.com.br/pagar.html?link=k3Hq9ZbT1x",
"title": "Mentoria 1h", "amount": 25000, "uses": 0, "max_uses": 1, "active": true } }
As cobranças criadas pelo link têm source: "payment_link" e payment_link_id.
Assinaturas
Cobrança recorrente por PIX: a cada ciclo a Nethook gera uma cobrança (válida por 3 dias) e envia charge.created com subscription_id para você mandar ao cliente. Pago, o ciclo avança; vencido, a assinatura fica past_due; após 3 ciclos sem pagamento, é cancelada.
POST/v1/subscriptions GET/v1/subscriptions/{id} POST/v1/subscriptions/{id}/cancel
{ "external_id": "plano-pro-123", "description": "Plano Pro", "amount": 9700,
"interval": "month", // week | month | year
"customer": { "name": "Carla Dias", "document": "52998224725" }, // ou "customer_id": "cus_…"
"start_at": "2026-12-01T12:00:00Z" } // opcional; padrão: agora
Webhooks
Cadastre as URLs (https) no painel em Integrações, escolhendo os eventos. Cada URL recebe um segredo próprio (whsec_…), exibido uma única vez.
| Evento | Quando |
|---|---|
| charge.pending | Cobrança criada. |
| charge.paid | Pagamento confirmado. |
| charge.expired | Venceu sem pagamento. |
| charge.refunded | Devolvida ao pagador. |
| payout.completed | Saque concluído. |
| payout.failed | Saque não saiu (ou foi recusado na aprovação); o total voltou ao saldo. |
| dispute.opened | O banco do pagador abriu um MED; o valor entrou em bloqueio cautelar. |
| dispute.won / dispute.lost | Decisão do MED: valor liberado ou devolvido ao pagador. |
| subscription.created | Assinatura criada. |
| subscription.past_due | A cobrança do ciclo venceu sem pagamento. |
| subscription.canceled | Cancelada por você ou após 3 ciclos sem pagamento. |
| balance.adjusted | A equipe da Nethook lançou um ajuste manual no seu saldo. |
POST https://seusite.com.br/webhooks/nethook
Content-Type: application/json
X-Nethook-Event: charge.paid
X-Nethook-Delivery: whd_…
X-Nethook-Signature: t=1763560000,v1=5f1c…
{ "id": "evt_…", "event": "charge.paid", "mode": "live",
"created_at": "…", "data": { …mesmos campos da cobrança… } }
Conferir a assinatura
Calcule HMAC-SHA256(segredo, "<t>.<corpo cru>") em hexadecimal e compare com v1 em tempo constante. Recuse se t tiver mais de 5 minutos de diferença do seu relógio.
// Node 18+ com Express
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.post('/webhooks/nethook', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('x-nethook-signature') ?? '';
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.status(401).end();
const esperado = crypto.createHmac('sha256', process.env.NETHOOK_WEBHOOK_SECRET)
.update(`${m[1]}.${req.body}`).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(m[2]), Buffer.from(esperado))) return res.status(401).end();
const evento = JSON.parse(req.body);
// Deduplique por evento.id: o mesmo aviso pode chegar mais de uma vez.
res.status(200).json({ received: true });
// processe em segundo plano…
});
Entrega e retentativas
Responda 2xx em até 10 segundos. Qualquer outra resposta conta como falha, e há até 6 retentativas com espera crescente (30 s, 1, 2, 4, 8 e 16 min). Redirecionamentos não são seguidos. Você pode reenviar qualquer aviso pelo painel.
Saldo
GET/v1/balance
{ "success": true, "balance": { "currency": "BRL",
"available": 48217, // pode sacar agora
"settling": 12990, // pago, liberado ainda hoje
"receivable": 39900, // pago, liberado nos próximos dias
"pending_out": 10000, // saques e devoluções em andamento
"blocked": 0, // bloqueio cautelar por MED
"debt": 0 } } // valor devido (MED perdido sem saldo)
O prazo de liberação (D+0, D+1…) é definido por conta. Enquanto a venda está em liquidação, ela não pode ser sacada nem devolvida.
Saques (PIX Out)
POST/v1/payouts
| Campo | Descrição |
|---|---|
| amount | Obrigatório. Centavos que o recebedor recebe (mínimo 100). |
| pix_key | Obrigatório. Chave PIX de destino. |
| pix_key_type | Obrigatório. cpf, cnpj, email, phone ou random. |
| external_id | Obrigatório. Id do saque no seu sistema. Grave antes de chamar: repetir o mesmo nunca paga duas vezes. |
| beneficiary_name | Opcional. |
| beneficiary_document | Opcional. CPF/CNPJ do dono da chave. |
| description | Opcional. |
A taxa do saque sai do seu saldo: é debitado amount + fee (campo total_debited).
{
"success": true, "duplicate": false,
"payout": { "id": "po_…", "status": "processing", "amount": 10000, "fee": 150,
"total_debited": 10150, "pix_key": "52998224725", "pix_key_type": "cpf",
"external_id": "saque-98431", "end_to_end_id": null, "created_at": "…" }
}
Status: processing → completed | failed. Em failed, o total volta ao saldo; para tentar de novo, use um novo external_id. Se a sua requisição cair por timeout, repita com o mesmo external_id: é seguro.
GET/v1/payouts/{id} GET/v1/payouts?external_id=…
IPs autorizados
Em produção, as rotas /v1/payouts só respondem a IPs cadastrados no painel em Integrações (IPv4 ou IPv6; faixa de até /24 ou /64; até 20 entradas). De outro IP: 403 ip_not_allowed. No teste não há essa trava.
Limites e aprovação de saques
Em produção, cada conta tem limite por saque, por dia e por mês, e um valor acima do qual o saque espera aprovação manual da equipe de risco. Veja e peça aumento no painel em Limites.
| Situação | Resposta |
|---|---|
| Acima do limite por saque, diário ou mensal | 422 per_transaction_limit_exceeded, daily_limit_exceeded ou monthly_limit_exceeded |
| Acima do valor de aprovação | 201 com status: "pending_approval". O valor fica reservado; depois vira processing ou rejected (com payout.failed). |
| Chave PIX ou documento na lista de bloqueio | 403 blocked_by_risk |
| Muitos saques para a mesma chave no dia | 429 velocity_limit |
MED (contestações PIX)
Quando o banco do pagador abre um MED (Mecanismo Especial de Devolução), o valor da venda vai para blocked e você recebe dispute.opened. A disputa traz os dados do caso enviados pelo Banco Central: med_type (MED 2.0), kind (original ou relacionada), end_to_end_id, payer_name e payer_psp.
A resposta é feita com evidências em arquivo (nota fiscal, comprovante de envio ou entrega, conversa com o cliente, fotos), em até 4 dias. A Nethook repassa ao banco dentro do prazo do arranjo PIX.
GET/v1/disputes GET/v1/disputes/{id} POST/v1/disputes/{id}/evidences
curl -X POST https://api.nethook.com.br/v1/disputes/dp_…/evidences \ -H "x-api-key: $NETHOOK_KEY" \ -F "file=@nota-fiscal-2031.pdf"
Um arquivo por chamada, campo file: PDF, PNG, JPG ou JPEG, até 10 MB, no máximo 10 por disputa. O conteúdo é conferido (um .png que não é imagem é recusado). Depois que a Nethook repassa as evidências ao banco, a disputa não aceita mais arquivos.
Ganho: o valor volta para available. Perdido: o valor é devolvido ao pagador; se o bloqueio não cobria tudo (você já tinha sacado), a diferença fica em debt e é abatida das próximas vendas. Mesmo que você devolva o valor ao cliente por conta própria, responda o MED.
Erros
{ "success": false, "error": "Saldo insuficiente para o valor do saque mais a taxa.", "code": "insufficient_balance" }
| HTTP · code | O que fazer |
|---|---|
| 400 invalid_json | O corpo não é JSON. |
| 400 validation_failed | Veja details[] com field e message. |
| 400 invalid_pix_key | A chave não bate com o tipo informado. |
| 401 missing_api_key | Envie o header x-api-key. |
| 401 invalid_api_key | Chave errada ou substituída por uma nova. |
| 403 account_not_active | Cadastro ainda em análise para produção. |
| 403 account_suspended | Fale com o suporte. |
| 403 ip_not_allowed | Cadastre o IP do servidor no painel. |
| 403 insufficient_balance | Saldo não cobre o valor (+ taxa). |
| 404 transaction_not_found | Cobrança não existe ou não é da sua conta. |
| 404 payout_not_found | Saque não existe ou não é da sua conta. |
| 422 transaction_not_paid | Só cobranças pagas podem ser devolvidas. |
| 502 provider_error | Nenhum PIX foi gerado. Pode tentar de novo. |
| 500 internal_error | Tente de novo; em saques, com o mesmo external_id. |