Modo de teste (sandbox)
Teste a integração inteira, do pedido ao webhook, sem Pix de verdade e sem mexer no seu saldo. Basta usar uma chave de teste no lugar da chave de produção.
A chave de teste
Em Integrações › Ambiente de teste, crie uma chave de teste. Ela começa com gp_test_ e aparece uma única vez, como a de produção.
Authorization: Bearer gp_test_1a2b3c4d5e6f_0123456789abcdef0123456789abcdef0123456789abcdef- O teste tem endereço próprio, separado da produção:
https://app.grinnypay.com/api/v1/sandbox. A chavegp_test_só vale nele, e agp_live_só vale emhttps://app.grinnypay.com/api/v1. Chave no endereço errado responde403(chave_de_teste_na_producaoousomente_chave_de_teste), sem criar nada. - O endereço de teste tem as rotas de cobrança (criar, consultar, listar) e
simulate-payment. Saldo e saques respondem403 recurso_indisponivel_em_teste. - Cada conta pode ter até 5 chaves de teste ativas, à parte das 5 de produção.
O que muda e o que não muda
| Chave de produção | Chave de teste | |
|---|---|---|
| Pix | Real, gerado no banco | Fictício (copia e cola que não paga nada) |
| Pagamento | O cliente paga o Pix | Você chama POST /charges/{id}/simulate-payment |
| Saldo e extrato | Recebe a venda | Nunca é tocado |
| Taxa e líquido | Conta da sua taxa | A mesma conta, em centavos exatos |
| Painel e relatórios | Aparece | Não aparece |
| Webhooks | Webhook de produção, "livemode": true | Só webhook de teste, "livemode": false, assinados do mesmo jeito |
link_pagamento | Página do Pix | null (não existe página de pagamento de teste) |
| Antifraude, push, Utmify e nota fiscal | Valem | Não rodam |
Cobranças de teste e de produção ficam separadas dos dois lados: a chave de teste não enxerga cobrança real, e a de produção não enxerga cobrança de teste (404 nao_encontrado).
Limites do teste
- Retenção: a cobrança de teste é apagada sozinha depois de 7 dias.
- Teto: até 200 cobranças de teste guardadas por conta. Passou disso,
POST /chargesresponde429 limite_cobrancas_testee não grava nada, até abrir vaga. Repetir umaIdempotency-Keyque já existe devolve a cobrança e não conta como nova. - Pedidos por minuto: a chave de teste tem limite por minuto próprio (
429 muitas_requisicoeselimite_vendedor), à parte do da produção: um teste de carga não gasta a cota das vendas reais.
Os dados de teste não são criptografados. Use só dados fictícios (nome, e-mail e CPF de mentira): nunca dado real de cliente.
Webhook de teste
Evento de teste nunca vai para o seu webhook de produção. Em Integrações › Ambiente de teste, crie um webhook de teste, com a URL do seu ambiente de testes. Ele recebe só eventos da chave de teste, e o webhook de produção só os de venda de verdade. Os eventos de teste saem depois dos reais na fila de envio.
Fluxo completo
Crie a cobrança de teste
Igual à cobrança normal, com a chave gp_test_. A resposta traz "livemode": false.
curl -X POST https://app.grinnypay.com/api/v1/sandbox/charges \
-H "Authorization: Bearer $GRINNY_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: teste-1042" \
-d '{
"valor": 9700,
"descricao": "Curso de Marketing",
"referencia": "teste-1042",
"cliente": { "nome": "Carlos Silva", "email": "[email protected]", "cpf": "52998224725" }
}'Simule o pagamento
Chame o endereço abaixo com o id da cobrança. Ela vira pago e o webhook venda.aprovada sai para a sua URL.
curl -X POST https://app.grinnypay.com/api/v1/sandbox/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f/simulate-payment \
-H "Authorization: Bearer $GRINNY_TEST_KEY"Confira o webhook
O aviso chega no webhook de teste, com o mesmo formato e a mesma assinatura do real. Veja livemode para não tratar teste como venda de verdade.
{
"id": "evt_9124",
"tipo": "venda.aprovada",
"sequencia": 9124,
"criado_em": "2026-10-15T14:32:10-03:00",
"livemode": false,
"dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "livemode": false }
}No seu receptor de webhook, ignore ou separe os eventos com "livemode": false: eles não são vendas e não devem liberar acesso nem emitir nota.
Repetir e vencer
- Simular o pagamento de novo numa cobrança já paga devolve a mesma cobrança, sem um segundo webhook.
- Cobrança de teste vence como a real (5 a 15 minutos). Simular uma vencida devolve
422 dados_invalidos: crie outra. - A
Idempotency-Keyfunciona igual: a mesma chave devolve a mesma cobrança de teste.
Ir para produção
Troque a chave gp_test_ pela gp_live_ e o endereço https://app.grinnypay.com/api/v1/sandbox por https://app.grinnypay.com/api/v1. O formato das respostas é o mesmo. Antes de abrir as vendas, passe pela lista de produção.