Skip to main content
De forma predeterminada, Midaz rechaza una transacción cuando el pagador no puede cubrir sus comisiones. Una comisión diferible cambia esto. El pagador paga la parte de la comisión que cubre su monto disponible. El resto se convierte en una deuda de comisión, y la transacción se completa. Los créditos siguientes al pagador liquidan la deuda. La deuda de comisión está desactivada de forma predeterminada. Se aplica solo a las comisiones que marcas como diferibles.

​
Haz que una comisión sea diferible

Define deferrable: true en una comisión cuando creas o actualizas su paquete de comisiones.
  • Solo una comisión con isDeductibleFrom: false puede ser diferible. Midaz rechaza una comisión deducible que también sea diferible con el error 0530.
  • Una comisión diferible abre una deuda solo en una transacción directa /v2. En un hold /v2, Midaz rechaza una comisión sin cobertura con el error 0018.
  • Cuando un saldo ya tiene 256 deudas de comisión abiertas, Midaz rechaza una nueva comisión diferible sin cobertura en él con el error 0018.
Ejemplo. Un pagador tiene 105 y envía 100 con una comisión diferible de 10. La transacción mueve 105: el pago de 100 y 5 de la comisión. Los otros 5 se convierten en una deuda de comisión. La clave de metadatos feeDebtOpenings de la transacción registra la deuda.

​
Cómo se liquida una deuda

Un crédito al saldo del pagador a través de la API /v2 liquida sus deudas de comisión abiertas, de la más antigua a la más reciente. Esto incluye transacciones directas, commits y reversiones. Un crédito menor que una deuda liquida una parte de ella. Cada liquidación mueve el valor del saldo del pagador a la cuenta de comisiones de la deuda. Midaz registra estos movimientos como operaciones de tipo FEE_SETTLEMENT, y la clave de metadatos feeDebtSettlements de la transacción registra las deudas liquidadas. Para liquidar deudas sin un crédito, usa Cobrar deudas de comisión abiertas. Envía el accountAlias del pagador y, de forma opcional, un balanceKey y un maxAmount.
  • Midaz paga las deudas abiertas de ese saldo con su monto disponible, de la más antigua a la más reciente, y no cobra comisión por el cobro.
  • La respuesta incluye el monto collected y el transactionId del cobro.
  • Cuando no se cobra nada, la respuesta incluye collected: "0" y Midaz no crea ninguna transacción.
  • No puedes revertir un cobro. Midaz lo rechaza con el error 0089.

​
Reversiones y deuda de comisión

Cuando reviertes la transacción que abrió una deuda, el pagador recupera la comisión completa:
  • La reversión devuelve la parte de la comisión que el pagador pagó en la transacción original.
  • Midaz cancela la parte de la deuda que sigue abierta.
  • Midaz reembolsa la parte que los créditos siguientes liquidaron. La cuenta de comisiones paga el reembolso, y Midaz lo registra como operaciones de tipo FEE_REFUND. En /v2, el reembolso luego liquida las otras deudas abiertas del pagador, de la más antigua a la más reciente.
La reversión de un crédito que liquidó una deuda puede reabrir esa deuda por el monto liquidado. Cuando el registro de deuda de comisión de una transacción aún no está completo, Midaz rechaza la reversión con el error 0529 (HTTP 409) y no mueve nada. Inténtalo de nuevo más tarde.

​
Consulta las deudas de comisión

  • Listar deudas de comisión devuelve las deudas de un ledger, de la más antigua a la más reciente. Filtra por account_alias, balance_key y status (open o settled). Con account_alias, la respuesta también incluye openTotal, el total que debe el saldo.
  • Obtener una deuda de comisión devuelve una deuda con su monto remaining y su historial de cambios.
Listar y consultar deudas de comisión requiere el permiso midaz/fee-debts con get. Cobrar deuda de comisión requiere post. Cada cambio tiene uno de estos tipos:

​
Cuentas y saldos con deuda de comisión

Midaz se niega a eliminar un saldo, o a eliminar o cerrar su cuenta, cuando:
  • El saldo debe deuda de comisión (error 0527). Acredita el saldo o cobra la deuda primero.
  • Otros saldos deben deuda de comisión al saldo (error 0528), por ejemplo una cuenta de comisiones. Acredita primero los saldos que deben la deuda.

​
Antes de activar la deuda de comisión

  • Ejecuta Midaz v4.2.0 o posterior en todas las instancias del ledger antes de definir deferrable en una comisión. Una versión anterior no puede completar una transacción que lleva deuda de comisión. Después de definirlo, no hagas rollback del ledger a una versión anterior.
  • El ledger guarda las deudas de comisión abiertas en Valkey. Valkey debe ser persistente y conservar estas claves. Consulta Configuración de dependencias.