Reserve an amount, then confirm or cancel (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.

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	API call	`POST /v2/transactions/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`	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`	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`.

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.

Read the transaction with GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}. APPROVED means that Midaz moved the held amount. CANCELED means that Midaz released the hold.

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