Webhooks para API payment gateway

Quando o estado de pagamento de uma encomenda API gateway muda, a Zenofy envia JSON para o URL de webhook configurado no produto (não por pedido API).

Configure URL e segredo opcional na app ao criar ou editar um produto API Gateway (secção Integração com software externo).

Estes eventos são distintos dos webhooks de encomenda (Integrações → Webhook em produtos normais) e dos webhooks SaaS (produtos Software/SaaS).

Entregas falhadas são reenviadas automaticamente (backoff exponencial). Valide com o segredo opcional do produto.

Configuração

O URL do webhook é obrigatório antes de POST /checkout/order-api-gateway funcionar. O segredo é opcional; quando definido, cada pedido inclui X-Signature: sha256=<hex> (HMAC-SHA256 do corpo JSON).

Pedido HTTP de saída

POST · Content-Type: application/json

POST https://your-server.com/webhooks/zenofy HTTP/1.1
Content-Type: application/json
X-Event: payment.succeeded
X-Signature: sha256=abc123...

{ ... }

Verificação da assinatura

Calcule HMAC-SHA256 do corpo JSON com o segredo do produto. Compare com X-Signature (prefixo sha256=). O evento também vem em X-Event (ex. payment.succeeded).

Tipos de evento

Evento	Quando
`payment.succeeded`	Encomenda marcada como paga.
`payment.refunded`	Encomenda reembolsada.
`payment.chargeback`	Encomenda com chargeback (admin).

Campos do corpo JSON

event — tipo (igual a X-Event)
payment_id — id estável derivado da encomenda (ex. pay_…)
checkout_id — id da encomenda (igual ao checkout_id da API de criação)
reference — o seu reference do pedido de criação, se existir
amount — inteiro em unidades menores
currency — código ISO
status — succeeded, refunded ou chargeback
customer — name, email
payment_method — alias como mpesa, card
paid_at — data de pagamento
refunded_at — em payment.refunded
chargeback_at — em payment.chargeback

Exemplos de corpo JSON

payment.succeeded (ilustrativo)

{
  "event": "payment.succeeded",
  "payment_id": "pay_12abcd01",
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "reference": "inv-2026-0042",
  "amount": 2500,
  "currency": "MZN",
  "status": "succeeded",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com"
  },
  "payment_method": "mpesa",
  "paid_at": "2026-05-19T11:22:00+02:00"
}

payment.refunded (ilustrativo)

{
  "event": "payment.refunded",
  "payment_id": "pay_12abcd01",
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "reference": "inv-2026-0042",
  "amount": 2500,
  "currency": "MZN",
  "status": "refunded",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com"
  },
  "payment_method": "mpesa",
  "paid_at": "2026-05-19T11:22:00+02:00",
  "refunded_at": "2026-05-20T09:00:00+02:00"
}

← Criar encomenda API gateway (POST)

Todos os tutoriais