EVENT:CHARGE_PAID — cobrança paga (atualização principal) - Dotfy

Este é o evento que você espera para liberar o produto/serviço para o cliente.

Disparado quando o pagador efetiva o PIX. Inclui:

status: "PAID" (sempre "PAID" — nunca "COMPLETED" no corpo do webhook)

paidAt (ISO8601 do pagamento; o campo está presente em todos os eventos de cobrança, com valor null quando ainda não pago)

brCode e qrCode carregam o mesmo PIX copia-e-cola — qrCode é o nome correto; brCode é mantido por retrocompatibilidade

payer com nome e CPF/CNPJ mascarados do pagador real

netAmount (valor líquido após splits, em centavos) — só presente se a cobrança teve splits

splits[] (status final de cada split) — só presente se houver

Idempotência: se você responder 200 mas o webhook chegar duplicado, trate como o mesmo pagamento. Use data.id (ou o externalId que você passou no correlationID) como chave de deduplicação.

purchaseLink (opcional): presente apenas quando a cobrança nasceu de um link de compra por comprador (criado via POST /api/products/{id}/purchase-links). Identifica QUAL link foi pago — use o id para conciliar com o seu pedido. Os dados de customer são os informados NA CRIAÇÃO do link (não os digitados no checkout). O campo também aparece em EVENT:CHARGE_CREATED/EXPIRED quando a cobrança pertence a um link.

Cartão (checkout com cartão OU POST /api/card-payments): um pagamento com cartão dispara o mesmo EVENT:CHARGE_PAID, com paymentMethod: "CARD" e um objeto card { lastFour, brand, installments } (nunca PAN/CVV). Nesses casos brCode/qrCode vêm vazios. Em PIX, paymentMethod: "PIX". Concilie sempre pelo correlationID.

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

curl --location 'https://seu-dominio.com/webhooks/dotfy?event=charge-paid' \ --header 'X-Webhook-Signature: t=1714000300000,v1=<hex_de_HMAC_SHA256(secret, timestamp + '\''.'\'' + body)>' \ --header 'X-Webhook-Event: EVENT:CHARGE_PAID' \ --header 'X-Webhook-ID: clev02j3l4m5n6p7q8r9s0t1u2' \ --header 'X-Webhook-Timestamp: 2026-05-07T14:35:12.000Z' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "event": "EVENT:CHARGE_PAID", "timestamp": "2026-05-07T14:35:12.000Z", "data": { "id": "clxxx0001", "externalId": null, "correlationId": null, "brCode": "00020126360014BR.GOV.BCB.PIX0114+5511999998888...", "qrCode": "00020126360014BR.GOV.BCB.PIX0114+5511999998888...", "qrCodeUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "paymentLink": "https://app.dotfy.com.br/checkout/dotfy-1714000000000-abc12345", "amount": 2990, "expiresAt": "2026-05-07T15:30:00.000Z", "createdAt": "2026-05-07T14:30:00.000Z", "status": "PAID", "paymentMethod": "PIX", "paidAt": "2026-05-07T14:35:12.000Z", "customer": { "id": "12345678901", "name": "Maria Silva", "document": "123.456.789-01", "email": "maria@exemplo.com", "phone": "(11) 99999-8888" }, "payer": { "name": "Maria Silva", "taxId": "***456***" }, "netAmount": 2691, "splits": [ { "email": "parceiro@exemplo.com", "type": "PERCENT", "value": 10, "amount": 299, "status": "COMPLETED" } ], "purchaseLink": { "id": "clplink0001", "productId": "clprodNew", "customer": { "name": "Maria Silva", "email": "maria@exemplo.com", "phone": "5511999998888", "taxId": "12345678901" } } } }'

EVENT:CHARGE_PAID — cobrança paga (atualização principal)

Requisição

Respostas