Eventos y payloads de webhooks

Estado documental: Contrato propuesto. Los nombres y versiones de eventos se confirmarán con la implementación.

Estructura común

{
  "event_id": "evt_01JXYZ",
  "event_type": "payment.reconciled",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:40:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "reconciled"
    }
  }
}

Contexto opcional

Cuando fue enviado en la creación:

{
  "context": {
    "custom_reference_1": "ROUTE-184",
    "custom_reference_2": "SEAT-12A"
  }
}

Cuando no fue enviado, puede omitirse.

`payment.reported`

{
  "event_id": "evt_01J001",
  "event_type": "payment.reported",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:35:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "reported_by": "seller",
    "state": {
      "operational": "active",
      "financial": "payment_reported"
    }
  }
}

No confirma el pago.

`payment.evidence_received`

{
  "event_id": "evt_01J002",
  "event_type": "payment.evidence_received",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:36:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "evidence_id": "evi_01JXYZ",
    "ocr": {
      "status": "queued"
    },
    "state": {
      "operational": "active",
      "financial": "payment_reported"
    }
  }
}

`payment.detected`

{
  "event_id": "evt_01J003",
  "event_type": "payment.detected",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:38:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "expected_amount": "85.50",
    "detected_amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "movement_detected"
    }
  }
}

Movimiento detectado no siempre significa conciliación terminada.

`payment.reconciled`

{
  "event_id": "evt_01J004",
  "event_type": "payment.reconciled",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:40:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "expected_amount": "85.50",
    "reconciled_amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "reconciled"
    },
    "reconciled_at": "2026-07-20T14:40:00-05:00"
  }
}

`payment.amount_difference`

{
  "event_id": "evt_01J005",
  "event_type": "payment.amount_difference",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:40:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "expected_amount": "85.50",
    "received_amount": "80.00",
    "difference_amount": "5.50",
    "difference_type": "underpayment",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "amount_difference"
    }
  }
}

`payment.ambiguous`

{
  "event_id": "evt_01J006",
  "event_type": "payment.ambiguous",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:41:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "state": {
      "operational": "active",
      "financial": "ambiguous"
    },
    "action_required": "review"
  }
}

`payment.late_detected`

{
  "event_id": "evt_01J007",
  "event_type": "payment.late_detected",
  "event_version": "1.0",
  "created_at": "2026-07-20T15:10:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "expected_amount": "85.50",
    "detected_amount": "85.50",
    "currency": "PEN",
    "detected_at": "2026-07-20T15:10:00-05:00",
    "state": {
      "operational": "expired",
      "financial": "late_detected"
    },
    "action_required": "client_review"
  }
}

`payment.review_required`

{
  "event_id": "evt_01J008",
  "event_type": "payment.review_required",
  "event_version": "1.0",
  "created_at": "2026-07-20T15:11:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "reason": "insufficient_matching_evidence",
    "state": {
      "operational": "active",
      "financial": "review_required"
    }
  }
}

`payment.cancelled`

{
  "event_id": "evt_01J009",
  "event_type": "payment.cancelled",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:36:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "reason": "customer_cancelled",
    "state": {
      "operational": "cancelled",
      "financial": "awaiting_payment"
    }
  }
}

`checkout.expired`

{
  "event_id": "evt_01J010",
  "event_type": "checkout.expired",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:45:02-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "checkout_session_id": "ycs_01JXYZ",
    "expires_at": "2026-07-20T14:45:02-05:00",
    "state": {
      "operational": "expired",
      "financial": "awaiting_payment"
    }
  }
}

`refund.identified`

{
  "event_id": "evt_01J011",
  "event_type": "refund.identified",
  "event_version": "1.0",
  "created_at": "2026-07-20T15:20:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "refund_case_id": "rfc_01JXYZ",
    "amount_to_refund": "4.50",
    "currency": "PEN",
    "reason": "overpayment",
    "refund_executor": "client_company",
    "state": {
      "refund": "refund_identified"
    }
  }
}

YUPY identifica e informa. La empresa ejecuta la devolución.

`refund.pending_execution`

{
  "event_id": "evt_01J012",
  "event_type": "refund.pending_execution",
  "event_version": "1.0",
  "created_at": "2026-07-20T15:25:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "refund_case_id": "rfc_01JXYZ",
    "amount_to_refund": "4.50",
    "currency": "PEN",
    "state": {
      "refund": "refund_pending_execution"
    }
  }
}

`refund.completed`

Se emite cuando la empresa registra la ejecución y YUPY acepta la evidencia correspondiente.

{
  "event_id": "evt_01J013",
  "event_type": "refund.completed",
  "event_version": "1.0",
  "created_at": "2026-07-20T16:10:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "refund_case_id": "rfc_01JXYZ",
    "refunded_amount": "4.50",
    "currency": "PEN",
    "executed_by": "client_company",
    "state": {
      "refund": "refund_completed"
    }
  }
}

Estados separados

Operativos

created
active
expired
cancelled
closed

Financieros

awaiting_payment
payment_reported
movement_detected
reconciliation_pending
reconciled
amount_difference
ambiguous
late_detected
review_required

Entrega

queued
sent
delivered
read
failed

Devolución

refund_identified
refund_requested
refund_under_review
refund_approved
refund_pending_execution
refund_completed
refund_rejected
refund_failed
refund_cancelled

Un mensaje entregado no significa pago confirmado. Una devolución aprobada no significa que ya fue ejecutada.

Versionamiento

Cada evento incluye event_version. Un cambio incompatible debe generar una nueva versión.

Cierre del bloque

La API crea y consulta operaciones.
El SDK presenta Web Checkout.
El chat permite operar POS vía chat.
YUPY consulta internamente las cuentas receptoras.
YUPY concilia.
Los webhooks informan al sistema de la empresa.

La biblioteca completa de endpoints, reportes, callbacks y errores se documentará en el siguiente bloque.

Criterios de aceptación

Todos los eventos tienen event_id.
Los payloads tienen versión.
El contexto se devuelve solo cuando existe.
payment.reported no confirma el pago.
payment.reconciled representa conciliación completada.
Los pagos tardíos se notifican expresamente.
Las diferencias incluyen montos.
Las cancelaciones mantienen estado financiero separado.
YUPY no se presenta como ejecutor de devoluciones.
Los estados operativos, financieros, de entrega y devolución permanecen separados.

API Technical Docs