Guias/Começar

Introdução

Tudo o que você precisa para integrar pagamentos Pix com segurança e chegar à produção com confiança.

A KyvoPay oferece uma API HTTP direta para criar e acompanhar pagamentos Pix, enviar saques, solicitar reembolsos, consultar o saldo e receber eventos em tempo real.

Esta documentação foi organizada como uma jornada prática: entender os fundamentos, fazer a primeira requisição em sandbox, implementar webhooks e, só então, ir para produção.

Nota

Está começando agora? Siga Primeira integração. O fluxo completo pode ser testado sem movimentar dinheiro real.

URL base

Todas as requisições autenticadas usam este endereço:

https://integrate.api.kyvopay.com.br/v1

Autenticação

Envie sua chave no header X-API-Key. A chave deve existir apenas no seu servidor — nunca no navegador ou aplicativo mobile.

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

Conceitos essenciais

  • Sandbox e produção são isolados. Cada ambiente tem sua própria chave, saldo e recursos.
  • Valores são centavos inteiros. R$ 49,90 deve ser enviado como 4990.
  • Operações de escrita precisam ser idempotentes. Reutilize a mesma idempotency_key ao repetir a mesma operação.
  • Webhooks são a fonte de verdade. Libere um pedido somente depois de receber e validar o evento de pagamento.
  • Toda resposta tem um identificador. Salve o request_id nos logs para acelerar diagnósticos e atendimento.

Caminho recomendado

  1. Crie uma chave de sandbox

    Gere uma chave de teste no painel e armazene-a em uma variável de ambiente do servidor.

  2. Crie uma cobrança Pix

    Envie o valor em centavos e use o identificador do seu pedido como base para a chave de idempotência.

  3. Apresente o pagamento

    Mostre ao cliente tanto o QR Code quanto o código Pix copia e cola retornados pela API.

  4. Confirme pelo webhook

    Valide a assinatura, processe o evento uma única vez e responda HTTP 200 rapidamente.

  5. Passe para produção

    Gere a chave de produção, repita o fluxo completo com um valor baixo e monitore as primeiras transações.

Envelope de resposta

Respostas de sucesso e erro seguem o mesmo formato previsível:

{
  "data": {},
  "error": null,
  "request_id": "req_01..."
}

Continue em Primeira integração ou consulte a Referência da API.

Precisa de ajuda? Fale com o suporte
© 2026 KyvoPay