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

# Send a TED (or internal transfer)

> Sends a TED to another institution or, if the recipient is in your own institution, an internal transfer. The recipient's bank (`recipient.bankId` or `recipient.bankCode`) decides the path.

Send `X-Account-Id` with the debited account and `X-Idempotency` with a new key for each payment. The service validates the request and applies the institution policy (window, limits, fee). Then it holds the amount plus the fee and sends the TED to the STR. Settlement is asynchronous: track it with `GET /v1/transfers/{transferId}` or with the `transfer.*` events.

| `status` in the 201 response | Meaning |
|---|---|
| `SUBMITTED` | The rail accepted the TED and sent it to the STR. Wait for `SETTLED` or `REJECTED` |
| `SETTLED` | Internal transfer (`type=INTERNAL`) already settled in the ledger, with `recipient.accountId` filled in |
| `REJECTED` | Synchronous refusal from the ledger or the rail; the hold was released. Example: insufficient balance, `rejection.code=TED-0031` |
| `AWAITING_RECONCILIATION` / `CREATED` | Undetermined outcome (no conclusive response from the rail or the ledger); automatic reconciliation resolves it. Do not resend with another key |

Validation and policy refusals return 4xx/503 **without creating a resource**: fix the request and resend it with a new key. The exception is a retry whose first attempt got no answer: a refusal does not show that the first attempt created nothing. Look up the transfer before you send it with a new key: `GET /v1/transfers` filtered by `client_reference` (the `clientReference` you sent), or by `account_id` and a `start_date`/`end_date` range (UTC) that covers the first attempt. The key stays bound to the transfer it created, so a later request with the same key never creates a second transfer. If the internal recipient is not in the organization's registry, the response is 422 `TED-1021`. A materially identical request sent shortly after another one can return 409 `TED-0014`, even with another key.



## OpenAPI

````yaml /es/openapi/v3-current/ted-lerian.yaml post /v1/transfers
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](/es/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:
    post:
      tags:
        - Transfers
      summary: Send a TED (or internal transfer)
      description: >-
        Sends a TED to another institution or, if the recipient is in your own
        institution, an internal transfer. The recipient's bank
        (`recipient.bankId` or `recipient.bankCode`) decides the path.


        Send `X-Account-Id` with the debited account and `X-Idempotency` with a
        new key for each payment. The service validates the request and applies
        the institution policy (window, limits, fee). Then it holds the amount
        plus the fee and sends the TED to the STR. Settlement is asynchronous:
        track it with `GET /v1/transfers/{transferId}` or with the `transfer.*`
        events.


        | `status` in the 201 response | Meaning |

        |---|---|

        | `SUBMITTED` | The rail accepted the TED and sent it to the STR. Wait
        for `SETTLED` or `REJECTED` |

        | `SETTLED` | Internal transfer (`type=INTERNAL`) already settled in the
        ledger, with `recipient.accountId` filled in |

        | `REJECTED` | Synchronous refusal from the ledger or the rail; the hold
        was released. Example: insufficient balance, `rejection.code=TED-0031` |

        | `AWAITING_RECONCILIATION` / `CREATED` | Undetermined outcome (no
        conclusive response from the rail or the ledger); automatic
        reconciliation resolves it. Do not resend with another key |


        Validation and policy refusals return 4xx/503 **without creating a
        resource**: fix the request and resend it with a new key. The exception
        is a retry whose first attempt got no answer: a refusal does not show
        that the first attempt created nothing. Look up the transfer before you
        send it with a new key: `GET /v1/transfers` filtered by
        `client_reference` (the `clientReference` you sent), or by `account_id`
        and a `start_date`/`end_date` range (UTC) that covers the first attempt.
        The key stays bound to the transfer it created, so a later request with
        the same key never creates a second transfer. If the internal recipient
        is not in the organization's registry, the response is 422 `TED-1021`. A
        materially identical request sent shortly after another one can return
        409 `TED-0014`, even with another key.
      operationId: createTransfer
      parameters:
        - description: >-
            Identifier (UUID) of the customer account in your own institution
            that starts the operation: the debited account in a send request or
            a quote. It goes in the header, never in the body. The account must
            belong to the organization that the token resolves. A missing or
            malformed value returns 400 `TED-0008`; an account from another
            organization returns 403 `TED-0009`.
          in: header
          name: X-Account-Id
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            Idempotency key that the integrator creates (1 to 128 printable
            ASCII characters, no spaces; we recommend a UUID). Required on every
            operation with an effect. Send the SAME key again when you retry a
            call that failed because of a timeout or network error. Same key +
            same body returns the original response with
            `X-Idempotency-Replayed: true` and no new effect. Same key +
            different body responds 422 `TED-0012`. Same key still in processing
            responds 409 `TED-0013` (retry after `Retry-After`). Missing or in
            the wrong format: 400 `TED-0011`.
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XRequestId'
      requestBody:
        content:
          application/json:
            examples:
              internal:
                summary: Internal transfer (recipient in the institution's own ISPB)
                value:
                  amount: '250.00'
                  description: Transfer between accounts
                  purposeCode: '00010'
                  recipient:
                    agency: '0001'
                    bankAccount: '0007654321'
                    bankAccountType: CACC
                    bankId: '12345678'
                    document: '12345678901'
                    name: Maria da Silva
              ted:
                summary: TED to another institution (bank by COMPE)
                value:
                  amount: '1500.00'
                  clientReference: PED-2026-000123
                  description: Supplier payment
                  metadata:
                    channel: mobile
                    orderId: PED-2026-000123
                  purposeCode: '00010'
                  recipient:
                    agency: '1234'
                    bankAccount: '0001234567'
                    bankAccountType: CACC
                    bankCode: '001'
                    document: '12345678901'
                    name: Maria da Silva
            schema:
              $ref: '#/components/schemas/CreateTransferRequestBody'
        required: true
      responses:
        '201':
          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
                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
                status: SUBMITTED
                submittedAt: '2026-10-22T13:05:14Z'
                totalAmount: '1503.25'
                transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b
                type: TED
                updatedAt: '2026-10-22T13:05:14Z'
              schema:
                $ref: '#/components/schemas/TransferResponse'
          description: >-
            Transfer recorded. Read `status`: `SUBMITTED` (TED accepted by the
            rail; settlement through the STR is asynchronous), `SETTLED`
            (internal transfer settled), `REJECTED` (synchronous refusal from
            the ledger or the rail; see `rejection`), `AWAITING_RECONCILIATION`
            (TED) or `CREATED` (internal transfer): undetermined outcome;
            automatic reconciliation resolves it. If `X-Idempotency-Replayed:
            true`, this is the replay of an earlier transfer creation.
          headers:
            X-Idempotency-Replayed:
              description: >-
                `true` when this response is the replay of a previous request
                with the same `X-Idempotency` (no new effect occurred). Absent
                when the request produced a new effect. Always check this
                header: the HTTP status and the body are identical in both
                cases.
              schema:
                type: boolean
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Malformed JSON (`TED-0001`), `X-Account-Id` missing/malformed
            (`TED-0008`), or `X-Idempotency` missing/in the wrong format
            (`TED-0011`). Nothing was created.
          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`);
            or the account in `X-Account-Id` does not belong to the organization
            (`TED-0009`).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Holder of the source account not found in the registry (`TED-0010`).
            Nothing was created.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Materially identical request within the duplicate protection window
            (`TED-0014`; query the existing transfer), or a request with the
            same `X-Idempotency` is still processing (`TED-0013`; retry after
            `Retry-After`).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Refused before any effect, so this request created nothing. Invalid
            fields, purpose code, bank, or document (`TED-0002` to `TED-0007`);
            internal recipient not found (`TED-1021`); outside the window or
            non-business day (`TED-0020`/`TED-0021`); limit exceeded
            (`TED-0030`); idempotency key already used (`TED-0012`). With
            `TED-0012`, a transfer can already exist for this key, so look it up
            with `GET /v1/transfers` before you use a new key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Unexpected failure (`TED-9000`). The transfer can already exist:
            look for it with `GET /v1/transfers` (for example, by
            `client_reference`) before you send it again. 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: >-
            Window cannot be determined (`TED-0022`), fee calculation
            (`TED-0040`) or registry (`TED-1020`) unavailable, or institution
            without configuration (`TED-0080`). For `TED-0080`, the transfer can
            already exist: look for it with `GET /v1/transfers` before you send
            it again.
          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:
    CreateTransferRequestBody:
      additionalProperties: false
      description: >-
        Request to send a TED or an internal transfer. The debited account does
        NOT go in the body: the `X-Account-Id` header identifies it. The
        recipient's bank decides the path (TED or INTERNAL): another institution
        → TED through the STR; your own institution → internal transfer settled
        in the ledger.
      properties:
        amount:
          description: >-
            Amount in BRL as a decimal string, not a JSON number: digits only,
            with a dot as the decimal separator, up to 16 significant integer
            digits and at most 2 significant decimal places, with no sign or
            exponent. Leading and trailing spaces are ignored (e.g., "1500.00";
            "1500.000" is equal to 1500.00).
          examples:
            - '1500.00'
          type: string
        clientReference:
          description: >-
            Requester reference (up to 64 characters). Queries and events return
            it, and you can use it as a filter in GET
            /v1/transfers?client_reference=.
          examples:
            - PED-2026-000123
          maxLength: 64
          type: string
        description:
          description: >-
            Transfer description (up to 140 characters). Required when
            purposeCode=99999 (other).
          examples:
            - Supplier payment
          maxLength: 140
          type: string
        metadata:
          additionalProperties: {}
          description: >-
            Free key-value pairs from the requester, returned verbatim in
            queries and events. Never sent to the STR or to other external
            systems.
          type: object
        purposeCode:
          description: Purpose code of the TED (FinlddCli Domain Dictionary, 5 digits).
          examples:
            - '00001'
          pattern: ^[0-9]{5}$
          type: string
        recipient:
          $ref: '#/components/schemas/RecipientBody'
          description: >-
            Recipient: bank (ISPB or COMPE), branch, account, account type,
            name, and document.
      required:
        - amount
        - purposeCode
        - recipient
      type: object
    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: <SERVICE>-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
    RecipientBody:
      additionalProperties: false
      description: >-
        Recipient of the transfer. Identify the bank by `bankId` (ISPB, 8
        digits) OR by `bankCode` (COMPE, 3 digits), never both. Use `GET
        /v1/participants` to resolve one from the other. The other fields
        identify the account and the holder exactly as they appear at the
        destination bank.
      properties:
        agency:
          description: >-
            Branch of the destination account, without the check digit (up to 4
            characters).
          examples:
            - '1234'
          maxLength: 4
          type: string
        bankAccount:
          description: >-
            Destination account number, in the format that the destination bank
            accepts (up to 20 characters).
          examples:
            - '0001234567'
          maxLength: 20
          type: string
        bankAccountType:
          description: >-
            Type of the destination account: CACC (checking), SVGS (savings),
            SLRY (salary), or TRAN (payment).
          enum:
            - CACC
            - SVGS
            - SLRY
            - TRAN
          type: string
        bankCode:
          description: >-
            COMPE code of the destination institution (3 digits). Send bankId OR
            bankCode, never both.
          pattern: ^[0-9]{3}$
          type: string
        bankId:
          description: >-
            ISPB of the destination institution (8 digits). Send bankId OR
            bankCode, never both.
          pattern: ^[0-9]{8}$
          type: string
        document:
          description: CPF (11 digits) or CNPJ (14 digits), digits only.
          pattern: ^([0-9]{11}|[0-9]{14})$
          type: string
        name:
          description: >-
            Full name or legal name of the holder of the destination account (up
            to 200 characters).
          examples:
            - Maria da Silva
          maxLength: 200
          type: string
      required:
        - agency
        - bankAccount
        - bankAccountType
        - name
        - document
      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 <token>` 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.