> ## 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. # Cancel a transfer (before sending) or a pending entry in the STR > Cancels a transfer that is not yet sent to the STR, or asks the STR to cancel a pending entry. | Current state | Result | |---|---| | `CREATED`, `RESERVED` | Cancels immediately and releases the hold: 200, `status=CANCELLED` | | `PENDING_STR` | Asks the STR to cancel: 202. The state changes only when the STR confirms (503 `TED-1012` if the rail does not expose this capability) | | `CANCELLED` | 200, with no new effect | | `SUBMITTED`, `SETTLED`, `REJECTED` | Not cancelable: 409 `TED-0061`. A settled TED comes back only through a return from the recipient institution | | `AWAITING_RECONCILIATION`, `EXHAUSTED` | Not cancelable: 409 `TED-0061`. Operations use `POST .../unblock` with evidence | The body is optional (`reason`). `X-Idempotency` is required; `X-Idempotency-Replayed: true` indicates a replay. ## OpenAPI ````yaml /es/openapi/v3-current/ted-lerian.yaml post /v1/transfers/{transferId}/cancel 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/{transferId}/cancel: post: tags: - Transfers summary: Cancel a transfer (before sending) or a pending entry in the STR description: >- Cancels a transfer that is not yet sent to the STR, or asks the STR to cancel a pending entry. | Current state | Result | |---|---| | `CREATED`, `RESERVED` | Cancels immediately and releases the hold: 200, `status=CANCELLED` | | `PENDING_STR` | Asks the STR to cancel: 202. The state changes only when the STR confirms (503 `TED-1012` if the rail does not expose this capability) | | `CANCELLED` | 200, with no new effect | | `SUBMITTED`, `SETTLED`, `REJECTED` | Not cancelable: 409 `TED-0061`. A settled TED comes back only through a return from the recipient institution | | `AWAITING_RECONCILIATION`, `EXHAUSTED` | Not cancelable: 409 `TED-0061`. Operations use `POST .../unblock` with evidence | The body is optional (`reason`). `X-Idempotency` is required; `X-Idempotency-Replayed: true` indicates a replay. operationId: cancelTransfer parameters: - description: >- Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid. Values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. The window sets how long the response is replayed. in: header name: X-TTL schema: minimum: 1 type: integer - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier 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: default: summary: Cancellation with a reason value: reason: Requested by the customer before sending schema: $ref: '#/components/schemas/CancelTransferRequest' 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 purposeCode: '00010' 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: CANCELLED totalAmount: '1503.25' transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: '2026-10-22T13:06:02Z' schema: $ref: '#/components/schemas/TransferResponse' description: >- Transfer cancelled and hold released (`status=CANCELLED`). If `X-Idempotency-Replayed: true`, or if it was already cancelled, no new effect occurred. 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' '202': content: application/json: schema: $ref: '#/components/schemas/TransferResponse' description: >- Cancellation of the pending entry requested from the STR. The transfer stays `PENDING_STR` until the STR responds. Track it by query or event. 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`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). 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' '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Cannot be cancelled in the current status (`TED-0061`): already sent, settled, rejected, or awaiting reconciliation/exhausted (use unblock with evidence); 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: >- A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. 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: >- The STR connector does not expose the cancellation of a pending entry (`TED-1012`), or its answer is unknown (`TED-1010`): the cancellation request stays recorded, so retry with the same `X-Idempotency` and `reason`. Or the institution configuration is missing (`TED-0080`). 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: CancelTransferRequest: additionalProperties: false description: >- Optional body of the cancellation. The reason is recorded. When the cancellation is sent to the STR, the reason goes with the history of the entry. properties: reason: description: >- Reason (goes to the cancellation description in the STR, when applicable) maxLength: 140 type: string 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: -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.