Webhooks

Introdução

Os webhooks do FullPix notificam sua aplicação sempre que uma transação PIX muda de status. Cada evento é enviado para o postbackUrl configurado, via requisição HTTP POST com payload JSON contendo os detalhes completos da transação.

Estrutura do Payload do Webhook

Todos os eventos compartilham a mesma estrutura base:

{
    "id": "F92XRTVSGB2B",
    "type": "transaction",
    "objectId": "28a65292-6c74-4368-924d-f52a653706be",
    "data": {
        "id": "28a65292-6c74-4368-924d-f52a653706be",
        "amount": 10000,
        "refundedAmount": null,
        "description": "Transação criada via API",
        "companyId": "6b366424-d046-41c6-8976-22a516f7dfb8",
        "installments": 1,
        "paymentMethod": "PIX",
        "status": "paid",
        "postbackUrl": "https://webhook.site/0d7aef0c-ad93-4a7c-8514-30d9b2896750",
        "metadata": null,
        "createdAt": "2025-04-03T15:59:43-03:00",
        "updatedAt": "2025-04-03T15:59:43-03:00",
        "paidAt": "2025-04-03T15:59:43.56-03:00",
        "ip": null,
        "customer": {
            "id": "96155cff-4224-46fd-af28-ba58d6b06301",
            "name": "TESTE PIX",
            "email": "testepix@gmail.com",
            "phone": "11999999999",
            "createdAt": "2025-04-03T15:59:43.131002",
            "document": "01234567890"
        },
        "card": null,
        "boleto": null,
        "pix": {
            "qrcode": "https://digital.mundipagg.com/pix/",
            "expirationDate": "2025-04-03T16:19:43-03:00",
            "end2EndId": "E12345678202009091221abcdef12345",
            "receiptUrl": null
        },
        "shipping": {
            "neighborhood": "centro",
            "zipCode": "49070083",
            "city": "Aracaju",
            "complement": "",
            "streetNumber": "11",
            "street": "Rua Bolívia",
            "state": "SE"
        },
        "refusedReason": null,
        "items": [
            {
                "title": "Camisa G",
                "unitPrice": 10000,
                "quantity": 1,
                "externalRef": "yshZlkj4eFo2imq7TOH158g1mp0akci8"
            }
        ],
        "splits": [
            {
                "recipientId": "21cb8a8b-35e4-44bf-aa72-130a1154b42a",
                "percentage": 100,
                "netAmount": 9900
            }
        ],
        "fee": {
            "fixedAmount": 1,
            "spreadPercentage": 0.6,
            "estimatedFee": 100,
            "netAmount": 9900
        }
    }
}

Status Possíveis

Status	Descrição	Ação recomendada
`waiting_payment`	Transação criada, aguardando pagamento	Aguardar confirmação do cliente
`paid`	Transação paga com sucesso	Liberar o produto/serviço e atualizar sistemas
`refused`	Transação recusada	Consultar motivo e notificar o cliente
`canceled`	Transação cancelada	Atualizar sistema e comunicar o cancelamento
`refunded`	Transação estornada	Registrar o estorno e analisar a causa
`chargedback`	Transação com chargeback	Iniciar contestação com o suporte do FullPix
`failed`	Transação falhou	Identificar o erro e tentar novamente se possível
`expired`	Transação expirou	Oferecer nova opção de pagamento
`in_analisys`	Transação em análise	Aguardar retorno da análise
`in_protest`	Transação em protesto	Abrir contestação junto ao FullPix

Boas Práticas

Resposta rápida: Retorne HTTP 200 em até 5 segundos para evitar retries desnecessários do FullPix.

Idempotência: Utilize o data.id para garantir que o processamento seja executado apenas uma vez.

Retry controlado: Em falhas, o FullPix reenviará o webhook até 3 vezes; trate reentradas de forma segura.

Logging e auditoria: Registre todos os payloads recebidos para troubleshooting e rastreabilidade.

Introdução#

Estrutura do Payload do Webhook#

Status Possíveis#

Boas Práticas#

Introdução

Estrutura do Payload do Webhook

Status Possíveis

Boas Práticas