> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Reserva un monto en el saldo de origen con una transacción pendiente y después confírmala o cancélala, por la API de Midaz.

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](https://docs.lerian.studio/es/diagrams/lerian-products/midaz-create-and-transact.md).

## Diagrama

***

![Reservar un monto y después confirmar o cancelar](https://mintcdn.com/lerian-49cb71fc/MbifquGny5fsdtVy/images/es/d2/id-midaz-reserve-then-confirm-or-cancel.svg?fit=max\&auto=format\&n=MbifquGny5fsdtVy\&q=85\&s=e377227ab6c2784f0bad552a4200897c)

## 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`](https://docs.lerian.studio/es/reference/products/midaz/v2/create-transaction-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`](https://docs.lerian.studio/es/reference/products/midaz/v2/commit-transaction) | 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`](https://docs.lerian.studio/es/reference/products/midaz/v2/cancel-transaction) | 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}`](https://docs.lerian.studio/es/reference/products/midaz/v2/get-transaction). `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](https://docs.lerian.studio/es/reference/products/midaz/v2/get-all-operations-by-account.md) 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. |

## Relacionados

***

* [Montar un ledger y registrar la primera transacción](https://docs.lerian.studio/es/diagrams/lerian-products/midaz-create-and-transact.md)
* [Revertir una transacción](https://docs.lerian.studio/es/diagrams/lerian-products/midaz-reverse-a-transaction.md)
* [Lista de errores de Midaz](https://docs.lerian.studio/es/reference/products/midaz/error-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.