A API da Zuno Pay permite criar cobranças PIX, produtos, links de pagamento e saques de forma programática. Todas as respostas são em JSON. Valores monetários são sempre em CENTAVOS (ex: R$ 197,00 = 19700). A base URL é https://zunopags.com.br/api/v1.

Todas as rotas exigem o header x-api-key com a sua chave de API. Crie chaves nomeadas em Dashboard → Configurações → Chaves de API (a chave completa só é exibida na criação — guarde-a com segurança). Emitir uma chave exige KYC aprovado, assim como as operações financeiras (criar cobrança, produto, link, saque, estorno).

Mande o header Idempotency-Key (um UUID por operação) em POST /transactions e POST /withdrawals. Se a sua requisição der timeout e você reenviar com a MESMA chave e o MESMO corpo, a API devolve a resposta da primeira vez (com o header Idempotent-Replayed: true) e não cria uma segunda cobrança nem um segundo saque. A chave vale por 24 horas. Reusar a chave com outro corpo devolve 422 (idempotency_key_reused); reenviar enquanto a primeira ainda está rodando devolve 409 (idempotency_in_progress), e basta tentar de novo em instantes.

Erros retornam status HTTP 4xx/5xx com o corpo { "error": { "code": string, "message": string } }. Códigos comuns: unauthorized (401, API key inválida), kyc_required (403, verificação pendente), account_blocked (403), invalid_request (400), insufficient_balance (400), amount_below_minimum (400), invalid_state (400), not_found (404).

Consulte os dados da sua conta, status do KYC e taxas vigentes.

Crie cobranças PIX e acompanhe o status. A confirmação chega via webhook (evento transaction.paid) ou consultando a transação.

Divida uma venda entre a sua conta e outras contas da plataforma (sócio, co-produtor, gestor de tráfego, afiliado). Cada fatia cai direto no saldo de quem recebe, no mesmo prazo de liberação da venda, quando o pagamento é confirmado.

Duas formas de medir a fatia: percent (percentual do valor BRUTO da venda) ou amountCents (valor fixo em centavos). Use uma das duas em cada destinatário.

Quem paga a taxa: a taxa da plataforma sai da parte de quem vendeu. Numa venda de R$ 100 com taxa de R$ 5 e split de 20% para um parceiro, o parceiro recebe R$ 20 cheios e você fica com R$ 75.

Destinatário: @username, e-mail do dono ou id da conta. A conta precisa estar ativa e não pode ser a sua. Até 5 destinatários por venda, cada um uma vez só.

Duas maneiras de configurar:
1. Na própria cobrança, com o campo splits em POST /transactions. Vale só para ela.
2. No painel, em Financeiro → Split de pagamentos. O acordo vale para toda venda da conta (inclusive as da API) ou só para um produto ou link. Se a cobrança da API vier SEM o campo splits, os acordos do painel se aplicam sozinhos; se vier COM, vale só o que foi enviado (para não pagar o mesmo parceiro duas vezes).

Regras: o valor de cada fatia é calculado e congelado na criação da cobrança; mudar um acordo depois não altera vendas já feitas. Pela API, se a soma das fatias não couber na venda depois da taxa, a cobrança é recusada com invalid_split antes de ser criada. Nos acordos do painel, a venda passa sem split nesse caso, para o comprador não ser prejudicado por uma configuração. O netCents devolvido já vem sem a parte dos parceiros, e o webhook traz o splitCents.

Produtos têm um checkout hospedado próprio (https://zunopags.com.br/p/SLUG) com imagem, descrição e captura automática de UTMs.

Links de pagamento são checkouts simples de valor fixo (https://zunopags.com.br/pay/SLUG), sem página de produto.

Solicite saques do saldo disponível via PIX. Saques passam por aprovação da plataforma.

Crie webhooks personalizados em Dashboard → Configurações → Webhooks, escolhendo os eventos que quer receber: transaction.created (PIX gerado), transaction.paid (compra aprovada) e transaction.refunded (reembolso). Cada webhook tem seu próprio secret. Enviamos POST JSON com os headers x-webhook-event (nome do evento), x-webhook-signature (HMAC SHA-256 do corpo, usando o secret do webhook), x-webhook-delivery (id da entrega) e x-webhook-attempt (número da tentativa). Valide a assinatura antes de processar. Webhooks criados antes de 18/09/2026 também recebem os nomes antigos (x-nivus-*) até você trocar para cabeçalhos neutros no painel.

Com a UTMify conectada (Dashboard → Integrações), todo pedido é enviado automaticamente para a UTMify seguindo a documentação oficial: o pedido entra como waiting_payment quando o PIX é gerado e é atualizado para paid/refunded conforme o status muda. Enviamos os trackingParameters (utm_source, utm_medium, utm_campaign, utm_content, utm_term, src e sck), valores, comissões, país e IP do cliente. Nos checkouts hospedados tudo é capturado da URL automaticamente; na API, envie os campos utm e customer.ip ao criar a transação.