Conciliar pagamentos
O webhook é o jeito principal de saber do pagamento. A conciliação é a rede de segurança: uma rotina sua que confere de tempos em tempos se nenhuma venda ficou sem tratar.
Por que conciliar
- O seu servidor pode ficar fora do ar por mais tempo do que as tentativas de reenvio cobrem (cerca de 22 horas).
- Um erro no seu código pode ter tratado o evento pela metade.
- Você pode ter ativado a integração depois de algumas vendas já existirem.
A conciliação não substitui o webhook: ela só pega o que escapou.
A rotina
1. Liste as cobranças pendentes do seu sistema
Pegue no seu banco os pedidos que ainda estão aguardando pagamento e cuja cobrança já foi criada há mais de 2 minutos (dê tempo ao webhook chegar).
2. Consulte cada uma na API
Chame GET /charges/{id}. Se está pendente, a consulta pergunta ao banco na hora (no máximo a cada 20 segundos por cobrança). Para muitas de uma vez, use GET /charges com status=pago e limite=100.
3. Trate o resultado como se fosse o webhook
pago: libere o acesso (se ainda não liberou). expirado: cancele o pedido. med, contestado ou reembolsado: ajuste o acesso. O mesmo código de tratamento serve para os dois caminhos, e a conferência de repetição evita tratar duas vezes.
4. Repita num ritmo suave
A cada 5 a 15 minutos para o que é recente e uma varredura maior uma vez por dia. Nunca em loop apertado: o limite de pedidos da chave existe (veja Limites).
Espera crescente quando der erro
Se a API devolver 429, 503 ou 500, espere e tente de novo, dobrando a espera a cada falha, com um pouco de variação aleatória. Erro 4xx que não é 429 não melhora tentando de novo: corrija o pedido.
<?php
function consultar(string $id, int $max = 5): array {
$espera = 1;
for ($i = 1; $i <= $max; $i++) {
$ch = curl_init("https://app.grinnypay.com/api/v1/charges/$id");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GRINNY_KEY')]]);
$corpo = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($http === 200) {
return json_decode($corpo, true);
}
if (!in_array($http, [0, 429, 500, 503], true)) {
throw new RuntimeException("Erro $http: não adianta repetir");
}
sleep($espera + random_int(0, 1)); // 1, 2, 4, 8 s (+ até 1 s)
$espera *= 2;
}
throw new RuntimeException('API indisponível: tente na próxima rodada');
}
// Rotina: pedidos aguardando pagamento há mais de 2 minutos
foreach ($pedidosPendentes as $pedido) {
$c = consultar($pedido['cobranca_id']);
if ($c['status'] === 'pago') {
liberarAcesso($pedido, $c); // a mesma função que o webhook usa, com a conferência de repetição
} elseif ($c['status'] === 'expirado') {
cancelarPedido($pedido);
}
}async function consultar(id, max = 5) {
let espera = 1000;
for (let i = 1; i <= max; i++) {
try {
const r = await fetch(`https://app.grinnypay.com/api/v1/charges/${id}`, {
headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}` },
signal: AbortSignal.timeout(10000),
});
if (r.status === 200) return await r.json();
if (![429, 500, 503].includes(r.status)) throw new Error(`Erro ${r.status}: não adianta repetir`);
} catch (e) {
if (e.message.startsWith('Erro ')) throw e; // 4xx: corrija o pedido
}
await new Promise((ok) => setTimeout(ok, espera + Math.random() * 1000)); // 1, 2, 4, 8 s
espera *= 2;
}
throw new Error('API indisponível: tente na próxima rodada');
}
for (const pedido of pedidosPendentes) {
const c = await consultar(pedido.cobrancaId);
if (c.status === 'pago') await liberarAcesso(pedido, c); // a mesma função do webhook
else if (c.status === 'expirado') await cancelarPedido(pedido);
}Idempotência: o mesmo pedido nunca vira dois
- Ao criar: mande sempre
Idempotency-Keycom um código do seu pedido (ex.:pedido-1042). Se a conexão cair, repita com a mesma chave: você recebe a mesma cobrança, não outra. Veja Repetição segura. - Ao receber: grave o
iddo evento e asequencia. Webhook e conciliação podem trazer o mesmo pagamento: o segundo a chegar não faz nada. - Ao liberar: a trava deve ser o status do pedido no seu banco (
UPDATE ... WHERE status = 'aguardando'), não só a memória do processo.
Conferir o dinheiro
No fim do dia, some o liquido das cobranças pago do período (use status=pago na listagem) e compare com o que o seu sistema registrou. Diferença quase sempre é uma venda não tratada, um MED ou um reembolso. O saldo da conta está em GET /balance; o extrato completo está no painel, em Relatórios.
Ao achar uma venda pago que o seu sistema não tem, trate-a como um venda.aprovada atrasado e anote o motivo. Se acontece mais de uma vez, olhe o histórico de envios em Integrações › Webhooks: ali aparece o código que o seu servidor devolveu.