Webhooks
Referencia completa del sobre de entrega, los headers y el catálogo de eventos que Paytami puede enviarte. Para cómo registrar un endpoint y verificar la firma, ve la guía de webhooks.
El sobre de un evento
Toda entrega es un POST con este cuerpo:
{
"id": "evt_7c1a2b3d4e5f60718293a4b5",
"type": "payment.succeeded",
"created_at": "2026-08-28T15:10:00.000Z",
"data": { "...": "el objeto correspondiente al tipo de evento" }
}| Campo | Descripción |
|---|---|
id | Identificador único del evento, prefijo evt_. Úsalo para deduplicar. |
type | Uno de los valores del catálogo de eventos. |
created_at | ISO 8601 en UTC. |
data | El recurso afectado, en el mismo formato que devuelve la API pública. |
Headers de cada entrega
| Header | Descripción |
|---|---|
Paytami-Signature | t=<unix>,v1=<hmac_hex> — ver verificación de firma. |
Paytami-Event-Id | El mismo id del cuerpo (evt_...), para deduplicar sin tener que parsear el JSON primero. |
User-Agent | Paytami-Webhooks/1.0. |
Catálogo de eventos
| Evento | Cuándo se dispara |
|---|---|
payment.succeeded | Un cobro se completó exitosamente. |
payment.failed | Un intento de cobro falló. |
payment.canceled | Un cobro se canceló antes de completarse. |
refund.succeeded | Un reembolso se procesó exitosamente. |
chargeback.opened | Se abrió un contracargo sobre un pago. |
chargeback.won | Un contracargo se resolvió a favor del comercio. |
payout.completed | Un retiro llegó a la cuenta bancaria del comercio. |
payout.failed | Un retiro falló. |
Puedes suscribirte a cualquier subconjunto de estos eventos al registrar tu endpoint, o dejarlo vacío para recibir todos.
payment.succeeded / payment.failed / payment.canceled
data es el mismo objeto Payment que devuelve GET /v1/payments/{id}:
{
"id": "pay_8f2c1a9d4e6b7c0a1d2e3f40",
"status": "captured",
"currency": "GTQ",
"amount": "15000",
"paytami_fee": "435",
"net_amount": "14565",
"checkout_url": "https://app.paytami.com/api/v1/checkout/pay_8f2c1a9d4e6b7c0a1d2e3f40",
"created_at": "2026-08-28T15:04:00.000Z"
}refund.succeeded
{
"id": "refund_4a1f0c2b3d4e5f60718293a4",
"payment_id": "pay_8f2c1a9d4e6b7c0a1d2e3f40",
"amount": "5000",
"currency": "GTQ",
"reason": "requested_by_customer",
"status": "succeeded"
}reason es uno de: requested_by_customer, duplicate_charge, product_not_received, product_unacceptable, merchant_error, fraudulent, other.
chargeback.opened / chargeback.won
{
"id": "chb_9a1b2c3d4e5f60718293a4b5",
"payment_id": "pay_8f2c1a9d4e6b7c0a1d2e3f40",
"amount": "15000",
"currency": "GTQ",
"status": "opened"
}status es opened o won según el evento. No se incluye el motivo del contracargo: es información sensible del proceso de disputa que se maneja directamente entre Paytami y el emisor de la tarjeta.
payout.completed / payout.failed
{
"id": "payout_c7e5b1a2d3e4f5061728394a",
"currency": "GTQ",
"amount": "142000",
"status": "completed",
"bank_account_id": "ba_2d6a9f1e2c3b4a5061728394",
"bank_account_masked": "••••4321",
"requested_at": "2026-08-27T10:00:00.000Z",
"processing_at": "2026-08-27T10:05:00.000Z",
"sent_to_bank_at": "2026-08-27T14:00:00.000Z",
"completed_at": "2026-08-28T09:00:00.000Z",
"failed_at": null,
"canceled_at": null,
"failure_reason": null
}En payout.failed, failure_reason trae el motivo y completed_at queda null.