Evidencias, OCR, reclamos y pendientes

Estado documental: Contrato propuesto. Las rutas, campos, límites y tiempos pasan a estado confirmado solo después de su implementación y verificación.

Objetivo: Documentar la carga de constancias, OCR, reclamos del comprador y resolución de casos pendientes.

Evidencia y OCR

Ejemplo: subir constancia

POST /v1/payment-orders/pay_01JXYZ/evidence
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: 8e0752b4-217e-4754-a57f-dabf83cc5b32
Content-Type: multipart/form-data

file=@payment-proof.jpg
evidence_type=payment_receipt
reported_by=seller
shift_id=shf_01JXYZ
device_id=dev_01JXYZ

{
  "result": "evidence_received",
  "evidence_id": "evi_01JXYZ",
  "payment_order_uid": "pay_01JXYZ",
  "payment_reported": true,
  "ocr": {
    "status": "queued"
  },
  "request_id": "req_01JXYZ"
}

Ejemplo: resultado OCR

{
  "evidence_id": "evi_01JXYZ",
  "status": "processed",
  "extracted": {
    "amount": "80.00",
    "currency": "PEN",
    "paid_at_candidate": "2026-07-20T14:37:00-05:00",
    "operation_reference_candidate": "12345678",
    "recipient_candidate": "EMPRESA EJEMPLO"
  },
  "confidence": {
    "amount": 0.98,
    "paid_at": 0.89
  },
  "request_id": "req_01JXYZ"
}

OCR aporta evidencia complementaria. No confirma por sí solo que el dinero llegó.

Si OCR detecta marcas o señales asociadas a Yape o Plin, ese dato describe evidencia sobre el mecanismo utilizado por el pagador. No debe convertirse en un selector de payment_method ni de instrumento. Para Web Checkout QR, el caller solicita payment_method = "qr" y YUPY resuelve internamente el instrumento concreto según la configuración aplicable.

La recepción de evidencia y payment_reported son señales operativas. La confirmación financiera ocurre cuando Reconciliation encuentra y normaliza evidencia suficiente, produciendo payment.reconciled y, cuando corresponde, confirmed_at.

Estados OCR

queued
processing
processed
partial
unreadable
rejected
failed

Reclamos públicos protegidos

Ejemplo: crear reclamo

{
  "transaction_code": "YP-7H2K9",
  "reason": "payment_not_confirmed",
  "buyer_name": "María Ramos",
  "contact": {
    "channel": "email",
    "value": "maria@example.com"
  }
}

{
  "claim_token": "<OPAQUE_CLAIM_TOKEN>",
  "claim_status": "created",
  "request_id": "req_01JXYZ"
}

Este flujo debe usar rate limiting, controles antiabuso, token opaco y exposición mínima de datos.

transaction_code en este flujo público protegido es un código opaco de búsqueda/reclamo. No es payment_order_uid y no debe exponer IDs internos de YUPY.

Gestión de reclamos por la empresa

Casos pendientes

Tipos principales:

late_payment
amount_difference
underpayment
overpayment
ambiguous_payment
evidence_review
cancelled_order_with_payment
refund_required
delivery_failure
unresolved_payment
operational_error

Ejemplo: resolver un caso

POST /v1/pending-cases/case_01JXYZ/resolve

{
  "resolution": "accept_late_payment",
  "reason": "La empresa confirmó que la venta continúa vigente.",
  "evidence_ids": [
    "evi_01JXYZ"
  ]
}

{
  "case_id": "case_01JXYZ",
  "status": "resolved",
  "resolved_at": "2026-07-20T16:30:00-05:00",
  "request_id": "req_01JXYZ"
}

Resoluciones permitidas

confirm_reconciliation
maintain_pending
request_more_evidence
mark_unresolved
accept_late_payment
reject_commercial_operation
create_supplemental_order
create_refund_case
close_without_financial_match

confirm_reconciliation solo corresponde cuando Reconciliation ya produjo confirmación financiera normalizada; resolver un caso no crea por sí mismo esa confirmación.

accept_late_payment representa una decisión comercial sobre evidencia financiera tardía. Si la Payment Order original ya estaba expired o cancelled, esta resolución no la reabre, no elimina su closed_at y no vuelve a ocupar el Counter ya liberado. La evidencia y la resolución permanecen vinculadas a la Payment Order histórica para auditoría y reporting.

Errores principales

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: el ejemplo de evidencia pasó de ypt_... a payment_order_uid/pay_...; se retiró del OCR activo la clasificación de Yape como payment_method_candidate; se aclaró que Yape/Plin son mecanismos observados del pagador y que el flujo QR canónico permanece qr + qr_bbva; se reforzó que evidencia, OCR y payment_reported no constituyen confirmación financiera; se fijó Reconciliation/payment.reconciled como frontera de confirmación; se distinguió transaction_code público de payment_order_uid; y se documentó que accept_late_payment no reabre una Payment Order terminal ni reocupa su Counter.