Webhooks
Um Aviso automático que a FastGivr envia, por uma requisição HTTP, para a URL do seu sistema quando algo acontece (ex.: cobrança paga). é o aviso que a FastGivr envia para o seu sistema quando uma cobrança é paga. Assim você não precisa ficar consultando a API para saber se o cliente pagou.
Como configurar
Informe a URL no campo webhook ao criar a cobrança (POST /billing/charges). Cada cobrança pode ter a sua URL.
{
"payment_method": "BOLEPIX",
"amount": 150.00,
"due_date": "2026-10-31",
"client_id": 5,
"webhook": "https://seusistema.com.br/fastgivr/webhook"
}Como funciona
Descrição do diagrama em texto
- O banco confirma o pagamento à FastGivr.
- A cobrança passa para Pago.
- A FastGivr faz um POST com um JSON na URL informada no campo webhook da cobrança.
- Seu sistema responde com um código HTTP 2xx. Sem essa resposta, o aviso fica registrado como Falhou e pode ser reenviado.
O aviso
POST com Content-Type: application/json:
{
"type": { "name": "BOLEPIX" },
"txid": "E000000002026101009000002",
"value": "150.00",
"account": "SEU_ACCOUNT_TOKEN",
"date_time": "2026-10-15 14:32:10",
"details": { "...": "dados da transação e da cobrança" },
"payer": [],
"event": null,
"attempts": 0,
"last_attempt_at": null
}| Campo | O que é |
|---|---|
type.name | Forma do pagamento: PIX IN, BOLETO ou BOLEPIX |
txid | Identificador da cobrança Pix, criado por quem recebe. Serve para conciliar o pagamento com a cobrança. do Pix ou do boleto pago |
value | Valor pago |
account | Account Token da conta que recebeu |
date_time | Data e hora do pagamento |
details | Dados da transação e da cobrança. Os campos variam conforme a forma de pagamento |
event | charge.paid nos reenvios; pode vir null no envio automático |
Mudança de nomes (16/10/2026)
dateTime passou a se chamar date_time, e lastAttemptAt, last_attempt_at. Se o seu sistema lê esses campos, atualize a leitura. As demais chaves não mudaram.
O aviso traz o Account Token
O campo account contém o Account Token da conta. Use HTTPS na URL do webhook e não grave o corpo do aviso em logs abertos.
Boas práticas
- Responda rápido com 2xx e processe depois. A FastGivr tenta entregar o aviso automaticamente uma vez.
- Não confie só no aviso: confirme o status consultando
GET /billing/charges/{id}antes de liberar um pedido. - Trate repetições: use o
txidpara não processar o mesmo pagamento duas vezes (um reenvio manda o mesmo aviso de novo).
Reenviar e consultar
| O que fazer | Como |
|---|---|
| Ver os avisos enviados, com status, tentativas, payload e resposta | Portal: Configurações → Webhooks · API: GET /access/webhook-notifications e GET /access/webhook-notifications/{id} |
| Reenviar o aviso de uma cobrança paga | API: POST /billing/charges/{id}/webhook |
Resposta do reenvio:
{
"message": "Notificação enviada com sucesso",
"charge_id": "12",
"status": "success",
"http_status": 200,
"error": null,
"webhook_url": "https://seusistema.com.br/fastgivr/webhook",
"webhook_notification_id": 34,
"response": { "ok": true }
}Se o seu sistema responder com erro, o reenvio responde 500 com os detalhes. Cobrança que não existe, de outra conta ou ainda não paga: 404.