Sincronizar eventos de cambios de estado del Pago

En este artículo te orientamos para que entiendas cómo se generan los eventos del pago y puedas sincronizarlos en tu sistema, si es que lo necesitas.

El pago tiene un ciclo de vida desde su creación hasta su estado final, que puedes profundizar en el artículo sobre los estados del pago.

Cada vez que el pago cambia de estado, se genera un evento en el sistema. Es posible que quieras sincronizar en tu aplicación algunos de estos eventos que son importantes para tu lógica de negocio.

En caso de haber configurado un webhook y estar suscrito a los eventos payment.updated y payment.retrying), recibirás un webhook con dicho evento.

Sucesión de eventos típica

Típicamente el flujo de eventos que recibirás, tiene este orden:

• payment.created: El Pago es creado, y su estado es pending_submission
• payment.updated: El Pago es enviado y pasa a estado submitted
• payment.retrying: El Pago vuelve rechazado pero se reintenta automáticamente, el pago pasa a estado pending_submission
• Luego el payment.updated y el payment.retrying anterior se repiten, según la cantidad de intentos automáticos que tenga configurado tu usuario
• Por último recibes un payment.updated con el status final del pago (approved o rejected).

Buenas prácticas de procesamiento

De lo explicado anteriormente se deduce que cada vez que ocurra un rechazo y sea reintentado automáticamente, recibirás un evento payment.retrying.

Por otro lado, cada vez que tengamos un rechazo y ya no lo reintentemos más, te enviaremos un evento payment.updated. En dicho evento encontrarás que el pago estará en status rejected.

Te recomendamos que uses estas últimas dos condiciones para enterarte y procesar un rechazo parcial o un rechazo final en tu aplicación.

Motivos de rechazo

Si necesitas guardar en tu sistema información sobre los motivos de rechazo considera que hay dos tipos de información que recibes:

• rejection_code(es una categoría estandarizada por Debi, y aparece a nivel del pago una vez terminado el ciclo de reintentos) y
• response_message (motivo literal que nos responde la entidad financiera). Este campo figura tanto a nivel del objeto principal del pago como dentro de cada entrada del array logs, permitiendo acceder al detalle de cada etapa del procesamiento. El JSON recibido en los eventos del pago incluye un campo logs, que es un array de objetos. Cada objeto dentro de logs representa una acción en el historial del pago, con información como el estado, la fecha y el canal utilizado. A partir de este array es posible reconstruir el flujo completo de intentos de cobro, incluyendo los mensajes de respuesta asociados a cada uno.

Más información en el artículo sobre los Tipos de rechazo.

Estructura del objeto del evento

El objeto que recibes en los eventos payment.updated y payment.retrying tiene la siguiente estructura (aquí se muestra un ejemplo realista con un solo reintento y estado final aprobado):

{
  "object": {
    "id": "PY3Ja9W8opJ6",
    "logs": [
      {
        "action": "created",
        "status": "pending_submission",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-02T18:47:23-03:00",
        "response_message": ""
      },
      {
        "action": "submitting",
        "status": "submitted",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-02T18:52:07-03:00",
        "response_message": ""
      },
      {
        "action": "updated status",
        "status": "rejected",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-04T00:00:00-03:00",
        "response_message": "Falta de fondos"
      },
      {
        "action": "auto retrying",
        "status": "pending_submission",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-08T09:08:44-03:00",
        "response_message": ""
      },
      {
        "action": "submitting",
        "status": "submitted",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-08T18:31:08-03:00",
        "response_message": ""
      },
      {
        "action": "updated status",
        "status": "approved",
        "gateway": "GWw06AGDQgD8",
        "processed_at": "2025-07-11T00:00:00-03:00",
        "response_message": "Transacción aceptada"
      }
    ],
    "paid": true,
    "amount": 5121542.07,
    "object": "payment",
    "status": "approved",
    "gateway": "GWw06AGDQgD8",
    "refunds": [],
    "session": null,
    "currency": "ARS",
    "customer": {
      /* ... */
    },
    "livemode": true,
    "metadata": {
      "metadata_field_1": 72,
      "metadata_field_2": "esto es metadata"
    },
    "retryable": false,
    "created_at": "2025-07-02T18:47:23-03:00",
    "refundable": true,
    "updated_at": "2025-07-15T09:03:51-03:00",
    "binary_mode": false,
    "charge_date": "2025-07-02",
    "description": "Pago de la mensualidad Correspondiente al mes 6/25",
    "next_action": null,
    "subscription": null,
    "payment_method": {
      /* ... */
    },
    "rejection_code": "",
    "updated_status": null,
    "amount_refunded": 0,
    "response_message": "Transacción aceptada",
    "amount_refundable": 5121542.07,
    "submissions_count": 2,
    "gateway_identifier": "19047008",
    "can_auto_retry_until": null,
    "effective_charged_date": "2025-07-11",
    "provider_rejection_code": "",
    "auto_retries_max_attempts": null,
    "subscription_payment_number": null,
    "estimated_accreditation_date": "2025-07-15"
  }
}

En este ejemplo, el pago fue creado, enviado, rechazado por falta de fondos, reintentado automáticamente, enviado nuevamente y finalmente aprobado. Así puedes ver cómo se refleja toda la sucesión de eventos en el array logs.

Campos del array logs

Cada elemento del array logs contiene:

• action: La acción realizada (created, submitting, updated status, auto retrying)
• status: El estado del pago en ese momento
• gateway: El identificador del gateway utilizado
• processed_at: Fecha y hora del procesamiento
• response_message: Mensaje de respuesta del procesador (incluye motivos de rechazo cuando aplica)