Guias/Integração

Sandbox e produção

Chave de teste opera num ambiente isolado, com provedor simulado — sem dinheiro real.

Sandbox existe para você integrar sem risco: mesmo contrato de API, mesmo envelope, mesmos códigos de erro, e nenhum dinheiro real.

Como funciona

O ambiente é definido pela chave, não pela URL. As duas chaves chamam o mesmo endereço, https://integrate.api.kyvopay.com.br:

	Chave de teste	Chave de produção
Formato	`ky_XXXXX-XXXXX-XXXXX`	`ky_XXXXX-XXXXX-XXXXX`
Como saber qual é	Rótulo Teste em Integrações → Chaves de API	Rótulo Produção no mesmo lugar
Dinheiro	Simulado	Real
Saldo, cobranças, saques	Isolados, numa conta de sandbox só sua	Os da sua conta
Cadastro aprovado	Não precisa	Precisa, para processar cobranças reais

As duas chaves têm o mesmo formato: o ambiente não aparece na string. Nomeie as chaves pelo ambiente (checkout-teste, checkout-prod) e guarde cada uma numa variável separada. Uma chave de teste em produção não dá erro: ela simplesmente opera no sandbox, sem mover dinheiro.

A conta de sandbox é criada na primeira vez que você gera uma chave de teste. Ela é sua: ninguém mais enxerga os dados dela, e ela não aparece como uma segunda empresa no painel.

O que acontece em sandbox

Cobrança Pix: sai com um código copia e cola de mentira (…KYVOPAYSANDBOX…) que não funciona em app de banco. Alguns segundos depois de criada, a cobrança é marcada como paga sozinha — não há QR para pagar.
Saldo: a cobrança paga entra como saldo disponível na hora, sem prazo de liberação, já descontada a taxa padrão. Isso permite testar saque logo em seguida. As condições negociadas da sua conta de produção não se aplicam ao sandbox.
Saque: é aprovado na hora, sem análise manual, e fica processing. Chame POST /v1/payouts/{payoutId}/sync para concluí-lo.
Webhooks: chegam nos mesmos endpoints que você cadastrou, com o campo livemode: false no corpo e em data. Em produção é true. Ignore livemode: false no seu fluxo real (ou trate de forma separada) — assim um teste nunca libera um pedido de verdade.
Idempotência, limites e envelope: iguais aos de produção.

O que não existe em sandbox

Cartões: respondem 403, porque o emissor é um provedor real.
Disputas (MED): não são geradas, pois vêm do provedor de pagamento.
Painel: os dados de sandbox ainda não aparecem no painel — consulte pela API e pelos webhooks.

Testando o fluxo de ponta a ponta

Crie uma chave de teste
Em Integrações → Chaves de API, escolha Teste. Copie na hora: ela só aparece inteira uma vez.
Crie a cobrança
POST /v1/payments com o pagador. Veja Receber PIX.
Espere o webhook
O payment.paid chega com livemode: false. Valide a assinatura como em produção.
Consulte o saldo
GET /v1/balance já mostra o valor disponível.
Teste o saque
POST /v1/payouts e depois POST /v1/payouts/{payoutId}/sync.

Antes de virar a chave para produção

Variável de ambiente separada por ambiente, sem chave escrita no código.
Webhook de produção apontando para a URL de produção — não para o túnel de desenvolvimento.
Código que trata livemode: false de forma diferente de true.
Primeiro teste em produção com valor baixo, feito por você.

Precisa de ajuda? Fale com o suporte