Reservar un monto y después confirmar o cancelar (API)

Reserva un monto ahora y decide después si se mueve. Usa este recorrido cuando una verificación o una aprobación ocurre entre la solicitud y la transferencia.

Participantes

Tu institución. Tu sistema. Llama a la API de Midaz y decide si confirma o cancela.
Midaz. El ledger. Reserva el monto y solo lo mueve cuando confirmas.

Antes de empezar

Las cuentas y sus saldos existen. Consulta Montar un ledger y registrar la primera transacción.

Diagrama

Reservar un monto y después confirmar o cancelar

Pasos por la API

#	Origen	Destino	Mensaje	API de Lerian	Qué ocurre
1	Tu institución	Midaz	Llamada a la API	`POST /v2/transactions/hold`	Reserva el monto. El cuerpo tiene los mismos campos que una transacción directa: `asset`, `amount`, `debits` y `credits`. Envía el header `X-Idempotency`.
2	Midaz	Midaz	Paso interno		Midaz retiene el monto de cada origen. Los destinos no cambian.
3	Midaz	Tu institución	Respuesta de la API		Midaz responde `201` con la transacción en `PENDING`. Guarda su `id`.
4	Tu institución	Tu institución	Paso interno		Tu sistema decide confirmar o cancelar.
5	Tu institución	Midaz	Llamada a la API	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`	Confirma la transacción.
6	Midaz	Midaz	Paso interno		Midaz saca el monto del monto retenido de cada origen y acredita cada destino.
7	Midaz	Tu institución	Respuesta de la API		Midaz responde `201` con la transacción en `APPROVED`.
8	Tu institución	Midaz	Llamada a la API	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`	O cancela la transacción.
9	Midaz	Midaz	Paso interno		Midaz libera la retención de cada origen. Los destinos no cambian.
10	Midaz	Tu institución	Respuesta de la API		Midaz responde `201` con la transacción en `CANCELED`.

Reglas

El monto queda retenido hasta que confirmas o cancelas la transacción.
Cuando el modo de Tracer del ledger es enforce, Midaz rechaza la reserva antes de mover cualquier saldo si Tracer no la permite.

Cómo saber que terminó

Lee la transacción con GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}. APPROVED significa que Midaz movió el monto retenido. CANCELED significa que Midaz liberó la retención.

Qué puede salir mal

Situación	Qué ves	Qué hacer
Un saldo de origen no tiene monto disponible suficiente	`422` con `0018`	Midaz no reservó nada. Agrega fondos o reserva un monto menor.
El origen es una cuenta externa	`422` con `0098`	Usa una cuenta de tu ledger como origen de la reserva.
La transacción no está en `PENDING`, u otra confirmación o cancelación está en curso	`409` con `0099` o `0486`	Lee el estado de la transacción antes de enviar otra llamada.
La respuesta de la reserva no llega	Ninguna respuesta, o un timeout	No supongas que la reserva falló. Dentro del tiempo del header `X-TTL` (300 segundos por defecto), envía la misma solicitud con la misma clave `X-Idempotency`. Un `201` con `X-Idempotency-Replayed: true` devuelve la primera transacción. Un `409` con `0084` significa que Midaz todavía no tiene el resultado guardado de la primera solicitud: envíala otra vez más tarde con la misma clave. Después de ese tiempo, lee las operaciones de la cuenta de origen antes de enviar la reserva otra vez.
La respuesta de una confirmación o de una cancelación no llega	Ninguna respuesta, o un timeout	Lee el estado de la transacción. Si todavía está en `PENDING`, envía la misma llamada otra vez.

Resumen

Midaz

Tracer

Reporter

Reservar un monto y después confirmar o cancelar (API)

Participantes

Antes de empezar

Diagrama

Pasos por la API

Reglas

Cómo saber que terminó

Qué puede salir mal

Relacionados

​Participantes

​Antes de empezar

​Diagrama

​Pasos por la API

​Reglas

​Cómo saber que terminó

​Qué puede salir mal

​Relacionados

Participantes

Antes de empezar

Diagrama

Pasos por la API

Reglas

Cómo saber que terminó

Qué puede salir mal

Relacionados