Primeira integração

Roteiro curto para sair do zero. Faça tudo em sandbox primeiro: nada aqui movimenta dinheiro de verdade.

1. Crie a conta e a chave de sandbox

   No painel, vá em Integrações → Chaves de API e crie uma chave de sandbox. O formato é ky_XXXXX-XXXXX-XXXXX, e ela só aparece inteira uma vez — copie na hora.

2. Confirme que a chave responde

   Consultar o saldo é o teste mais simples, porque não cria nada:

   curl https://integrate.api.kyvopay.com.br/v1/balance \
     -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX"

   200 com o envelope { "data": …, "error": null } significa que a chave é válida. 401 significa chave ausente ou inválida; 403 indica que a chave não tem permissão para a rota ou que o IP de origem não está na lista permitida da chave.

3. Suba o endpoint de webhook antes da primeira cobrança

   O pagamento chega como evento, não como resposta da cobrança. Publique uma URL https que responda 200 rápido e cadastre em Integrações → Webhooks. Detalhes em Webhooks.

4. Crie a cobrança e mostre o QR Code

   A resposta traz o código copia e cola e a imagem do QR. Renderize os dois: no celular a pessoa copia, no desktop ela escaneia. Passo a passo em Receber PIX.

5. Trate o evento de pagamento

   Valide a assinatura, confirme o pedido no seu banco de dados e responda 200. Só libere o produto depois do evento — nunca no clique do botão "já paguei".

6. Repita em produção

   Com o cadastro aprovado, gere uma chave de produção, troque a variável de ambiente e refaça o fluxo com um valor baixo antes de abrir para os clientes.

Checklist antes de abrir para o público

• Chave em variável de ambiente, fora do repositório e fora do front-end.
• Webhook validando assinatura e tratando entrega repetida.
• idempotency_key derivada do ID do pedido em toda criação de cobrança, saque e reembolso.
• Log do request_id em toda chamada.
• Valores em centavos, sem float em nenhum ponto do caminho.