Skip to content

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 evento charge.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/json

Nã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
}
CampoDescrição
type.namePIX IN (Pix de cobrança PIX), BOLEPIX (Pix de uma BOLEPIX) ou BOLETO (boleto pago)
txidtxid do Pix ou do boleto pago (o mesmo de data.pix.txid / data.boleto.txid)
valueValor pago, string com 2 casas. Acima de 999,99 vem com separador de milhar: "1,500.00"
accountToken da conta FastGivr
date_timeData e hora do pagamento (Y-m-d H:i:s)
detailsA cobrança (campos da tabela charges). Use details.id para identificar a cobrança
payerCliente da cobrança, ou [] se não houver
eventcharge.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.

StatusQuando
404Cobrança não encontrada. (inexistente, de outra conta ou não paga)
400Nã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.