Comece por aqui

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 chave gp_test_ só vale nele, e a gp_live_ só vale em https://app.grinnypay.com/api/v1. Chave no endereço errado responde 403 (chave_de_teste_na_producao ou somente_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 respondem 403 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çãoChave de teste
PixReal, gerado no bancoFictício (copia e cola que não paga nada)
PagamentoO cliente paga o PixVocê chama POST /charges/{id}/simulate-payment
Saldo e extratoRecebe a vendaNunca é tocado
Taxa e líquidoConta da sua taxaA mesma conta, em centavos exatos
Painel e relatóriosApareceNão aparece
WebhooksWebhook de produção, "livemode": trueSó webhook de teste, "livemode": false, assinados do mesmo jeito
link_pagamentoPágina do Pixnull (não existe página de pagamento de teste)
Antifraude, push, Utmify e nota fiscalValemNã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 /charges responde 429 limite_cobrancas_teste e não grava nada, até abrir vaga. Repetir uma Idempotency-Key que 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_requisicoes e limite_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-Key funciona 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.