Nethook
API REST · v1

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.

Valores sempre em centavos. 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.

PrefixoAmbiente
sk_test_…Teste: nenhum dinheiro é movimentado.
sk_live_…Produção: liberada após a aprovação do cadastro.
Use a chave só no servidor. Nunca no app, no site ou em código que o cliente vê.

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.

RecursoRotas
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

CampoDescrição
amountObrigatório. Inteiro em centavos, de 100 a 100.000.000.
customer.nameObrigatório. Nome de quem paga (3 a 100 caracteres).
customer.documentObrigatório. CPF ou CNPJ válido, com ou sem pontuação.
customer.emailOpcional.
customer.phoneOpcional. DDD + número.
external_idRecomendado. Id do pedido no seu sistema (1 a 64: letras, números, . _ : -). Repetir o mesmo devolve a cobrança original com "duplicate": true.
descriptionOpcional, até 140 caracteres.
site_urlOpcional. Página https onde a venda aconteceu.
expires_inOpcional. Segundos até expirar (300 a 604800). Padrão: 3600.
metadataOpcional. Objeto com textos seus; volta igual na consulta e no webhook.
splitsOpcional. 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.

Libere o pedido só quando receber o webhook 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_….

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

CampoDescrição
titleNome que aparece na página (obrigatório sem product_id).
amountValor fixo em centavos. Sem ele, o cliente escolhe entre min_amount e max_amount.
product_idUsa nome e preço de um produto cadastrado no painel.
max_usesQuantos pagamentos o link aceita (ex.: vagas de uma turma).
expires_atData limite (ISO 8601).
success_urlPá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.

EventoQuando
charge.pendingCobrança criada.
charge.paidPagamento confirmado.
charge.expiredVenceu sem pagamento.
charge.refundedDevolvida ao pagador.
payout.completedSaque concluído.
payout.failedSaque não saiu (ou foi recusado na aprovação); o total voltou ao saldo.
dispute.openedO banco do pagador abriu um MED; o valor entrou em bloqueio cautelar.
dispute.won / dispute.lostDecisão do MED: valor liberado ou devolvido ao pagador.
subscription.createdAssinatura criada.
subscription.past_dueA cobrança do ciclo venceu sem pagamento.
subscription.canceledCancelada por você ou após 3 ciclos sem pagamento.
balance.adjustedA 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

CampoDescrição
amountObrigatório. Centavos que o recebedor recebe (mínimo 100).
pix_keyObrigatório. Chave PIX de destino.
pix_key_typeObrigatório. cpf, cnpj, email, phone ou random.
external_idObrigatório. Id do saque no seu sistema. Grave antes de chamar: repetir o mesmo nunca paga duas vezes.
beneficiary_nameOpcional.
beneficiary_documentOpcional. CPF/CNPJ do dono da chave.
descriptionOpcional.

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çãoResposta
Acima do limite por saque, diário ou mensal422 per_transaction_limit_exceeded, daily_limit_exceeded ou monthly_limit_exceeded
Acima do valor de aprovação201 com status: "pending_approval". O valor fica reservado; depois vira processing ou rejected (com payout.failed).
Chave PIX ou documento na lista de bloqueio403 blocked_by_risk
Muitos saques para a mesma chave no dia429 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 · codeO que fazer
400 invalid_jsonO corpo não é JSON.
400 validation_failedVeja details[] com field e message.
400 invalid_pix_keyA chave não bate com o tipo informado.
401 missing_api_keyEnvie o header x-api-key.
401 invalid_api_keyChave errada ou substituída por uma nova.
403 account_not_activeCadastro ainda em análise para produção.
403 account_suspendedFale com o suporte.
403 ip_not_allowedCadastre o IP do servidor no painel.
403 insufficient_balanceSaldo não cobre o valor (+ taxa).
404 transaction_not_foundCobrança não existe ou não é da sua conta.
404 payout_not_foundSaque não existe ou não é da sua conta.
422 transaction_not_paidSó cobranças pagas podem ser devolvidas.
502 provider_errorNenhum PIX foi gerado. Pode tentar de novo.
500 internal_errorTente de novo; em saques, com o mesmo external_id.