Set up a ledger and post the first transaction (API)

From the organization and the ledger to a posted transaction and its balances, through the Midaz API.

Create the ledger structure in Midaz, post the first transaction and read the result.

​

Participants

---

• Your institution. Your system. It calls the Midaz API.
• Midaz. The ledger. It keeps the organizations, ledgers, assets, accounts, balances and transactions.

​

Before you start

---

• Your system has a token that can create organizations, ledgers, assets, accounts and transactions in Midaz.
• Choose the code of the asset, for example BRL, and the alias of each account, for example @customer-1.

​

Diagram

---

​

Steps through the API

---

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	API call	POST /v2/organizations	Create the organization with its legalName and legalDocument. Midaz answers 201 with the organization id.
2	Your institution	Midaz	API call	POST /v2/organizations/{organization_id}/ledgers	Create the ledger with a name. Midaz answers 201 with the ledger id.
3	Your institution	Midaz	API call	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets	Create the asset with its name, type and code.
4	Midaz	Midaz	Internal step		Midaz creates the external account @external/<code> of the asset when it does not exist yet.
5	Your institution	Midaz	API call	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts	Create the account with its assetCode, type and alias. Transactions find the account by its alias.
6	Midaz	Midaz	Internal step		Midaz creates the default balance of the account in the same call.
7	Your institution	Midaz	API call	POST /v2/transactions/direct	Post the transaction with its asset, amount, debits and credits. Each leg names the account alias, its organizationId, its ledgerId and its amount. Send the X-Idempotency header.
8	Midaz	Midaz	Internal step		Midaz debits each source balance and credits each destination balance. All of the balances change, or none of them changes.
9	Midaz	Your institution	API answer		Midaz answers 201 with the transaction and its operations. The status in this answer is CREATED.
10	Your institution	Midaz	API call	GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/{alias}/balances	Read the balances of the account.
11	Midaz	Your institution	API answer		Midaz returns each balance of the account with its available and onHold amounts.

​

Rules

---

• A debit is the account that the money leaves. A credit is the account that the money enters. The debits and the credits each total the transaction amount.
• To bring value into the ledger, debit the external account @external/<code> and credit your account. To send value out, debit your account and credit @external/<code>.
• When the Tracer mode of the ledger is enforce, Midaz refuses the transaction 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}. Its status is APPROVED. The balances of the source and destination accounts show the new amounts.

​

What can go wrong

---

Situation	What you see	What to do
The asset of the account does not exist in the ledger	404 with 0034	Create the asset, then create the account.
The debits or the credits do not total the amount	422 with 0073	Correct the amounts and send the transaction again. Midaz moved nothing.
A source balance cannot cover its debit	422 with 0018	Add funds to the source, or post a smaller amount. Midaz moved nothing.
You reuse an idempotency key for a different request	409 with 0084	Use a new key for each new transaction.
You send the same request again before Midaz stores the result of the first	409 with 0084	Keep the key: the first request can still post the transaction. Send the same request again later with the same X-Idempotency key.
The answer to the transaction does not arrive	No answer, or a timeout	Do not assume that the transaction 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 transaction again.

​

Related

---

• Reserve an amount, then confirm or cancel
• Reverse a transaction
• Charge a fee on a transaction
• Register a holder and open an account
• Midaz error list