Webhooks de pagamento para integradores

TLDR: contrato público dos webhooks que a ZeusPay envia às organizações a cada mudança de status de pagamento — catálogo de eventos, configuração, política de retry e estrutura completa do payload.

Visão geral

Webhooks são mensagens automáticas enviadas do nosso sistema para a aplicação do integrador quando acontecem eventos específicos na plataforma. Para pagamentos, disparamos um evento sempre que há mudança de status — criação, confirmação, reembolso e outros.

O recurso é interno e liberado por conta. Para habilitar, o integrador fala com o gerente de conta, que faz a configuração.

Termos técnicos, nomes de eventos e nomes de campos são identificadores do contrato e não são traduzidos.

Fluxo

mermaid graph LR A["Mudança de status<br/>do pagamento"] --> B["EventsHub"] B --> C["FetchListeners<br/>IntegrationWebhook ativos"] C --> D["BuildPayloads"] D --> E["POST na URL do integrador<br/>X-Security-Signature-Token"] E --> F{"Sucesso?"} F -->|sim| G["OutcomeWebhookLog"] F -->|não| H["Retry — até 3 tentativas"] H --> E style E fill:#1f2937,color:#fff

Contratos

Catálogo de eventos

Evento Significado
PAYMENT_PENDING Pagamento pendente de processamento
PAYMENT_GATEWAY_CREATED Pagamento criado no gateway
PAYMENT_GATEWAY_CREATING Pagamento sendo criado no gateway
PAYMENT_PAID Pagamento confirmado e processado com sucesso
PAYMENT_LOCALLY_CREATED Pagamento criado no nosso sistema local
PAYMENT_ANTICIPATED Pagamento antecipado
PAYMENT_ABANDONED Pagamento marcado como abandonado após período de inatividade (padrão 20 minutos, configurável por organização)
PAYMENT_APPROVED_BY_RISK_ANALYSIS Pagamento em cartão aprovado na análise manual de risco
PAYMENT_AUTHORIZED Pagamento em cartão autorizado, aguardando captura
PAYMENT_AWAITING_CHARGEBACK_REVERSAL Disputa vencida, aguardando repasse da adquirente
PAYMENT_AWAITING_RISK_ANALYSIS Pagamento em cartão aguardando aprovação na análise manual de risco
PAYMENT_BANK_SLIP_VIEWED Boleto visualizado pelo cliente
PAYMENT_CHARGEBACK_DISPUTE Pagamento em disputa de chargeback (documentação apresentada para contestação)
PAYMENT_CHARGEBACK_REQUESTED Chargeback recebido
PAYMENT_CHECKOUT_VIEWED Fatura visualizada pelo cliente
PAYMENT_CONFIRMED Pagamento confirmado, saldo ainda não disponível
PAYMENT_CREATED Novo pagamento gerado
PAYMENT_CREDIT_CARD_CAPTURE_REFUSED Falha na captura do pagamento em cartão
PAYMENT_DELETED Pagamento removido
PAYMENT_DUNNING_RECEIVED Negativação recebida
PAYMENT_DUNNING_REQUESTED Negativação solicitada
PAYMENT_OVERDUE Pagamento vencido
PAYMENT_PARTIALLY_REFUNDED Pagamento parcialmente reembolsado
PAYMENT_RECEIVED_IN_CASH_UNDONE Recebimento em dinheiro estornado
PAYMENT_RECEIVED Pagamento recebido
PAYMENT_REFUND_IN_PROGRESS Estorno em andamento (liquidação agendada; o estorno ocorre após a execução)
PAYMENT_REFUNDED Pagamento reembolsado
PAYMENT_REPROVED_BY_RISK_ANALYSIS Pagamento em cartão reprovado na análise manual de risco
PAYMENT_RESTORED Pagamento restaurado
PAYMENT_SPLIT_CANCELLED Split do pagamento cancelado
PAYMENT_SPLIT_DIVERGENCE_BLOCK_FINISHED Bloqueio por divergência de split encerrado
PAYMENT_SPLIT_DIVERGENCE_BLOCK Valor bloqueado por divergência de split
PAYMENT_UPDATED Alteração de vencimento ou valor do pagamento

Parâmetros de configuração

Parâmetro Descrição
Método HTTP Sempre POST. Não é configurável no momento.
URL Endpoint público que recebe as notificações e aceita requisições POST.
Eventos Um ou mais eventos do catálogo acima.
Header de autenticação X-Security-Signature-Token. O integrador fornece o valor do token, que enviamos em cada requisição.
Delay em minutos Atraso opcional na entrega, em minutos. Útil quando o integrador precisa de tempo para processar dados relacionados.

Retries

  • Cada evento é retentado até três vezes em caso de falha na entrega.
  • Depois de três tentativas sem sucesso, paramos de enviar o evento.
  • Se os webhooks esperados não chegarem, o integrador deve acionar o gerente de conta para investigação.

Configurações por evento

Abandono de pagamento (PAYMENT_ABANDONED)

  • Tempo padrão de abandono: 20 minutos.
  • Customizável por organização, nas configurações da organização.
  • Dispara quando o pagamento permanece pendente por mais tempo que o configurado, contado a partir da criação do pagamento.

Exemplo de payload

O exemplo completo também está versionado em assets/example_payment_webhook_payload.json.

json { "id": "webhook_5fc77bb8fd18953c20f3052e5e510cbd", "data": { "payment": { "pid": "payment_172838869584a0b655f03a4b5f9b59237a41bd731d", "utm": { "id": "", "term": "", "medium": "", "source": "", "content": "", "campaign": "" }, "kind": "repayment", "total": "2758.35", "status": "paid", "gateway": { "id": "pay_o4np19283091823", "deleted": false, "gateway": "asaas", "checkout_url": "https://www.asaas.com/i/19283091823" }, "checkout": { "pid": "0322-formacao-de-terapeutas-trg-formacao-em-leitura-corporal-e-comportamental-12x-no-boleto", "name": "Professional Training Course - 12x Installments", "slug": "0322-formacao-de-terapeutas-trg-formacao-em-leitura-corporal-e-comportamental-12x-no-boleto", "total": "2997.0", "locked": false, "status": false, "product": { "id": 2, "pid": "prod_17296398896e3ed2ba6909499cbacb55c41546f71e", "kind": "online_course", "name": "Professional Training Course", "tags": "training, combo", "created_at": "2024-10-22T20:31:29.319-03:00", "updated_at": "2024-10-22T20:31:29.319-03:00", "description": "Professional Training Course\r\n\r\n", "privacy_url": null, "user_terms_url": null, "checkouts_count": 20, "organization_id": 1 } }, "customer": { "name": "John Smith", "email": "john.smith@example.com", "active": true, "country": "br", "created_at": "2022-11-15T10:48:25.315-03:00", "doc_number": "12345678900", "updated_at": "2022-11-15T10:48:25.315-03:00", "phone_number": "11999999999", "payments_count": 2 }, "installments": [ { "id": 1000827, "total": "250.85", "status": "paid", "due_date": "2025-02-08", "net_total": "249.86", "paid_date": "2025-02-06", "created_at": "2024-10-08T00:00:00.000-03:00", "gateway_id": "pay_4enfbz5j59jwki6z", "payment_id": 113131, "updated_at": "2025-02-06T11:05:01.689-03:00", "description": "Parcela 5 de 11. Reparcelamento: Professional Training Course - 12x Installments", "billing_type": "PIX", "installment_number": 5, "gateway_status": "RECEIVED", "transaction_receipt_url": "https://www.asaas.com/comprovantes/h/19283091823%3D%3D", "payment_refunds": [ { "id": 67, "total": "200.0", "status": "done", "created_at": "2025-02-05T15:42:58.138-03:00", "updated_at": "2025-02-05T15:42:58.138-03:00", "description": null, "date_created": "2025-02-05T15:42:55.000-03:00", "effective_date": null, "end_to_end_identifier": null, "transaction_receipt_url": null } ] } ] } }, "event": "payments", "version": "1.0.0", "created_at": "2025-02-06T11:05:02.047-03:00", "event_name": "PAYMENT_RECEIVED" }

Campos do payload

Raiz

Campo Tipo Descrição
id string Identificador único do evento de webhook
event string Tipo de recurso a que o webhook se refere (ex.: payments)
version string Versão da API do payload
created_at datetime Quando o evento foi criado
event_name string Evento específico que disparou o webhook

data.payment

Campo Tipo Descrição
pid string Identificador único do pagamento
kind string Tipo do pagamento (ex.: standard, repayment)
total decimal Valor total do pagamento
status string Status atual do pagamento
created_at datetime Criação do pagamento
updated_at datetime Última atualização do pagamento
due_date date Vencimento
paid_date date Data do pagamento, quando aplicável
billing_type string Forma de pagamento (BOLETO, PIX, CREDIT_CARD)
net_total decimal Valor líquido, já descontadas as taxas
installment_count integer Número de parcelas

Valores possíveis de status:

Valor Significado
draft Pagamento em rascunho, ainda não finalizado
pending Aguardando processamento ou ação do cliente
paid Processado e confirmado com sucesso
refunded Reembolsado ao cliente
overdue Vencido
deleted_or_canceled_by_new_payment Cancelado ou substituído por um novo pagamento

data.payment.gateway

Campo Tipo Descrição
id string ID do pagamento no gateway
deleted boolean Se o pagamento foi apagado no gateway
gateway string Identificador do gateway
checkout_url string URL da página de pagamento

data.payment.checkout

Campo Tipo Descrição
pid string Identificador único do checkout
name string Nome do checkout
slug string Identificador amigável para URL
total decimal Valor total do checkout
locked boolean Se o checkout está travado
status boolean Status do checkout
description string Descrição detalhada
integration string Tipo de integração
checkout_type string Tipo do checkout
interest_rate decimal Taxa de juros do parcelamento
installment_count integer Número de parcelas disponíveis
installments_available array Opções de parcelamento
payment_types_available array Formas de pagamento disponíveis

data.payment.checkout.product

Campo Tipo Descrição
pid string Identificador único do produto
kind string Tipo do produto (ex.: online_course)
name string Nome do produto
description string Descrição do produto
tags string Tags do produto
user_terms_url string URL dos termos de uso
privacy_url string URL da política de privacidade
checkouts_count integer Número de checkouts deste produto

data.payment.customer

Campo Tipo Descrição
name string Nome completo do cliente
email string Email do cliente
doc_number string CPF ou CNPJ
phone_number string Telefone
country string Código do país
active boolean Se o cliente está ativo
created_at datetime Criação do cliente
updated_at datetime Última atualização dos dados
payments_count integer Total de pagamentos do cliente

data.payment.utm

Campo Tipo Descrição
id string Identificador UTM
term string Parâmetro utm_term
medium string Parâmetro utm_medium
source string Parâmetro utm_source
content string Parâmetro utm_content
campaign string Parâmetro utm_campaign

data.payment.installments[]

Campo Tipo Descrição
id integer Identificador único da parcela
total decimal Valor da parcela
status string Status da parcela — mesmos valores do pagamento
due_date date Vencimento da parcela
net_total decimal Valor líquido da parcela
paid_date date Data do pagamento, quando aplicável
created_at datetime Criação da parcela
updated_at datetime Última atualização
description string Descrição da parcela
billing_type string Forma de pagamento da parcela
installment_number integer Posição na sequência de parcelas
gateway_id string Identificador da parcela no gateway
gateway_status string Status reportado pelo gateway
transaction_receipt_url string URL do comprovante da transação
payment_refunds array Estornos associados à parcela

payment_refunds[]

Campo Tipo Descrição
id integer Identificador único do estorno
total decimal Valor estornado
status string Status do estorno (ex.: done)
created_at datetime Criação do registro
updated_at datetime Última atualização do registro
description string Descrição do estorno
date_created datetime Quando o estorno foi iniciado
effective_date datetime Quando o estorno foi processado
end_to_end_identifier string Identificador de rastreio da transação (PIX)
transaction_receipt_url string URL do comprovante do estorno

Estrutura de pagamento e parcelas

Na ZeusPay, um pagamento representa uma transação de venda completa e pode ser dividido em várias parcelas. Essa estrutura afeta como os eventos são entregues.

  • Um pagamento pode ter várias parcelas.
  • Cada parcela tem status e rastreio próprios.
  • Mudanças em parcelas disparam eventos referentes ao pagamento-pai.

Entrega de eventos

Múltiplos eventos na criação. Quando um pagamento com parcelas é criado, o integrador recebe um evento por parcela. Uma compra em cartão em 12x gera 12 eventos PAYMENT_CREATED separados, cada um com a informação da parcela específica, todos referenciando o mesmo pagamento-pai.

Eventos posteriores. No caso normal, cada mudança individual de parcela gera um evento — quando a parcela 3 é paga, chega um PAYMENT_PAID. Múltiplos eventos só são enviados quando várias parcelas mudam ao mesmo tempo: um pagamento apagado gera eventos para todas as parcelas restantes; várias parcelas pagas de uma vez geram vários PAYMENT_PAID.

Boas práticas de implementação

  1. Sempre verificar a informação de parcela no payload.
  2. Estar preparado para receber múltiplos eventos do mesmo pagamento.
  3. Usar o pid do pagamento para correlacionar eventos relacionados.
  4. Processar cada evento de parcela de forma independente.

Solicitando webhooks ao gerente de conta

O integrador copia o modelo abaixo e envia para tecnologia@ibft.com.br:

``` Assunto: Webhook Configuration Request - [Nome da Empresa]

Olá, time,

Gostaria de solicitar a configuração de webhooks para nossa integração com a ZeusPay. Segue o detalhamento:

Endpoint URL: https://seu-dominio.com/webhooks/zeuspay Security Token: [token de sua preferência para o header X-Security-Signature-Token]

Eventos desejados: - PAYMENT_CREATED - PAYMENT_PAID - PAYMENT_REFUNDED [adicionar ou remover conforme o catálogo de eventos]

Configuração de delay: - Delay preferido em minutos: [ex.: 5 minutos]

Informações adicionais: - Nome da empresa: [nome] - Contato técnico: [nome e email] - Ambiente: [Produção/Staging]

Fico à disposição para qualquer informação adicional.

Atenciosamente, [seu nome] ```

Referências