Comece por aqui

Sua primeira cobrança

Do zero ao Pix pago: chave de API, cobrança, QR Code para o cliente e o aviso de pagamento no seu servidor.

Com a chave gp_live_ a cobrança deste guia é um Pix de verdade: use um valor pequeno (a partir de R$ 1,00). Para testar sem dinheiro, crie uma chave gp_test_ e siga o modo de teste.

Passo a passo

Crie uma chave de API

No painel, abra Integrações › API (pede a verificação em duas etapas) e clique em criar credencial. Marque a permissão Criar/consultar transações.

A chave privada começa com gp_live_ e aparece uma única vez. Copie e guarde no seu servidor (por exemplo numa variável de ambiente).

A chave é credencial de servidor. Ela nunca deve aparecer no JavaScript do navegador, em app de celular, em repositório público ou em print.

Crie a cobrança

Mande o valor em centavos e os dados do cliente. A Idempotency-Key é opcional, mas recomendada: se a conexão cair e você mandar de novo, não nasce uma segunda cobrança.

curl -X POST https://app.grinnypay.com/api/v1/charges \
  -H "Authorization: Bearer $GRINNY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{
    "valor": 9700,
    "descricao": "Curso de Marketing",
    "referencia": "pedido-1042",
    "cliente": { "nome": "Carlos Silva", "email": "[email protected]", "cpf": "52998224725" }
  }'

A resposta vem assim:

{
  "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f",
  "status": "pendente",
  "valor": 9700,
  "taxa": 371,
  "liquido": 9329,
  "descricao": "Curso de Marketing",
  "pix_copia_e_cola": "00020101021226...",
  "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f",
  "cliente": { "nome": "Carlos Silva", "email": "[email protected]" },
  "expira_em": "2026-10-15T14:45:00-03:00",
  "pago_em": null,
  "criado_em": "2026-10-15T14:30:00-03:00",
  "referencia": "pedido-1042"
}

Guarde o id junto do seu pedido: é por ele que você consulta a cobrança e reconhece o webhook.

Mostre o Pix para o cliente

Você tem dois caminhos:

  • Gere o QR Code no seu site a partir do pix_copia_e_cola e mostre também o texto para o cliente copiar.
  • Ou mande o cliente para o link_pagamento: uma página pronta com QR Code, botão de copiar e contador.

Receba o aviso de pagamento

Em Integrações › Webhooks, cadastre a URL do seu servidor (https) e marque o evento venda.aprovada. Quando o Pix for pago, chega um POST assim:

{
  "id": "evt_5821",
  "tipo": "venda.aprovada",
  "sequencia": 5821,
  "criado_em": "2026-10-15T14:32:10-03:00",
  "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "...": "..." }
}

Confira a assinatura antes de liberar o acesso (veja Conferir a assinatura) e responda com HTTP 2xx em até 5 segundos.

Confira quando quiser

Se o webhook atrasar, consulte a cobrança pelo id. Enquanto ela está pendente, a consulta pergunta ao banco na hora.

curl https://app.grinnypay.com/api/v1/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f \
  -H "Authorization: Bearer $GRINNY_KEY"

Antes de ir para produção

  • Chave só no servidor e, se possível, com IPs autorizados cadastrados.
  • Webhook conferindo a assinatura, o horário e o id repetido.
  • Tratamento dos erros 422 (dados do cliente) e 429 (limites). Veja Erros.