Resolve Transfer Reconciliation

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/{transferId}/reconciliation/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "action": "SETTLE",
  "reason": "JD cabine ticket 4471 confirms settlement at 10:42",
  "evidenceReference": "STR0008 ctrl 202609061042"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"action\": \"SETTLE\",\n  \"reason\": \"JD cabine ticket 4471 confirms settlement at 10:42\",\n  \"evidenceReference\": \"STR0008 ctrl 202609061042\"\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({
    action: 'SETTLE',
    reason: 'JD cabine ticket 4471 confirms settlement at 10:42',
    evidenceReference: 'STR0008 ctrl 202609061042'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/{transferId}/reconciliation/resolve', 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}/reconciliation/resolve"

payload = {
    "action": "SETTLE",
    "reason": "JD cabine ticket 4471 confirms settlement at 10:42",
    "evidenceReference": "STR0008 ctrl 202609061042"
}
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",
  "status": "COMPLETED",
  "reconciliationStatus": "RESOLVED",
  "resolvedAt": "2026-09-06T12:00:00Z",
  "midazTransactionId": "11111111-2222-3333-4444-555555555555",
  "compensationTransactionId": "66666666-7777-4888-9999-aaaaaaaaaaaa",
  "previousCompensationTransactionId": "33333333-4444-4555-8666-777777777777"
}

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

Resolve Transfer Reconciliation

Use this endpoint to resolve by hand one transfer that reconciliation parked in manual review. Each action serves exactly one transfer type.

On an outbound TED whose hold is preserved:

SETTLE commits the hold and completes the transfer.
REVERT cancels the hold and fails the transfer.

On an inbound credit whose STR0010R2 chargeback refund the automatic path could not finish:

RE_POST pays the refund again. Before it pays anything, it asks the ledger what became of the compensation already on file. Only a compensation that moved nothing licenses a posting. One that already moved the gross closes the row where it stands, with nothing posted. One that moved any other amount is refused for good. Even the licensed case first searches the ledger for this chargeback’s own refunds and adopts a live one already paying the gross instead of filing a second, so a refund that was paid can never be paid twice. A compensation on file that the ledger prices as live enters that same search as one of its members, so while a second live refund stands beside it, the row is not closed on it and no difference is quoted against it.
SETTLED_BY_HAND posts nothing and records that the refund was arranged outside this platform, so it requires an evidenceReference that names the outside movement. Because this record also takes the row off the pending list, it is filed only over a ledger reading that completed and priced every posting it saw. A scan that the ledger truncated, a scan that it could not answer, and a scan holding a posting in a status this service cannot price are each refused as not confirmed instead of closed. Send the same request again under a new X-Idempotency key.

When the ledger holds more than one live refund for a chargeback, this platform debited the beneficiary more than once, and no action here takes a posting back: RE_POST is refused, and SETTLED_BY_HAND closes the row with every one of those transactions named on the closing record.

On every action except RE_POST, the ledger moves first, and the row is written only once the ledger reaches the state that the resolution claims, so a failure midway leaves the transfer exactly as it was found. RE_POST runs in the other order, because it is the one action that pays: the new compensation is stamped on the transfer the moment the ledger returns its ID, before anything judges what it paid. Every later failure leaves the row parked and naming the money, and repeating the identical request under a new X-Idempotency key (the key that earned the failure is fenced) converges on that stamp instead of paying a second time. A stamped compensation that the ledger cannot find is undecided, not absent, and is refused: wait, repeat the identical request under a new X-Idempotency key, and close the row with SETTLED_BY_HAND if it never clears. A refund that the ledger prices at anything other than the gross is a verdict that no retry changes, whether it is the compensation on file, one that the ledger scan found, or the one that this request filed: the row stays parked, the remaining difference is settled outside this platform, and the row is closed with SETTLED_BY_HAND.

The operator reason is required on every action. It is recorded in the audit trail with the subject resolved from the bearer token. This endpoint requires the transfers:resolve permission and a user token.

POST

transfers

{transferId}

reconciliation

resolve

Resolve Transfer Reconciliation

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/{transferId}/reconciliation/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "action": "SETTLE",
  "reason": "JD cabine ticket 4471 confirms settlement at 10:42",
  "evidenceReference": "STR0008 ctrl 202609061042"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"action\": \"SETTLE\",\n  \"reason\": \"JD cabine ticket 4471 confirms settlement at 10:42\",\n  \"evidenceReference\": \"STR0008 ctrl 202609061042\"\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({
    action: 'SETTLE',
    reason: 'JD cabine ticket 4471 confirms settlement at 10:42',
    evidenceReference: 'STR0008 ctrl 202609061042'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/{transferId}/reconciliation/resolve', 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}/reconciliation/resolve"

payload = {
    "action": "SETTLE",
    "reason": "JD cabine ticket 4471 confirms settlement at 10:42",
    "evidenceReference": "STR0008 ctrl 202609061042"
}
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",
  "status": "COMPLETED",
  "reconciliationStatus": "RESOLVED",
  "resolvedAt": "2026-09-06T12:00:00Z",
  "midazTransactionId": "11111111-2222-3333-4444-555555555555",
  "compensationTransactionId": "66666666-7777-4888-9999-aaaaaaaaaaaa",
  "previousCompensationTransactionId": "33333333-4444-4555-8666-777777777777"
}

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

Operator decision, justification, and evidence reference (required for SETTLED_BY_HAND).

action

enum<string>

required

Available options:

SETTLE,

REVERT,

RE_POST,

SETTLED_BY_HAND

Example:

"SETTLE"

reason

string

required

Required string length: 10 - 500

Example:

"JD cabine ticket 4471 confirms settlement at 10:42"

evidenceReference

string

Required for SETTLED_BY_HAND.

Maximum string length: 200

Example:

"STR0008 ctrl 202609061042"

Response

Indicates that the transfer was resolved. A ledger reference that names nothing is omitted instead of sent as the all-zeroes UUID: compensationTransactionId and previousCompensationTransactionId belong to the inbound actions, and midazTransactionId is absent on an inbound close of a row whose credit transaction was never proven.

transferId

string<uuid>

Example:

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

status

string

Example:

"COMPLETED"

reconciliationStatus

string

Example:

"RESOLVED"

resolvedAt

string<date-time>

Example:

"2026-09-06T12:00:00Z"

midazTransactionId

string<uuid>

Example:

"11111111-2222-3333-4444-555555555555"

compensationTransactionId

string<uuid>

Example:

"66666666-7777-4888-9999-aaaaaaaaaaaa"

previousCompensationTransactionId

string<uuid>

Example:

"33333333-4444-4555-8666-777777777777"

Transfers API

Dashboard & Reconciliation API

TED In Operations API

Webhooks API

Webhook DLQ API

Error handling

Resolve Transfer Reconciliation

Authorizations

Headers

Path Parameters

Body

Response