Saltar al contenido principal

Transaction, Settlement, Split y Refund

Transaction​

Una Transaction representa un acuerdo financiero entre dos o más Accounts — un proceso, no un movimiento directo de dinero. Orquesta los Participants (Accounts con un rol específico, como "comprador" o "vendedor"), sigue una Workflow Version, y eventualmente resulta en un Settlement.

Settlement no es Payout — lea esto antes de asumir que el dinero se mueve de inmediato​

Settlement nunca "envía fondos" por sí mismo. Lo que executeSettlement() realmente hace, siempre, sin importar la política: calcula el Fee, aplica el Split, y convierte la parte de cada Participant en una obligación económica real — un Payable/Receivable adeudado a ese beneficiario. Si esa obligación se paga de inmediato o más tarde es una decisión completamente separada, controlada por PayoutPolicy:

  • Bajo PayoutPolicy.Immediate (el caso común, y el que usa todo ejemplo funcional de este sitio) — el propio Settlement dispara la ejecución real en el mismo momento: bajo Self-Custody, esto significa construir un SigningRequest y una ExecutionLeg por beneficiario (vea Self-Custody), nunca un crédito directo en el Ledger.
  • Bajo PayoutPolicy.Threshold/Scheduled/Manual — la parte del beneficiario se convierte en un Payable (un saldo acumulado, adeudado pero aún no pagado, consultable vía getPayableSummary) y solo se paga efectivamente más tarde, cuando un PayoutBatch se ejecuta. Un PayoutBatch solo puede crearse con trigger = Manual a través de la API pública hoy — ThresholdCrossed y Scheduled existen en el modelo de dominio pero aún no tienen una ruta pública para dispararse; no construya una integración que asuma que cualquiera de los dos está disponible.

Un Payable (lo que un beneficiario tiene por cobrar) nunca es lo mismo que un saldo on-chain. Bajo Self-Custody, una vez que la ExecutionLeg de un beneficiario confirma, el dinero realmente salió de la custodia de la plataforma — enviado al ExecutionDestination propio y registrado de ese beneficiario, una dirección completamente fuera de Ishtaran. No queda nada en el Ledger para mantener como saldo Available de ese beneficiario; la plataforma registra, en cambio, Delivered, el historial acumulado de lo que realmente se pagó (getPayableSummary().paid), nunca confundido con un saldo disponible en el Ledger.

Transmitir (broadcast) la ExecutionLeg de un beneficiario — o la propia leg del Platform Fee — cuesta recursos de red reales (p. ej. Energy/Bandwidth de TRON). Ese costo se cobra por separado del Platform Fee, a una NetworkCostPayerAccount registrada una vez por Organization/AssetNetwork (vea Self-Custody) — sin una, el primer Settlement real con algo que pagar falla antes de siquiera construir un SigningRequest. Platform Fee y Network Execution Fee son dos números distintos, rastreados de forma independiente — nunca asuma que el Fee mostrado en un Settlement ya incluye el costo de red, y nunca asuma que el costo de red es fijo (se cotiza al momento, en cada broadcast). Ver Network Execution para quién provee realmente ese recurso (CUSTOMER_RESOURCES vs ISHTARAN_RESOURCES) y cómo financiarlo por primera vez.

Partial Settlement​

Un Partial Settlement libera solo parte del valor reservado de una Transaction en una llamada, manteniendo el resto reservado para una llamada posterior. Todo Settlement está balanceado en el Ledger — la suma distribuida nunca excede el saldo reservado para esa llamada, y llamarlo repetidamente en la misma Transaction concilia exactamente a los mismos totales que una sola llamada por el monto total.

Split​

El Split define cómo se distribuye un valor entre múltiples Participants en el momento del Settlement — porcentajes o valores fijos, nunca sumando más del total liquidado.

Fee y Pricing Policy​

El Platform Fee es el valor cobrado por la plataforma sobre un Settlement, calculado según la Pricing Policy configurada para la Organization/Application. El Fee propio de la plataforma sigue el mismo modelo de dominio que los clientes — sin camino financiero especial. Esto es distinto del Network Execution Fee descrito arriba — nunca el mismo número, nunca derivado uno del otro.

Refund y Reversal​

Un Refund devuelve, total o parcialmente, un valor ya liquidado o reservado a un Participant de origen — una reversión económica dentro del Ledger (un nuevo asiento compensatorio, vía Reversal; un asiento nunca se borra). Un Refund no "deshace", ni puede deshacer, una transacción que ya confirmó on-chain — no existe tal mecanismo, en ninguna blockchain. Lo que el Refund realmente revierte es la propia contabilidad económica de la plataforma sobre quién debe qué.

Workflow es opcional​

El propio Settlement no tiene dependencia técnica del estado del Workflow — executeSettlement() verifica solo el estado de la propia Transaction (Reserved/PartiallySettled), nunca una Rule o Transition de Workflow. Un Workflow es una forma genuinamente opcional de modelar el ciclo de vida de su propio producto (vea Workflows) y orquestar cuándo usted decide llamar a executeSettlement() — nunca un gate impuesto por la propia plataforma.

Rutas​