Webhooks

PagoFast envía eventos normalizados a la URL configurada por el integrador. La entrega es asíncrona: puede ocurrir después de la respuesta REST y no reemplaza la consulta del recurso para reconciliación.

Configuración del destino

Cuando POST /v1/payments admite webhook_url, esa URL recibe los eventos del pago. Si el ambiente ofrece endpoints de webhook a nivel cuenta, su configuración se administra por separado. No asumas que ambos mecanismos existen: confirmalo en el OpenAPI desplegado.

Usá HTTPS, evitá redirects y no incluyas secretos en la query string. El endpoint debe aceptar el body JSON crudo y los headers de firma.

Eventos

payment.pending
payment.approved
payment.declined
payment.failed
payment.expired
payment.canceled
payment.refunded

Los clientes deben aceptar tipos nuevos sin fallar todo el endpoint. Registrá de manera segura un tipo desconocido y respondé según la política acordada, sin aplicar un cambio de negocio que no comprendés.

Payload

{
  "id": "evt_019f7067f8b47b4e",
  "type": "payment.approved",
  "created_at": "2026-07-17T13:15:08.500Z",
  "data": {
    "payment": {
      "id": "019f7061-2010-7698-8827-e32f86e14298",
      "status": "approved",
      "amount": {
        "value": "12500.00",
        "currency": "ARS"
      },
      "external_reference": "order-9821",
      "payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
      "processor_reference": "trx_739204",
      "updated_at": "2026-07-17T13:15:08.441Z"
    }
  }
}

id identifica el evento y se mantiene en reintentos o replay. created_at es la creación del evento; payment.updated_at indica la versión temporal del recurso.

Headers

Cada delivery incluye como mínimo los headers usados para identificación y firma:

OrderFast-Event-Id: evt_019f7067f8b47b4e
OrderFast-Timestamp: 1784294108
OrderFast-Signature: v1=0c240b7f...

El nombre histórico de los headers es parte del contrato y puede diferir del nombre comercial PagoFast. Verificá siempre la firma antes de procesar el payload.

Handler recomendado

1. Leer el body crudo sin modificarlo.
2. Validar timestamp y firma.
3. Parsear JSON y verificar su estructura.
4. Iniciar una transacción local.
5. Insertar event.id con una restricción única.
6. Si ya existe, responder 2xx sin repetir efectos.
7. Aplicar una transición válida usando payment.updated_at.
8. Persistir y confirmar.
9. Responder 2xx rápidamente.
10. Ejecutar trabajo lento de forma asíncrona en tu sistema.

Ejemplo conceptual:

if !valid_signature(raw_body, headers): return 401
event = parse(raw_body)
if events.exists(event.id): return 204
save_event_and_apply_valid_transition(event)
return 204

Duplicados y orden

La entrega es al menos una vez: el mismo evento puede llegar varias veces. Eventos distintos pueden llegar fuera de orden. No deduzcas el estado solo por type; compará la versión del recurso y evitá retroceder desde un estado final.

Si no podés decidir una transición con seguridad, conservá el evento y consultá GET /v1/payments/{payment_id}.

Respuestas

Cualquier status 2xx confirma recepción y detiene los reintentos de esa entrega. Respondé 4xx para requests inválidos y 5xx cuando una falla temporal impida persistirlos, teniendo en cuenta la política de reintentos.

No devuelvas información sensible ni detalles internos en el body de respuesta.