> ## 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 um valor e depois confirmar ou cancelar (API)

> Reserve um valor no saldo de origem com uma transação pendente e depois confirme ou cancele, pela API do Midaz.

Reserve um valor agora e decida depois se ele se move. Use esta jornada quando uma verificação ou uma aprovação acontece entre o pedido e a transferência.

## Participantes

***

* **Sua instituição.** O seu sistema. Ele chama a API do Midaz e decide se confirma ou cancela.
* **Midaz.** O ledger. Ele reserva o valor e só o move quando você confirma.

## Antes de começar

***

* As contas e seus saldos existem. Veja [Montar um ledger e lançar a primeira transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-create-and-transact.md).

## Diagrama

***

![Reservar um valor e depois confirmar ou cancelar](https://mintcdn.com/lerian-49cb71fc/WuRfbo_y9uSbzyyX/images/pt/d2/id-midaz-reserve-then-confirm-or-cancel.svg?fit=max\&auto=format\&n=WuRfbo_y9uSbzyyX\&q=85\&s=8ba0b9791ee0378936cdeaebe293b361)

## Passo a passo pela API

***

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | Midaz | Chamada de API | [`POST /v2/transactions/hold`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-hold) | Reserve o valor. O corpo tem os mesmos campos de uma transação direta: `asset`, `amount`, `debits` e `credits`. Envie o header `X-Idempotency`. |
| 2 | Midaz | Midaz | Etapa interna | | O Midaz retém o valor de cada origem. Os destinos não mudam. |
| 3 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201` com a transação em `PENDING`. Guarde o `id` dela. |
| 4 | Sua instituição | Sua instituição | Etapa interna | | O seu sistema decide confirmar ou cancelar. |
| 5 | Sua instituição | Midaz | Chamada de API | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`](https://docs.lerian.studio/pt/reference/products/midaz/v2/commit-transaction) | Confirme a transação. |
| 6 | Midaz | Midaz | Etapa interna | | O Midaz tira o valor do valor retido de cada origem e credita cada destino. |
| 7 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201` com a transação em `APPROVED`. |
| 8 | Sua instituição | Midaz | Chamada de API | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`](https://docs.lerian.studio/pt/reference/products/midaz/v2/cancel-transaction) | Ou cancele a transação. |
| 9 | Midaz | Midaz | Etapa interna | | O Midaz libera a retenção de cada origem. Os destinos não mudam. |
| 10 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201` com a transação em `CANCELED`. |

## Regras

***

* O valor fica retido até você confirmar ou cancelar a transação.
* Quando o modo do Tracer no ledger é `enforce`, o Midaz recusa a reserva antes de mover qualquer saldo se o Tracer não a permitir.

## Como saber que terminou

***

Leia a transação com [`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}`](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-transaction). `APPROVED` significa que o Midaz moveu o valor retido. `CANCELED` significa que o Midaz liberou a retenção.

## O que pode dar errado

***

| Situação | O que você vê | O que fazer |
| - | - | - |
| Um saldo de origem não tem valor disponível suficiente | `422` com `0018` | O Midaz não reservou nada. Adicione fundos ou reserve um valor menor. |
| A origem é uma conta externa | `422` com `0098` | Use uma conta do seu ledger como origem da reserva. |
| A transação não está em `PENDING`, ou outra confirmação ou outro cancelamento está em andamento | `409` com `0099` ou `0486` | Leia o status da transação antes de enviar outra chamada. |
| A resposta da reserva não chega | Nenhuma resposta, ou um timeout | Não suponha que a reserva falhou. Dentro do tempo do header `X-TTL` (300 segundos por padrão), envie a mesma requisição com a mesma chave `X-Idempotency`. Um `201` com `X-Idempotency-Replayed: true` devolve a primeira transação. Um `409` com `0084` significa que o Midaz ainda não tem o resultado guardado da primeira requisição: envie-a de novo mais tarde com a mesma chave. Depois desse tempo, leia as [operações da conta de origem](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-all-operations-by-account.md) antes de enviar a reserva de novo. |
| A resposta de uma confirmação ou de um cancelamento não chega | Nenhuma resposta, ou um timeout | Leia o status da transação. Se ela ainda estiver em `PENDING`, envie a mesma chamada de novo. |

## Relacionados

***

* [Montar um ledger e lançar a primeira transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-create-and-transact.md)
* [Estornar uma transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-reverse-a-transaction.md)
* [Lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md)


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