> ## 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.

# Reserve an amount, then confirm or cancel (API)

> Reserve an amount on the source balance with a pending transaction, then confirm or cancel it, through the Midaz API.

Reserve an amount now and decide later whether it moves. Use this journey when a check or an approval runs between the request and the transfer.

## Participants

***

* **Your institution.** Your system. It calls the Midaz API and decides whether to confirm or cancel.
* **Midaz.** The ledger. It reserves the amount and moves it only when you confirm.

## Before you start

***

* The accounts and their balances exist. See [Set up a ledger and post the first transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact.md).

## Diagram

***

![Reserve an amount, then confirm or cancel](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-midaz-reserve-then-confirm-or-cancel.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=858baf1304cc3247727646de2d30b2b0)

## Steps through the API

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Midaz | API call | [`POST /v2/transactions/hold`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-hold) | Reserve the amount. The body has the same fields as a direct transaction: `asset`, `amount`, `debits` and `credits`. Send the `X-Idempotency` header. |
| 2 | Midaz | Midaz | Internal step | | Midaz puts the amount of each source on hold. The destinations do not change. |
| 3 | Midaz | Your institution | API answer | | Midaz answers `201` with the transaction in `PENDING`. Keep its `id`. |
| 4 | Your institution | Your institution | Internal step | | Your system decides to confirm or to cancel. |
| 5 | Your institution | Midaz | API call | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`](https://docs.lerian.studio/en/reference/products/midaz/v2/commit-transaction) | Confirm the transaction. |
| 6 | Midaz | Midaz | Internal step | | Midaz takes the amount out of the on-hold amount of each source and credits each destination. |
| 7 | Midaz | Your institution | API answer | | Midaz answers `201` with the transaction in `APPROVED`. |
| 8 | Your institution | Midaz | API call | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`](https://docs.lerian.studio/en/reference/products/midaz/v2/cancel-transaction) | Or cancel the transaction. |
| 9 | Midaz | Midaz | Internal step | | Midaz releases the hold on each source. The destinations do not change. |
| 10 | Midaz | Your institution | API answer | | Midaz answers `201` with the transaction in `CANCELED`. |

## Rules

***

* The amount stays on hold until you confirm or cancel the transaction.
* When the Tracer mode of the ledger is `enforce`, Midaz refuses the reservation before it moves any balance if Tracer does not allow it.

## How you know it finished

***

Read the transaction with [`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}`](https://docs.lerian.studio/en/reference/products/midaz/v2/get-transaction). `APPROVED` means that Midaz moved the held amount. `CANCELED` means that Midaz released the hold.

## What can go wrong

***

| Situation | What you see | What to do |
| - | - | - |
| A source balance does not have enough available amount | `422` with `0018` | Midaz reserved nothing. Add funds, or reserve a smaller amount. |
| The source is an external account | `422` with `0098` | Use an account of your ledger as the source of the reservation. |
| The transaction is not `PENDING`, or another confirmation or cancellation is in progress | `409` with `0099` or `0486` | Read the transaction status before you send another call. |
| The answer to the reservation does not arrive | No answer, or a timeout | Do not assume that the reservation failed. Within the time in the `X-TTL` header (300 seconds by default), send the same request with the same `X-Idempotency` key. A `201` with `X-Idempotency-Replayed: true` returns the first transaction. A `409` with `0084` means that Midaz has no stored result for the first request yet: send it again later with the same key. After that time, read the [operations of the source account](https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-operations-by-account.md) before you send the reservation again. |
| The answer to a confirmation or a cancellation does not arrive | No answer, or a timeout | Read the transaction status. If it is still `PENDING`, send the same call again. |

## Related

***

* [Set up a ledger and post the first transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact.md)
* [Reverse a transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-reverse-a-transaction.md)
* [Midaz error list](https://docs.lerian.studio/en/reference/products/midaz/error-list.md)


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