Close Unsettled TED IN Credit

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "outcome": "RETURNED",
  "note": "funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812"
}
'

package main

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

func main() {

	url := "https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close"

	payload := strings.NewReader("{\n  \"outcome\": \"RETURNED\",\n  \"note\": \"funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812\"\n}")

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

	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-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    outcome: 'RETURNED',
    note: 'funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close', 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/ted-in/unsettled/{messageId}/close"

payload = {
    "outcome": "RETURNED",
    "note": "funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "messageId": "770e8400-e29b-41d4-a716-446655440003",
  "outcome": "RETURNED",
  "note": "funds wired back to the paying bank under control number 20260901000042",
  "amount": "15000.00",
  "closedAt": "2026-02-01T15:30:00Z",
  "closedBy": "acme/ana.souza",
  "retentionClosed": true,
  "retentionReason": "RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED",
  "retainedAt": "2026-02-01T15:29:55Z",
  "devolutionClosed": true,
  "devolutionPreviousStatus": "RETAINED",
  "devolutionStatus": "RETURNED"
}

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

Close Unsettled TED IN Credit

Use this endpoint to record where an unsettled inbound credit actually went, after a person moved it by hand. An inbound credit is unsettled when its message carries an open retention (neither credited nor returned), or when its devolution sits in RETAINED (a return that the tenant never authorized) or FAILED (a return that the clearing house refused).

No money moves here, and no ledger or JD call is made. Every outcome names an act performed outside this system, and this endpoint is the record of it:

RETURNED: a person sent the funds back to the paying bank, out of band, under the return control number that the devolution row has kept since the day of receipt.
CREDITED: a person credited the beneficiary.
ABSORBED: the tenant keeps funds that reached neither end.

A credit written down twice, as an open retention and as a RETAINED devolution, is closed on both rows in one transaction or on neither. A retention that the poller resolves by itself is refused: the credit lands on its own once the blocking condition lifts, and declaring it settled would tell the tenant to keep money that the service is about to deliver.

This is a tenant-wide administrative action. It requires the transfers:resolve permission and a user token, because the closure records which person decided. It does not require the X-Organization-Id header. In multi-tenant deployments it is scoped to the caller’s resolved tenant database.

POST

transfers

ted-in

unsettled

{messageId}

Close Unsettled TED IN Credit

curl --request POST \
  --url https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "outcome": "RETURNED",
  "note": "funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812"
}
'

package main

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

func main() {

	url := "https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close"

	payload := strings.NewReader("{\n  \"outcome\": \"RETURNED\",\n  \"note\": \"funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812\"\n}")

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

	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-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    outcome: 'RETURNED',
    note: 'funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812'
  })
};

fetch('https://ted.sandbox.lerian.net/v1/transfers/ted-in/unsettled/{messageId}/close', 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/ted-in/unsettled/{messageId}/close"

payload = {
    "outcome": "RETURNED",
    "note": "funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "messageId": "770e8400-e29b-41d4-a716-446655440003",
  "outcome": "RETURNED",
  "note": "funds wired back to the paying bank under control number 20260901000042",
  "amount": "15000.00",
  "closedAt": "2026-02-01T15:30:00Z",
  "closedBy": "acme/ana.souza",
  "retentionClosed": true,
  "retentionReason": "RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED",
  "retainedAt": "2026-02-01T15:29:55Z",
  "devolutionClosed": true,
  "devolutionPreviousStatus": "RETAINED",
  "devolutionStatus": "RETURNED"
}

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

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.

Cabeçalhos

X-Idempotency

string

obrigatório

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

Parâmetros de caminho

messageId

string<uuid>

obrigatório

The identifier of the inbound JD message.

Corpo

application/json

Where the money went, and why.

outcome

string

obrigatório

RETURNED, CREDITED, or ABSORBED. Accepted case-insensitively.

Exemplo:

"RETURNED"

note

string

obrigatório

The operator justification.

Required string length: 10 - 500

Exemplo:

"funds wired back to the paying bank under control number 20260901000042; treasury ticket 8812"

Resposta

Indicates that the closure was recorded.

messageId

string<uuid>

Exemplo:

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

outcome

string

Exemplo:

"RETURNED"

note

string

Exemplo:

"funds wired back to the paying bank under control number 20260901000042"

amount

string

What this decision was worth, read from the retention when the message carried one, and from the devolution row otherwise. Omitted when no positive amount was parsed.

Exemplo:

"15000.00"

closedAt

string<date-time>

Exemplo:

"2026-02-01T15:30:00Z"

closedBy

string

The stable subject from the bearer token, never a display name.

Exemplo:

"acme/ana.souza"

retentionClosed

boolean

Exemplo:

true

retentionReason

string

Exemplo:

"RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED"

retainedAt

string<date-time>

Exemplo:

"2026-02-01T15:29:55Z"

devolutionClosed

boolean

Exemplo:

true

devolutionPreviousStatus

string

RETAINED or FAILED: the devolution status before this call.

Exemplo:

"RETAINED"

devolutionStatus

string

Exemplo:

"RETURNED"

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

Close Unsettled TED IN Credit

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta