Tema
Webhooks
O webhook é o aviso que a FastGivr manda para o seu sistema quando uma cobrança é paga. O seu sistema recebe uma chamada HTTP no endereço que você escolheu.
Telas do portal sobre o assunto:
- A tela Webhooks: ver os avisos enviados, o que foi mandado e o que o seu sistema respondeu;
- Como reenviar o aviso de pagamento.
Onde informar o endereço
O endereço vai em cada cobrança, no campo webhook da criação:
json
{
"payment_method": "PIX",
"value": 150.90,
"due_date": "2026-11-30",
"client_id": 501,
"webhook": "https://seusistema.exemplo.com.br/webhooks/fastgivr"
}- Precisa ser uma URL válida. Use
https://. - Dá para trocar o endereço de uma cobrança pendente com
PUT /billing/charges/{id}. Veja Cobranças. - O portal não tem campo para o endereço.
Endereço único para a conta
A conta também pode ter um endereço geral de avisos, cadastrado pela equipe FastGivr. Fale com o suporte.
Quando o aviso é enviado
| Acontecimento | Aviso |
|---|---|
Pix pago em uma cobrança PIX | Enviado automaticamente ao endereço da cobrança. |
Pix pago em uma cobrança BOLEPIX (pelo QR Code) | Enviado automaticamente ao endereço da cobrança. |
Boleto pago (BOLETO, ou BOLEPIX pago pelo código de barras) | Pode ser enviado pelo botão Reenviar do portal. Confirme também pela consulta da cobrança. |
Boleto: consulte a cobrança
Para cobranças com boleto, não espere só pelo aviso. Consulte de tempos em tempos as cobranças pendentes com GET /billing/charges?status_id=... ou GET /billing/charges/{id}.
Como o aviso chega
http
POST https://seusistema.exemplo.com.br/webhooks/fastgivr
Content-Type: application/jsonCorpo
json
{
"type": { "name": "TIPO_DA_TRANSACAO" },
"txid": "TXID_DO_PIX",
"value": "150.90",
"dateTime": "2026-11-10 10:45:00",
"details": { "...": "dados do pagamento e da cobrança" },
"payer": [],
"event": null,
"attempts": 0,
"lastAttemptAt": null
}| Campo | Tipo | O que é |
|---|---|---|
txid | texto | Identificador do Pix ou do boleto pago. É o mesmo pix.txid ou boleto.txid que veio na criação da cobrança. Use para achar a cobrança no seu sistema. |
value | texto | Valor pago, com duas casas decimais e ponto. A partir de 1.000, vem com vírgula de milhar: "1,500.00". |
dateTime | texto | Data e hora do pagamento, AAAA-MM-DD HH:MM:SS, horário de Brasília. |
type.name | texto | Tipo da transação, em maiúsculas. |
details | objeto | Dados do pagamento e da cobrança. O conteúdo varia; não dependa dele. |
payer | lista | Dados do pagador. Pode vir vazio. |
event | texto ou null | Nome do evento. Pode vir null. |
attempts, lastAttemptAt | número, texto | Controle interno de envio. |
O corpo pode trazer outros campos além dos listados. Ignore os que não conhece.
Valor em texto
value é texto e pode ter vírgula de milhar. Não converta direto para número. Para o valor pago, prefira amount_paid da consulta da cobrança.
O que o seu sistema deve responder
- Responda com status 2xx (por exemplo,
200). Aí o aviso conta como Entregue na tela Webhooks. - Qualquer outro status, erro de conexão ou demora conta como Falhou.
- Responda rápido: grave o aviso e processe depois, em segundo plano.
- O corpo da sua resposta aparece no portal, em Resposta do Servidor. Não coloque dados sensíveis nele.
Tentativas
A FastGivr faz uma tentativa de entrega por aviso. Se falhar, o aviso fica como Falhou na tela Webhooks. Para mandar de novo, use o botão Reenviar do portal: Como reenviar o aviso de pagamento. O botão aparece só em cobranças pagas com boleto (BOLETO ou BOLEPIX).
Em qualquer caso, a consulta da cobrança mostra se ela foi paga, mesmo sem o aviso.
Confirme antes de dar baixa
Ao receber o aviso:
- Ache a cobrança no seu sistema pelo
txid. - Consulte a cobrança na API:
GET /billing/charges/{id}(veja Cobranças). - Só dê baixa se
data.status.titleforpaid. Usedata.amount_paidedata.payment_datecomo valor e data do pagamento.
js
// Express-style handler
app.post('/webhooks/fastgivr', express.json(), async (req, res) => {
res.sendStatus(200); // answer fast; process in the background
const { txid } = req.body ?? {};
if (!txid) return;
const order = await findOrderByFastgivrTxid(txid); // your lookup by pix.txid / boleto.txid
if (!order || order.paid) return; // unknown or already processed
const token = await getValidToken();
const response = await fetch(
`https://v1.api.fastgivr.com.br/billing/charges/${order.fastgivrChargeId}`,
{ headers: { Authorization: `Bearer ${token}` } },
);
if (response.status !== 200) return;
const { data: charge } = await response.json();
if (charge.status?.title === 'paid') {
await markOrderAsPaid(order, charge.amount_paid, charge.payment_date);
}
});Avisos repetidos
O seu sistema pode receber o mesmo pagamento mais de uma vez. Exemplos: um reenvio pelo portal, ou o endereço da cobrança e o endereço geral da conta.
- Processe cada pagamento uma vez só: antes de dar baixa, veja se a cobrança já está paga no seu sistema.
- Use o
txid(ou oidda cobrança) como chave para evitar baixa em dobro.