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" }
}'<?php
$ch = curl_init('https://app.grinnypay.com/api/v1/charges');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('GRINNY_KEY'),
'Content-Type: application/json',
'Idempotency-Key: pedido-1042',
],
CURLOPT_POSTFIELDS => json_encode([
'valor' => 9700,
'descricao' => 'Curso de Marketing',
'referencia' => 'pedido-1042',
'cliente' => ['nome' => 'Carlos Silva', 'email' => '[email protected]', 'cpf' => '52998224725'],
]),
]);
$cobranca = json_decode(curl_exec($ch), true);const resp = await fetch('https://app.grinnypay.com/api/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GRINNY_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido-1042',
},
body: JSON.stringify({
valor: 9700,
descricao: 'Curso de Marketing',
referencia: 'pedido-1042',
cliente: { nome: 'Carlos Silva', email: '[email protected]', cpf: '52998224725' },
}),
});
const cobranca = await resp.json();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_colae 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
idrepetido. - Tratamento dos erros
422(dados do cliente) e429(limites). Veja Erros.