Diferencias y devoluciones

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: Definir cobros complementarios por faltantes y seguimiento de devoluciones ejecutadas por la empresa.

Diferencias de monto

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`GET`	`/v1/payment-orders/{id}/amount-difference`	Consultar diferencia.	No	Ninguno
Integración	`POST`	`/v1/payment-orders/{id}/supplemental-orders`	Crear cobro por faltante.	Obligatoria	payment.supplemental_order_created
Integración	`GET`	`/v1/payment-orders/{id}/supplemental-orders`	Listar órdenes vinculadas.	No	Ninguno
Administración	`POST`	`/v1/amount-differences/{difference_id}/accept`	Aceptar diferencia según política.	Obligatoria	payment.amount_difference_accepted
Administración	`POST`	`/v1/amount-differences/{difference_id}/resolve`	Registrar resolución.	Obligatoria	payment.amount_difference_resolved

Pago incompleto

{
  "expected_amount": "85.50",
  "received_amount": "80.00",
  "difference_amount": "5.50",
  "difference_type": "underpayment",
  "currency": "PEN"
}

Crear orden complementaria

POST /v1/payment-orders/ypt_01JXYZ/supplemental-orders
Idempotency-Key: 53bfc29e-d79f-45df-9428-1a77976e01b5

{
  "reason": "underpayment",
  "amount": "5.50",
  "currency": "PEN"
}

{
  "parent_yupy_transaction_id": "ypt_01JXYZ",
  "supplemental_yupy_transaction_id": "ypt_01JNEW",
  "amount": "5.50",
  "state": {
    "financial": "awaiting_payment"
  },
  "request_id": "req_01JXYZ"
}

Pago en exceso

Un exceso puede originar un caso de devolución. YUPY no devuelve el dinero.

Responsabilidad: YUPY identifica, organiza, alerta y da seguimiento. La empresa revisa, decide, ejecuta la devolución y registra la evidencia.

Devoluciones

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/payment-orders/{id}/refund-cases`	Crear caso vinculado.	Obligatoria	refund.identified
Administración	`GET`	`/v1/refund-cases`	Listar casos.	No	Ninguno
Administración	`GET`	`/v1/refund-cases/{refund_case_id}`	Consultar caso.	No	Ninguno
Administración	`POST`	`/v1/refund-cases/{id}/request`	Registrar solicitud.	Obligatoria	refund.requested
Administración	`POST`	`/v1/refund-cases/{id}/approve`	Aprobar internamente.	Obligatoria	refund.approved
Administración	`POST`	`/v1/refund-cases/{id}/reject`	Rechazar con motivo.	Obligatoria	refund.rejected
Administración	`POST`	`/v1/refund-cases/{id}/execution-attempts`	Registrar ejecución realizada por la empresa.	Obligatoria	refund.completed o refund.execution_failed
Administración	`GET`	`/v1/refund-cases/{id}/execution-attempts`	Listar intentos.	No	Ninguno
Administración	`POST`	`/v1/refund-cases/{id}/cancel`	Cancelar caso cuando proceda.	Obligatoria	refund.cancelled
Administración	`GET`	`/v1/refund-cases/{id}/history`	Consultar auditoría.	No	Ninguno

Crear caso de devolución

POST /v1/payment-orders/ypt_01JXYZ/refund-cases

{
  "reason": "overpayment",
  "amount_to_refund": "4.50",
  "currency": "PEN"
}

{
  "refund_case_id": "rfc_01JXYZ",
  "status": "refund_identified",
  "refund_executor": "client_company",
  "request_id": "req_01JXYZ"
}

Registrar ejecución exitosa

POST /v1/refund-cases/rfc_01JXYZ/execution-attempts

{
  "result": "success",
  "amount": "4.50",
  "currency": "PEN",
  "executed_at": "2026-07-20T16:10:00-05:00",
  "external_reference": "DEV-884120",
  "evidence_id": "evi_ref_01JXYZ"
}

{
  "refund_case_id": "rfc_01JXYZ",
  "status": "refund_completed",
  "request_id": "req_01JXYZ"
}

Registrar intento fallido

{
  "result": "failed",
  "amount": "4.50",
  "currency": "PEN",
  "failure_reason": "recipient_data_not_available"
}

Estados de devolución

refund_identified
refund_requested
refund_under_review
refund_approved
refund_pending_execution
refund_completed
refund_rejected
refund_failed
refund_cancelled

refund_approved no significa que el dinero ya fue devuelto.

Errores principales

HTTP	Código	Descripción
404	`refund_case_not_found`	Caso inexistente.
422	`refund_amount_exceeds_received`	Monto superior al recibido o disponible.
422	`refund_execution_evidence_required`	Falta evidencia de ejecución.
409	`refund_already_completed`	La devolución ya fue registrada.
409	`invalid_state_transition`	Acción incompatible con el estado.