Check Ledger Routing Readiness

curl --request GET \
  --url https://api.example.com/v1/transfers/routing/preflight \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/transfers/routing/preflight"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/transfers/routing/preflight', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "ready": false,
  "documentState": "bindings",
  "legacyPendingInitiations": 2,
  "readbackBudgetExhausted": false,
  "scopes": [
    {
      "organizationId": "11111111-1111-4111-8111-111111111111",
      "ledgerId": "22222222-2222-4222-8222-222222222222",
      "transferType": "TED_OUT",
      "transferCount": 7,
      "lastTransferAt": "2026-09-16T12:30:00Z",
      "derivedFrom": "ted_out_refund",
      "covered": true,
      "mode": "routes",
      "routesVerified": "ok",
      "membership": "verified"
    }
  ]
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "invalid request body",
  "code": "BTF-0001",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing Token",
  "code": "BTF-0401",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0405",
  "title": "Forbidden",
  "status": 403,
  "detail": "the credential is not allowed to perform transfers:create on this request",
  "code": "BTF-0405",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded",
  "code": "BTF-0429",
  "category": "rate_limit",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-9000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal server error",
  "code": "BTF-9000",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0200",
  "title": "Not Found",
  "status": 404,
  "detail": "transfer not found",
  "code": "BTF-0200",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    {
      "message": "transferId must be a valid UUID",
      "location": "body.senderAccountId"
    }
  ],
  "upstream": {
    "code": "AAC90",
    "message": "Assinatura invalida"
  }
}

Check Ledger Routing Readiness

Use this endpoint to check whether this tenant is ready for ledger-scoped routing. The report lists one line per Midaz organization, ledger, and transfer type:

Every tuple that has carried a transfer, whatever its outcome. transferCount measures traffic, not settlement.
Every tuple that the chargeback path demands although nothing has transferred on it and no binding addresses it (transferCount 0): the inbound tuple that every TED_OUT ledger owes for the refund (derivedFrom: ted_out_refund), the outbound tuple that every TED_IN ledger owes for the compensation (derivedFrom: ted_in_compensation), and the CROSS_CORE_RETURN_IN tuple that every CROSS_CORE_OUT ledger owes for a return from the other core (derivedFrom: cross_core_return).
One organization-level line per Midaz organization that the tenant registered to receive inbound TED and that has no inbound binding at any ledger (derivedFrom: ispb_onboarded_organization). ledgerId is empty, because the recipient account record decides the ledger when the credit arrives. Any inbound line for that organization answers the demand, and the line disappears.

These tuples are demanded of a ledger that the configuration only declares, in either mode, as well as of one that has carried traffic. Once a binding answers the demand, the line is reported as a configured scope with no derivedFrom, and it is still judged. ready is true only when every line clears. A declared scope, and the chargeback counterpart of a declared binding, are judged like any other line, because a binding is a promise about money that the operator intends to move, and a route that does not verify on it holds or refuses that ledger’s first transfer. An explicit mode: omit answers any line, because it posts with the route fields left off, and a chargeback against money that landed unrouted posts back unrouted. The one pairing that it cannot express, a ledger that routes its incoming credits while it declares their compensation unrouted, is refused when the configuration is read and never reaches this report.

The report also lists the bindings that the configuration carries, each with whether a binding covers it and whether the accounting routes it names exist inside that exact scope in Midaz. legacyPendingInitiations counts the live initiations still pending from before ledger-scoped routing, which this service answers with 409 (BTF-0112). readbackBudgetExhausted is false for every configuration that the contract accepts. A true value means a service defect: report it instead of retrying. The scopes past the budget then read unavailable.

This is a read-only administrative endpoint. It never writes the configuration and never moves money. It does not require the X-Organization-Id header. In multi-tenant deployments the report is scoped to the caller’s resolved tenant.

GET

transfers

routing

preflight

Check Ledger Routing Readiness

curl --request GET \
  --url https://api.example.com/v1/transfers/routing/preflight \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/transfers/routing/preflight"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/transfers/routing/preflight', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "ready": false,
  "documentState": "bindings",
  "legacyPendingInitiations": 2,
  "readbackBudgetExhausted": false,
  "scopes": [
    {
      "organizationId": "11111111-1111-4111-8111-111111111111",
      "ledgerId": "22222222-2222-4222-8222-222222222222",
      "transferType": "TED_OUT",
      "transferCount": 7,
      "lastTransferAt": "2026-09-16T12:30:00Z",
      "derivedFrom": "ted_out_refund",
      "covered": true,
      "mode": "routes",
      "routesVerified": "ok",
      "membership": "verified"
    }
  ]
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "invalid request body",
  "code": "BTF-0001",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing Token",
  "code": "BTF-0401",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0405",
  "title": "Forbidden",
  "status": 403,
  "detail": "the credential is not allowed to perform transfers:create on this request",
  "code": "BTF-0405",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded",
  "code": "BTF-0429",
  "category": "rate_limit",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-9000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal server error",
  "code": "BTF-9000",
  "category": "plugin",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin"
}

{
  "type": "https://errors.lerian.studio/v1/BTF-0200",
  "title": "Not Found",
  "status": 404,
  "detail": "transfer not found",
  "code": "BTF-0200",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    {
      "message": "transferId must be a valid UUID",
      "location": "body.senderAccountId"
    }
  ],
  "upstream": {
    "code": "AAC90",
    "message": "Assinatura invalida"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id.

Scopes

api

OAuth2ClientCredentials

TED transfer API access

api

OAuth2Password

TED transfer API access

Resposta

Indicates that the readiness report was returned.

ready

boolean

true only when every line in scopes clears.

Exemplo:

false

documentState

enum<string>

Opções disponíveis:

absent,

sentinel,

empty,

bindings

Exemplo:

"bindings"

legacyPendingInitiations

integer

Live initiations still pending from before ledger-scoped routing.

Exemplo:

2

readbackBudgetExhausted

boolean

false for every configuration that the contract accepts. true means a service defect; the scopes past the budget read unavailable.

Exemplo:

false

scopes

object[]

Show child attributes

API de Transferências

Painel e API de Conciliação

API de Operações TED In

API de Webhooks

API de Webhook DLQ

Tratamento de erros

Eventos

Check Ledger Routing Readiness

Autorizações

Scopes

Resposta