Repair Transfer Ledger Scope

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "ledgerId": "22222222-2222-4222-8222-222222222222",
  "reason": "stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger",
  "evidenceReference": "CRM ticket 8812"
}
'

package main

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

func main() {

	url := "https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair"

	payload := strings.NewReader("{\n  \"ledgerId\": \"22222222-2222-4222-8222-222222222222\",\n  \"reason\": \"stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger\",\n  \"evidenceReference\": \"CRM ticket 8812\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ledgerId: '22222222-2222-4222-8222-222222222222',
    reason: 'stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger',
    evidenceReference: 'CRM ticket 8812'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair"

payload = {
    "ledgerId": "22222222-2222-4222-8222-222222222222",
    "reason": "stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger",
    "evidenceReference": "CRM ticket 8812"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440003",
  "ledgerId": "22222222-2222-4222-8222-222222222222",
  "repairedAt": "2026-09-18T09:30:00Z"
}

{
  "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"
  }
}

{
  "error": {
    "code": "BTF-0401",
    "service": "plugin",
    "category": "deterministic",
    "message": "Missing or invalid authentication token",
    "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "error": {
    "code": "BTF-0429",
    "service": "plugin",
    "category": "rate_limit",
    "message": "Too many requests. Retry after the interval indicated by the `Retry-After` header.",
    "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

Repair Transfer Ledger Scope

Use this endpoint to correct the accounting scope of one transfer whose ledger is the all-zeroes UUID. That value addresses no Midaz ledger and matches no routing binding, so the transfer’s refund stays held, and no configuration that an operator could write frees it.

The operator supplies the ledger, because only a person may authorize an edit to the scope of a money row. CRM must report the same ledger for the transfer’s own account before anything is written; if the two disagree, nothing is written. No money moves here and no ledger call is made: the next reconciliation or poller cycle moves the money, once, on the routes that the repaired ledger resolves.

The operator reason is required. It is recorded in the transfer’s status history and audit trail with the subject from the bearer token. This endpoint requires the transfers:repair permission and a user token.

POST

transfers

{transferId}

scope

repair

Repair Transfer Ledger Scope

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "ledgerId": "22222222-2222-4222-8222-222222222222",
  "reason": "stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger",
  "evidenceReference": "CRM ticket 8812"
}
'

package main

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

func main() {

	url := "https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair"

	payload := strings.NewReader("{\n  \"ledgerId\": \"22222222-2222-4222-8222-222222222222\",\n  \"reason\": \"stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger\",\n  \"evidenceReference\": \"CRM ticket 8812\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ledgerId: '22222222-2222-4222-8222-222222222222',
    reason: 'stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger',
    evidenceReference: 'CRM ticket 8812'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ted.sandbox.lerian.net/v1/transfers/{transferId}/scope/repair"

payload = {
    "ledgerId": "22222222-2222-4222-8222-222222222222",
    "reason": "stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger",
    "evidenceReference": "CRM ticket 8812"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440003",
  "ledgerId": "22222222-2222-4222-8222-222222222222",
  "repairedAt": "2026-09-18T09:30:00Z"
}

{
  "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"
  }
}

{
  "error": {
    "code": "BTF-0401",
    "service": "plugin",
    "category": "deterministic",
    "message": "Missing or invalid authentication token",
    "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "error": {
    "code": "BTF-0429",
    "service": "plugin",
    "category": "rate_limit",
    "message": "Too many requests. Retry after the interval indicated by the `Retry-After` header.",
    "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

Authorizations

Authorization

string

header

required

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

Headers

X-Organization-Id

string<uuid>

required

Midaz organization scope for the request, used for downstream CRM, Fees, and Midaz calls. Required on org-scoped transfer routes in every deployment mode; a missing or non-UUID value returns 400. This is not the tenant identifier — tenantId is derived from the bearer JWT or authenticated context, never from this header. Background workers (TED IN poller, reconciliation) have no request header and, in single-tenant mode, fall back to the deployment's ORGANIZATION_ID env.

X-Idempotency

string

required

Required idempotency key for safe retries. Use a UUID v4 or unique business identifier. If the same key is sent again and the original request was already processed, the cached response is returned.

See Retries and idempotency for details.

Maximum string length: 255

Path Parameters

transferId

string<uuid>

required

The unique identifier of the transfer.

Body

application/json

The ledger that the operator asserts, the justification, and an optional evidence reference.

ledgerId

string<uuid>

required

Example:

"22222222-2222-4222-8222-222222222222"

reason

string

required

Required string length: 10 - 500

Example:

"stranded row from the pre-routing backlog; CRM ticket 8812 names this ledger"

evidenceReference

string

Maximum string length: 200

Example:

"CRM ticket 8812"

Response

Indicates that the transfer's ledger scope was repaired.

transferId

string<uuid>

Example:

"770e8400-e29b-41d4-a716-446655440003"

ledgerId

string<uuid>

Example:

"22222222-2222-4222-8222-222222222222"

repairedAt

string<date-time>

Example:

"2026-09-18T09:30:00Z"

Transfers API

Dashboard & Reconciliation API

TED In Operations API

Webhooks API

Webhook DLQ API

Error handling

Repair Transfer Ledger Scope

Authorizations

Headers

Path Parameters

Body

Response