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

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

messageId

string<uuid>

required

The identifier of the inbound JD message.

Body

application/json

Where the money went, and why.

outcome

string

required

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

Example:

"RETURNED"

note

string

required

The operator justification.

Required string length: 10 - 500

Example:

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

Response

Indicates that the closure was recorded.

messageId

string<uuid>

Example:

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

outcome

string

Example:

"RETURNED"

note

string

Example:

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

Example:

"15000.00"

closedAt

string<date-time>

Example:

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

closedBy

string

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

Example:

"acme/ana.souza"

retentionClosed

boolean

Example:

true

retentionReason

string

Example:

"RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED"

retainedAt

string<date-time>

Example:

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

devolutionClosed

boolean

Example:

true

devolutionPreviousStatus

string

RETAINED or FAILED: the devolution status before this call.

Example:

"RETAINED"

devolutionStatus

string

Example:

"RETURNED"

Transfers API

Dashboard & Reconciliation API

TED In Operations API

Webhooks API

Webhook DLQ API

Error handling

Close Unsettled TED IN Credit

Authorizations

Headers

Path Parameters

Body

Response