Migrate from API v1 to API v2

​

Ledger routes

• /v2/organizations and /v2/organizations/{organization_id}/ledgers take the organization only.
• /v2/settings/metadata-indexes takes no organization and no ledger.
• /v2/transactions/direct, /v2/transactions/hold, /v2/transactions/block and /v2/transactions/unblock take no organization and no ledger in the path.

​

Organization and ledger in the transaction body

# API v1: the organization and the ledger are in the path
POST /v1/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/ledgers/9c858901-8a57-4791-81fe-4a34d4dd8ab5/transactions/json

# API v2: the organization and the ledger are in each item of the body
POST /v2/transactions/direct

{
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

• Send organizationId and ledgerId in every item. Both are required, and both are UUIDs.
• All items must name the same organization and the same ledger.
• From v4.1.0, direct and hold accept items in different ledgers when every ledger enables crossLedger.enabled. See cross-Ledger transactions.
• block and unblock always need one organization and one ledger in all items.

​

Exceptions

• Annotations. POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/annotation has no v2 route.
• Asset rates. These v1 routes have no v2 route:
  • PUT /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/{external_id}
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/from/{asset_code}
• Tracer. Tracer keeps its own v1 API. See the Tracer API quick start.

​

CRM and Fees in API v2

​

CRM

​

Fees

​

Scope and permission changes

• Send the organization in the path. Do not send the X-Organization-Id header.
• In Fees, send the ledger in the path. Remove ledgerId from the body of packages, estimates, billing packages and billing calculation.
• The package and billing package lists always cover one ledger. In the plugin, ledgerId was an optional query parameter. To list the packages of a whole organization, call the list once for each ledger.
• In CRM instruments, keep ledgerId and accountId in the body.
• Use estimates only to simulate fees. An estimate does not record anything.

​

Transaction contract

• asset: the asset code.
• amount: the total, as a decimal string.
• debits and credits: arrays with one or more items each.

• alias: the account alias.
• organizationId and ledgerId: the UUIDs of the organization and the ledger of the account. See Organization and ledger in the transaction body.
• amount or share: send exactly one of the two.

• Use /v2/transactions/direct to post the transaction at once.
• Use /v2/transactions/hold to create a pending transaction. Then commit or cancel it.

​

Example of a direct transaction

{
  "asset": "BRL",
  "amount": "100.00",
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ],
  "credits": [
    {
      "alias": "@destination",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

​

Fields that the v2 body does not accept

• rate and remaining in an item.
• metadata in an item. The transaction itself still accepts metadata.
• transactionDate.
• balanceKey in an item, on Midaz v4.0.x only. From v4.1.0, each item accepts an optional balanceKey.

​

Responses and errors

​

Transaction responses

• source and destination become debit and credit, in the singular.
• The transaction no longer has route and chartOfAccountsGroupName.
• The operations inside a transaction no longer have route and chartOfAccounts. They keep routeId, routeCode and routeDescription.
• The responses of an operation that you read alone do not change.
• From v4.1.0, a direct or hold that spans ledgers returns a group with groupId and transactions[]. Commit, cancel and revert can also return a group.

​

Errors

• type, title, status and detail.
• code: the Midaz error code. The same error has the same code in v1 and v2.
• errors[]: the field errors, when the request has them.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://errors.lerian.studio/v1/0053",
  "title": "Unexpected Fields in the Request",
  "status": 400,
  "detail": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
  "errors": [
    {
      "message": "unexpected field",
      "location": "transactionDate"
    }
  ],
  "code": "0053"
}

​

Accounts and rules in API v2

​

Account routes

• Read an account by alias and by external code.
• Update and delete an account.
• Count the accounts with HEAD.

​

Holder rules

• When accounting.requireHolder is on, each account needs a holder of the organization. Without a holder, Midaz does not create the account.
• To skip that check, send skip.holder. Midaz accepts it only when overrides.allowHolderSkip is on. Otherwise, Midaz refuses the request with 422 and error 0490.
• When accounting.requireHolder is off and you send no holder, a non-external account gets the holder of its organization. An external account gets no holder.
• When accounting.requireHolder is off, Midaz does not check that the holderId you send exists.
• An account that you create through v1 gets no holder. v1 does not apply these rules.

​

Fees and Tracer

• Fees. Midaz charges a fee when a fee package matches the transaction.
• Tracer. Midaz reserves the transaction in Tracer when the Tracer mode of the ledger is not off.

​

Migration checklist

• List the routes that you use, the product version and the base URL of each service. Separate the routes with a v2 route from the routes that have none. Plan to stop using the routes that have none by April 29, 2027.
• For each transaction, select direct or hold. Update debits, credits, the decimal values and the scope of each item.
• Change CRM aliases to instruments. Move the organization and the ledger of Fees to the path. After the data migration, check the relationships and the identifiers.
• Grant the midaz permissions. Test the holder rules of the accounts in a staging environment.
• Update how you read success and error responses. Test removed fields, invalid input, missing resources and denied access.
• Test each flow that your integration uses: create, read, hold, commit, cancel, revert, block and unblock. Check balances, operations, fees and refusals by Tracer limits.
• Keep sending X-Idempotency and X-TTL on create requests. Do not send the same transaction through v1 and v2 to compare results. Use controlled data and scenarios in a staging environment.
• Move traffic in controlled steps. Monitor errors and financial results. Keep a rollback plan that does not send processed transactions again.