Webhooks

WizPay notifica a tu backend los eventos del ciclo de vida del pago con un POST JSON a la URL que configures. Los webhooks se administran desde tu panel (Webhooks), por evento y por sistema.

Formato del envío

POST https://tuservidor.com/webhooks/wizpay
Content-Type: application/json
Authorization: Bearer <key_auth>     ← solo si configuraste key_auth en el webhook

Todos los eventos comparten esta envolvente:

{
  "id_event": 2,
  "event": "payment.card.success",
  "id_system": 7,
  "timestamp": "2026-07-16T14:30:00.000Z",
  "...campos específicos del evento": "..."
}

Timeout: 10 segundos. Responde 2xx rápido (encola el trabajo pesado).
Autenticación: si configuraste key_auth, verifica el header Authorization: Bearer <key_auth> en tu receptor y rechaza lo demás.
Un fallo del webhook no afecta la transacción (es fire-and-forget).

⚠️

Los webhooks pueden llegar fuera de orden o (ante reintentos de red) duplicados. Usa reference como clave de idempotencia.

Catálogo de eventos

Pagos con tarjeta

Evento	Cuándo
`payment.card.before`	Justo antes de enviar el cobro al procesador.
`payment.card.success`	Cobro aprobado.
`payment.card.failed`	Cobro rechazado o con error.
`payment.card.fraud_blocked`	Tarjeta bloqueada por antifraude antes de intentar el cobro.

payment.card.success

{
  "event": "payment.card.success",
  "reference": "WP-1784169095747-578AFA46",
  "order_id": "ORD-1042",
  "amount": 350.0,
  "currency": "BOB",
  "card_last4": "1111",
  "card_type": "001",
  "cybersource_id": "7364298471236458210433",
  "auth_code": "831000"
}

payment.card.failed

{
  "event": "payment.card.failed",
  "reference": "WP-...",
  "order_id": "ORD-1042",
  "amount": 350.0,
  "currency": "BOB",
  "card_last4": "1111",
  "card_type": "001",
  "reason": "DECLINED"
}

Tarjetas guardadas

Evento	Cuándo
`payment.saved_card.before`	Antes de un cobro con tarjeta tokenizada.
`payment.saved_card.success`	Cobro con tarjeta guardada aprobado.
`payment.saved_card.failed`	Cobro con tarjeta guardada rechazado/fallido.

QR

Evento	Cuándo
`payment.qr.before`	Antes de confirmar el pago QR.
`payment.qr.success`	Pago QR confirmado.
`payment.qr.failed`	Pago QR rechazado o expirado.

Transacciones (agregados, cualquier método)

Evento	Cuándo
`transaction.success`	Cualquier transacción aprobada.
`transaction.failed`	Cualquier transacción rechazada/fallida.

transaction.success

{
  "event": "transaction.success",
  "reference": "WP-...",
  "amount": 350.0,
  "currency": "BOB",
  "payment_method": "CARD",
  "cybersource_id": "7364298471236458210433"
}

Si solo quieres marcar pedidos como pagados, suscríbete únicamente a transaction.success — cubre tarjeta, tarjeta guardada y QR.

Suscripciones

Evento	Cuándo
`subscription.created`	Se creó una suscripción.
`subscription.charge.before`	Antes del cobro automático del ciclo.
`subscription.charge.success`	Renovación cobrada.
`subscription.charge.failed`	Cobro del ciclo falló (habrá reintento).
`subscription.expired`	Superó los intentos fallidos → `EXPIRED`.
`subscription.cancelled`	Cancelada (manual o por enlace firmado).

subscription.created

{
  "event": "subscription.created",
  "reference": "sub_a1b2c3d4e5f6a7b8c9d0",
  "plan_name": "Plan Pro",
  "amount": 99.9,
  "currency": "BOB",
  "frequency": "MONTHLY",
  "next_charge_at": "2026-08-16 12:00:00"
}

Reembolsos

Evento	Cuándo
`refund.requested`	Se registró la solicitud de reembolso.
`refund.completed`	El procesador ejecutó el reembolso.

Receptor de ejemplo (Express)

app.post('/webhooks/wizpay', express.json(), (req, res) => {
  // 1) autenticar
  const auth = req.headers.authorization
  if (auth !== `Bearer ${process.env.WIZPAY_WEBHOOK_KEY}`) return res.sendStatus(401)
 
  // 2) responder YA (WizPay corta a los 10 s)
  res.sendStatus(200)
 
  // 3) procesar con idempotencia por reference
  const { event, reference } = req.body
  if (alreadyProcessed(reference, event)) return
  if (event === 'transaction.success') markOrderPaid(req.body)
})

Location (países y estados)Errores