Aparência
Webhooks de cobrança
Quando uma cobrança é paga, a API faz um POST na URL informada em webhook ao criar a cobrança (POST /billing/charges). Não há URL de webhook por conta: cada cobrança leva a sua. Sem webhook, nada é enviado.
Quando é enviado
- O banco confirma o pagamento do Pix ou do boleto.
- A API dá baixa na cobrança (
paid,amount_paid,payment_date) e, depois de gravar, envia o aviso com o eventocharge.paid. - Envio síncrono, uma tentativa. Não há nova tentativa automática. Se o seu sistema falhar, use
POST /billing/charges/{id}/webhook. - Pode chegar mais de um aviso para a mesma cobrança (reenvio manual). Trate de forma idempotente.
Requisição enviada ao seu sistema
POST {webhook}
Content-Type: application/jsonNão há assinatura nem header de autenticação. Para validar a origem, use uma URL com segredo seu (por exemplo, um token na query string) e confira a cobrança com GET /billing/charges/{id} antes de liberar o pedido.
json
{
"type": { "name": "PIX IN" },
"txid": "5f8cc3b5-4fe0-4814-b9c0-cd2c0becc97c",
"value": "150.75",
"account": "token-da-conta",
"date_time": "2026-11-20 14:32:10",
"details": {
"id": 2,
"value": "150.75",
"amount_paid": "150.75",
"payment_date": "2026-11-20 14:32:10",
"payment_method": "PIX",
"status_id": 2,
"client_id": 1,
"description": "Mensalidade dezembro"
},
"payer": { "id": 1, "name": "Maria Teste", "email": "maria@empresa.com", "document": "52998224725" },
"event": "charge.paid",
"attempts": 0,
"last_attempt_at": null
}| Campo | Descrição |
|---|---|
type.name | PIX IN (Pix de cobrança PIX), BOLEPIX (Pix de uma BOLEPIX) ou BOLETO (boleto pago) |
txid | txid do Pix ou do boleto pago (o mesmo de data.pix.txid / data.boleto.txid) |
value | Valor pago, string com 2 casas. Acima de 999,99 vem com separador de milhar: "1,500.00" |
account | Token da conta FastGivr |
date_time | Data e hora do pagamento (Y-m-d H:i:s) |
details | A cobrança (campos da tabela charges). Use details.id para identificar a cobrança |
payer | Cliente da cobrança, ou [] se não houver |
event | charge.paid no envio automático; null no reenvio manual |
Responda 2xx para confirmar. Qualquer outro status, erro de conexão ou demora acima de 30 segundos conta como falha. A API registra cada envio (URL, payload, status e resposta) em webhook_notifications, que a conta consulta em GET /access/webhook-notifications (permissão manage_api).
POST /billing/charges/{id}/webhook
Reenvia o aviso de uma cobrança paga da conta ativa. Permissão edit_charges. Usa o webhook e o txid do boleto ou, sem boleto, do Pix.
No reenvio, type.name é sempre BOLEPIX, event vem null e details traz a cobrança junto com os dados do boleto ou do Pix.
Response 200 (ou 500 se o seu sistema não respondeu 2xx):
json
{
"message": "Notificação enviada com sucesso",
"charge_id": "12",
"status": "success",
"http_status": 200,
"error": null,
"webhook_url": "https://empresa.com/webhooks/fastgivr",
"webhook_notification_id": 34,
"response": { "ok": true }
}Na falha: "message": "Erro ao enviar notificação", "status": "error" e o status devolvido pelo seu sistema em http_status.
| Status | Quando |
|---|---|
404 | Cobrança não encontrada. (inexistente, de outra conta ou não paga) |
400 | Não há PIX ou Boleto associado a esta cobrança. |
Prompt para LLM
Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo.
txt
Você vai integrar o recebimento dos webhooks de cobrança paga da API FastGivr.
Base URL: https://api.banking.fastgivr.com.br
Autenticação (para as chamadas à API): Authorization: Bearer {jwt}; header opcional account: {account_id}.
Como funciona: ao criar a cobrança (POST /billing/charges) envio "webhook": "<URL do meu sistema>". Quando a cobrança é paga, a FastGivr faz POST nessa URL com Content-Type: application/json, sem assinatura e sem header de autenticação. Uma tentativa só, timeout de 30 s, sem retry automático.
Corpo recebido: { "type": { "name": "PIX IN" | "BOLEPIX" | "BOLETO" }, "txid": string, "value": string com 2 casas (pode ter vírgula de milhar, ex. "1,500.00"), "account": token da conta, "date_time": "Y-m-d H:i:s", "details": { "id": id da cobrança, "amount_paid", "payment_date", "payment_method", "status_id", ... }, "payer": { "name", "email", "document", ... } ou [], "event": "charge.paid" ou null (reenvio), "attempts": 0, "last_attempt_at": null }.
Construa o endpoint receptor:
- Proteja a URL com um segredo meu (token na query string) e rejeite chamadas sem ele.
- Responda 2xx rápido (antes de 30 s); faça o processamento pesado em fila.
- Processe de forma idempotente pela chave details.id (+ txid): o mesmo aviso pode chegar mais de uma vez.
- Antes de liberar o pedido, confirme com GET /billing/charges/{details.id} que status.title é "paid" e que amount_paid confere.
- Converta "value" removendo a vírgula de milhar.
Endpoints:
- GET /billing/charges/{id} — confirma a cobrança; { code, success, data: { id, status: { title }, amount_paid, payment_date, pix, boleto }, message }.
- POST /billing/charges/{id}/webhook — pede o reenvio do aviso de uma cobrança paga; 200 { message, status: "success", http_status, webhook_notification_id, response } ou 500 com status "error"; 404 se não paga ou de outra conta; 400 sem Pix nem boleto.
Regras: permissões view_charges (GET) e edit_charges (reenvio); sem permissão 403.
Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data".
Chame a API pelo servidor (CORS só libera os sites da FastGivr).
Gere o código <linguagem/stack do meu projeto> com tratamento desses erros.