> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Get a transfer > Returns the current state of an outgoing or internal transfer: `status`, amounts (`amount`, `feeAmount`, `totalAmount`), parties, SPB identifiers (`nuop`, `numCtrlStr`), and the time of each step (`reservedAt`, `submittedAt`, `settledAt`). This is the simplest way to track a TED you just sent: poll until `status` reaches a terminal state (`SETTLED`, `REJECTED`, or `CANCELLED`). In `REJECTED`, `rejection` tells who refused the transfer (`source`) and why (`code`, `reason`). After `SETTLED`, a return made by the recipient institution appears in `returned`, and the `status` does not change. You can see only the transfers of your institution. An identifier from another institution returns 404, as if it did not exist. For the full sequence of transitions, use `GET /v1/transfers/{transferId}/timeline`. ## OpenAPI ````yaml /en/openapi/v3-current/ted-lerian.yaml get /v1/transfers/{transferId} openapi: 3.1.0 info: description: >- API of **TED Lerian**, the interface over Lerian SPB. Your institution uses it to send TEDs, make internal transfers, track incoming TEDs, and operate returns, queues, and policy on its Midaz ledger. The [API overview](/en/reference/interfaces/ted-lerian/ted-lerian-api-overview) gives the concepts, the roles, and the conventions. title: TED Lerian API version: v1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- Outgoing TEDs and internal transfers: fee quote, creation, query, timeline, and cancellation. Every integration starts here. name: Transfers - description: >- Incoming TEDs from other institutions: query, timeline, and operator actions (full return and manual review resolution). name: Incoming Transfers - description: >- STR participant list, to resolve COMPE code ↔ ISPB and validate the destination bank before you create a transfer. name: Participants - description: >- Back office: operations queue, inconsistency findings between the ledger and the STR, reviews of rail facts, held returns, and manual unblock with evidence. name: Reconciliation - description: >- Operations dashboard: daily aggregates, regulatory deadlines (30/60/60 min), and the closing balance that the STR reported. name: Operations - description: >- Institution configuration (editor): operating window and cut-off, usage limits, holiday calendar, and ISPB → organization bindings. name: Policy paths: /v1/transfers/{transferId}: get: tags: - Transfers summary: Get a transfer description: >- Returns the current state of an outgoing or internal transfer: `status`, amounts (`amount`, `feeAmount`, `totalAmount`), parties, SPB identifiers (`nuop`, `numCtrlStr`), and the time of each step (`reservedAt`, `submittedAt`, `settledAt`). This is the simplest way to track a TED you just sent: poll until `status` reaches a terminal state (`SETTLED`, `REJECTED`, or `CANCELLED`). In `REJECTED`, `rejection` tells who refused the transfer (`source`) and why (`code`, `reason`). After `SETTLED`, a return made by the recipient institution appears in `returned`, and the `status` does not change. You can see only the transfers of your institution. An identifier from another institution returns 404, as if it did not exist. For the full sequence of transitions, use `GET /v1/transfers/{transferId}/timeline`. operationId: getTransfer parameters: - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier format: uuid type: string - $ref: '#/components/parameters/XRequestId' responses: '200': content: application/json: example: amount: '1500.00' clientReference: PED-2026-000123 createdAt: '2026-10-22T13:05:12Z' description: Supplier payment feeAmount: '3.25' metadata: channel: mobile orderId: PED-2026-000123 numCtrlStr: STR20261022000000123 nuop: '87654321202610220000123' purposeCode: '00010' railOperationId: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b recipient: agency: '1234' bankAccount: '0001234567' bankAccountType: CACC bankCode: '001' bankId: '87654321' document: '12345678901' name: Maria da Silva reservedAt: '2026-10-22T13:05:13Z' sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: '0001' bankAccount: '0001111222' bankAccountType: CACC bankId: '12345678' document: '98765432100' name: João Pereira settledAt: '2026-10-22T13:05:41Z' status: SETTLED submittedAt: '2026-10-22T13:05:14Z' totalAmount: '1503.25' transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: '2026-10-22T13:05:41Z' schema: $ref: '#/components/schemas/TransferResponse' description: Transfer found, in its current state. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: 'Not authenticated: token missing, invalid, or expired (`TED-0070`).' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- No permission: the token's role does not authorize this action, or the product license is not valid for the organization (`TED-0071`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): framework validation, with no TED code. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' components: parameters: XRequestId: description: >- Correlation identifier of this request (UUID). Optional: when you omit it, or when the value is not a well-formed UUID, the platform creates a UUID and returns it in the X-Request-Id header of the response. The resolved identifier goes to the logs, spans, and audit events of this request. Keep it to open a support ticket. in: header name: X-Request-Id schema: format: uuid type: string schemas: TransferResponse: additionalProperties: false description: >- Representation of an outgoing (TED) or internal transfer. The create, query, and list operations return it, and so do the cancel and unblock actions. Track the lifecycle through the `status` field and the instants `reservedAt`/`submittedAt`/`settledAt`. When `status=REJECTED`, `rejection` tells you who refused it and why. properties: amount: description: Amount in BRL as a decimal string with two decimal places. examples: - '1500.00' pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string clientReference: description: Requester reference sent with the transfer request. maxLength: 64 type: string createdAt: description: Time (UTC) of creation. format: date-time type: string description: description: Description given in the send request. maxLength: 140 type: string feeAmount: description: Fee charged at sending, in BRL (0.00 when exempt). examples: - '0.00' pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string metadata: additionalProperties: {} description: >- Free-form key-value pairs from the requester, kept verbatim. Never sent to external systems. maxProperties: 50 type: object numCtrlStr: description: >- Identifier of the entry assigned by the STR (20 characters, XXXAAAAMMDDnnnnnnnnn). pattern: ^[A-Za-z0-9]{20}$ type: string nuop: description: >- SPB identifier of the operation, 23 digits. It can be absent even in status=SUBMITTED. In that case, correlate by railOperationId. pattern: ^[0-9]{23}$ type: string purposeCode: description: Purpose code given in the send request (FinlddCli, 5 digits). examples: - '00001' pattern: ^[0-9]{5}$ type: string railOperationId: description: Identifier of the operation in the rail (after acceptance). format: uuid type: string recipient: $ref: '#/components/schemas/PartyResponse' description: >- Recipient sent when the transfer was created. In an internal transfer it includes accountId. rejection: $ref: '#/components/schemas/RejectionResponse' description: Present only when status=REJECTED. reservedAt: description: >- Instant (UTC) when the amount and fee were put on hold in the source account. Start of the 30-min regulatory deadline for submission. format: date-time type: string returned: $ref: '#/components/schemas/TransferReturnSummary' description: >- Return received for this outgoing TED (credit back to the sender). Requires status=SETTLED and a LATER return from the recipient institution. For this reason it never appears in the creation response or in the list items, only in GET /v1/transfers/{transferId}. sender: $ref: '#/components/schemas/PartyResponse' description: Source account, always in your own institution (includes accountId). settledAt: description: Instant of settlement. Exists only from status=SETTLED. format: date-time type: string status: description: >- Current state (published as a free string: handle unknown values with tolerance). Current values: CREATED, RESERVED, SUBMITTED, PENDING_STR, SETTLED, REJECTED, CANCELLED, AWAITING_RECONCILIATION, EXHAUSTED. TED: CREATED → RESERVED (amount + fee on hold) → SUBMITTED (sent to the STR) → SETTLED | REJECTED; PENDING_STR when the STR keeps the entry pending; AWAITING_RECONCILIATION and EXHAUSTED when the outcome could not be confirmed automatically; CANCELLED on a cancellation before submission or of a confirmed pending entry. INTERNAL: CREATED → SETTLED | REJECTED in the same call. Terminal: SETTLED, REJECTED, CANCELLED. type: string submittedAt: description: >- Timestamp (UTC) when the rail accepted the TED for sending to the STR. format: date-time type: string totalAmount: description: >- Amount + fee: the total debited (on hold) from the source account, in BRL. examples: - '1500.00' pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string transferId: description: Transfer identifier. Use it in queries and actions. format: uuid type: string type: description: >- TED (another institution, through the STR) or INTERNAL (same institution, settled in the ledger). enum: - TED - INTERNAL type: string updatedAt: description: >- Time (UTC) of the last write to the record. This is not always a status change. ⚠️ An INTERNAL transfer can stay in CREATED because the ledger response was undetermined. In that case, the reprocessor uses updatedAt as the queue position on each new attempt, and it moves a transfer whose resend window expired one hour ahead: updatedAt CAN BE IN THE FUTURE (up to 1 h after the current time). Do not use it as a transition time. format: date-time type: string required: - transferId - type - status - amount - feeAmount - totalAmount - purposeCode - sender - recipient - createdAt - updatedAt type: object Detail: additionalProperties: true description: >- Standard error body (RFC 9457, `application/problem+json`) for every `/v1` operation. Use `code` (TED-NNNN) to handle the error in code, `detail` for the readable message, and `errors` for the invalid fields of a 422. The `X-Request-Id` of the response identifies the occurrence for support. properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object PartyResponse: additionalProperties: false description: >- One of the parties to the transfer (sender or recipient). `accountId` exists only for the party that belongs to your institution. For the counterparty at another bank, the API returns the bank details that were sent. properties: accountId: description: >- Account in your own institution; present only for the party that belongs to it. format: uuid type: string agency: description: Branch. type: string bankAccount: description: Account number. type: string bankAccountType: description: >- Account type: CACC (checking), SVGS (savings), SLRY (salary), or TRAN (payment). enum: - CACC - SVGS - SLRY - TRAN type: string bankCode: description: COMPE code (3 digits), when known. pattern: ^[0-9]{3}$ type: string bankId: description: >- ISPB of the institution (8 digits). Always present. Empty string when unknown. pattern: ^[0-9]{8}$ type: string document: description: CPF (11 digits) or CNPJ (14 digits), digits only. examples: - '12345678901' pattern: ^([0-9]{11}|[0-9]{14})$ type: string name: description: Name of the party, not truncated. type: string required: - bankId type: object RejectionResponse: additionalProperties: false description: >- Reason for a transfer in `status=REJECTED`. Validation and policy refusals NEVER appear here: they occur before the service creates any resource, and they return as 4xx/503 without a transfer body. properties: code: description: >- Rejection code, by source: LEDGER → TED-0031 (insufficient balance) or TED-1001; RAIL → TED-1011, TED-1013 (the rail closed the TED without an STR decision), or the rail's own refusal code; STR → SitLancSTR code or SFN error (example: STR0015 at the day close); OPERATOR → the code given in the unblock. examples: - TED-1011 type: string reason: description: >- Rejection reason, as recorded on the transfer. Always present. Empty string when no text was recorded. type: string source: description: >- Source of the rejection, and when it can appear. LEDGER is decided SYNCHRONOUSLY: it can already be filled in the response of POST /v1/transfers. RAIL can also be there, or it can arrive later through reconciliation when the rail closed the TED without an STR decision (approval denied or expired; code TED-1013). STR and OPERATOR are always ASYNCHRONOUS: they never appear in the creation response. They are only visible in a later query. enum: - LEDGER - RAIL - STR - OPERATOR type: string required: - code - reason - source type: object TransferReturnSummary: additionalProperties: false description: >- Return received for a TED that this institution sent: the recipient institution returned the amount, and it was (or is being) credited back to the sender. Only appears in `GET /v1/transfers/{transferId}`, never in the creation response. properties: amount: description: >- Returned amount in BRL as a decimal string with two decimal places. The return is always in full, so it is always equal to the amount of the original transfer. examples: - '1500.00' pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string feeRefunded: description: If the fee charged at sending was also reversed. Absent means false. type: boolean numCtrlStr: description: >- Identifier of the return entry assigned by the STR (20 characters). It can be absent. pattern: ^[A-Za-z0-9]{20}$ type: string receivedAt: description: Instant when the return was recorded. format: date-time type: string refundedAt: description: >- Instant of the credit back to the sender. Exists only from status=REFUNDED. format: date-time type: string returnCode: description: Official return reason (CodDevTransf, SFN Domain Dictionary). examples: - '12' pattern: ^[0-9]{1,2}$ type: string status: description: >- State of the return: RECEIVED (recorded), REFUNDED (re-credit settled in the ledger), or MANUAL_REVIEW (stopped for analysis). enum: - RECEIVED - REFUNDED - MANUAL_REVIEW type: string required: - returnCode - amount - status - receivedAt type: object ErrorDetail: additionalProperties: false description: >- An invalid field inside a validation error: where it is (`location`), what is wrong (`message`), and the value received. properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false description: >- Error reported by an upstream system (ledger or rail), when the service chooses to expose it. Absent in most errors. properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object headers: XRequestId: description: >- Echo of the request X-Request-Id: the value that the client sent, or the UUID that the platform generated when the client sent none. Present in every response, success or error. schema: format: uuid type: string securitySchemes: BearerAuth: bearerFormat: JWT description: >- JWT token that the Lerian Access Manager issues for your institution. Send it in `Authorization: Bearer ` on every call (except the public health probes). The tenant never comes from the body, the query, or the path. Each operation requires a role with the matching permission (see the API overview). Without it, 403 `TED-0071`. Missing, invalid, or expired token: 401 `TED-0070`. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.