Liquidar la deuda de comisión (API) - Lerian

Deja pasar un pago cuando el pagador no puede pagar la comisión completa y liquida el resto de la comisión después.

Participantes

Tu institución. Tu sistema. Registra los pagos y los créditos, y puede cobrar la deuda de comisión.
Midaz. El ledger. Abre la deuda de comisión y la liquida, de la deuda más antigua a la más reciente.

Antes de empezar

La comisión es diferible: su paquete de comisiones define deferrable como true en ella. Solo una comisión con isDeductibleFrom en false puede ser diferible.

Diagrama

Liquidar la deuda de comisión

Pasos por la API

#	Origen	Destino	Mensaje	API de Lerian	Qué ocurre
1	Tu institución	Midaz	Llamada a la API	`POST /v2/transactions/direct`	Registra un pago. El pagador tiene lo suficiente para el pago, pero no para la comisión completa.
2	Midaz	Midaz	Paso interno		Midaz mueve el pago y la parte de la comisión que el pagador puede pagar. El resto de la comisión se convierte en deuda de comisión.
3	Midaz	Tu institución	Respuesta de la API		Midaz responde `201`. El metadato `feeDebtOpenings` lista la deuda de comisión que abrió la transacción.
4	Tu institución	Midaz	Llamada a la API	`POST /v2/transactions/direct`	Después, registra una transacción que acredita al pagador.
5	Midaz	Midaz	Paso interno		Midaz usa el crédito para liquidar la deuda de comisión abierta de ese saldo, de la deuda más antigua a la más reciente. Paga la cuenta de comisión de cada deuda.
6	Midaz	Tu institución	Respuesta de la API		Midaz responde `201`. El metadato `feeDebtSettlements` lista las deudas que liquidó el crédito.
7	Tu institución	Midaz	Llamada a la API	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/collect`	O cobra la deuda de comisión abierta sin un crédito. Envía el `accountAlias` del pagador y, si quieres, un `balanceKey` y un `maxAmount`. Envía el header `X-Idempotency`.
8	Midaz	Tu institución	Respuesta de la API		Midaz responde con el monto `collected` y el `transactionId` del cobro.
9	Tu institución	Midaz	Llamada a la API	`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts`	Lee las deudas de comisión del pagador con `account_alias`.
10	Midaz	Tu institución	Respuesta de la API		Midaz lista las deudas, de la más antigua a la más reciente. `openTotal` es el total que el saldo todavía debe.

Reglas

Solo una transacción directa /v2 abre deuda de comisión.
Un crédito al pagador por la API /v2 puede liquidar su deuda de comisión abierta, de la deuda más antigua a la más reciente, hasta el monto del crédito.
Un cobro no cobra comisión, y no puedes revertirlo.

Cómo saber que terminó

Lista las deudas de comisión del pagador con account_alias y status=open. La lista está vacía.

Qué puede salir mal

Situación	Qué ves	Qué hacer
El saldo del pagador ya tiene 256 deudas de comisión abiertas	`422` con `0018`	Midaz rechaza el pago completo. Cobra la deuda de comisión abierta o acredita al pagador, y registra el pago otra vez.
Un cobro no liquida nada	`collected` es `0`, y no hay `transactionId`	El saldo no tiene deuda abierta o no tiene monto disponible, o Midaz no puede mover el monto entre el saldo y una cuenta de comisión. Lee las deudas de comisión, como en el paso 9, y el saldo.
Intentas revertir un cobro	`422` con `0089`	Un cobro es definitivo. Registra una nueva transacción si debes devolver un monto.
La respuesta de un cobro no llega	Ninguna respuesta, o un timeout	Dentro del tiempo del header `X-TTL` (300 segundos por defecto), envía el mismo cobro con la misma clave `X-Idempotency`. Después de un `409` con `0084`, o después de ese tiempo, lee las deudas de comisión del pagador, como en el paso 9, antes de cobrar otra vez.

Relacionados