Modo de teste
A chave de teste da API de pagamentos simula a cobrança Pix sem chamar gateway. O resultado é definido pelo valor e pelo documento enviados.
O modo de teste da API de pagamentos é o uso de uma chave de teste, iniciada por ggpk_test_. Com ela, a API nunca chama um gateway e não cobra ninguém: o resultado da cobrança é definido pelos dados enviados. Os webhooks são entregues de verdade, com livemode: false. O Pix de teste tem um copia e cola falso, que não pode ser pago em nenhum banco.
Cenários
| Dado enviado | Resultado |
|---|---|
buyer.document igual a 111.444.777-35 | Pix gerado, vence depois de 10 segundos. |
amount terminado em 51 (exemplo: 4951) | Pix gerado, pago depois de 10 segundos. |
amount terminado em 52 | Pix gerado, falha depois de 10 segundos. |
amount terminado em 53 | Pix gerado, vence depois de 10 segundos. |
amount terminado em 55 | Erro 402 pix_generation_failed, e a cobrança fica failed. |
| Qualquer outro valor | Pix gerado e nunca pago, vence em 2 horas. |
Os cenários são avaliados nessa ordem: o documento vem antes do valor. Cada cenário de 10 segundos dispara o webhook correspondente: payment_intent.succeeded, payment_intent.failed ou payment_intent.expired.
O que é igual à produção
- A validação dos campos e os códigos de erro.
- A idempotência e a
external_referenceúnica. - As ordens de cobrança que a chave pode usar.
- O cancelamento.
- A assinatura dos webhooks.
As cobranças de teste não aparecem em Pagamentos e não pagam taxa.
Limites do modo de teste
Os limites de requisição da chave de teste são menores e fixos, e não somam com os de produção:
| Operação | Por chave | Por conta (todas as chaves) |
|---|---|---|
| Criar cobrança | 10 por minuto | 20 por minuto |
| Consultar | 60 por minuto | |
| Cancelar | 10 por minuto | |
| Criar cobrança, por dia | 500 a cada 24 horas |
O modo de teste de todas as contas também divide um teto global de criações por minuto, para não disputar recursos com a produção. Acima de qualquer limite, a API responde 429 rate_limit_exceeded, com o header Retry-After.
No painel
A chave de teste é criada em Ferramentas > Gateways > API de pagamentos, botão Nova chave, com o Tipo em Teste.
Páginas relacionadas
- Chaves da API: a criação da chave de teste e da chave de produção.
- Erros e limites: os limites de requisição da produção.
Idempotência
O header Idempotency-Key faz a API de pagamentos devolver a resposta original quando o mesmo pedido de cobrança é repetido, sem criar outra cobrança.
Erros e limites
Os erros da API de pagamentos vêm em um formato único, com um código estável, e cada chave tem limites de requisições por minuto.