> ## 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. # Cancelar uma Transferência > Use este endpoint para cancelar uma transferência que ainda não foi enviada para processamento. Apenas transferências com status CREATED ou PENDING podem ser canceladas. Cancelar uma transferência libera os fundos retidos no Midaz e define o status como CANCELLED. Chamar cancel em uma transferência já cancelada retorna sucesso. Este endpoint não recebe corpo de requisição — a transferência é identificada apenas pelo parâmetro de caminho. ## OpenAPI ````yaml pt/openapi/v3-current/ted.yaml post /v1/transfers/{transferId}/cancel openapi: 3.0.3 info: title: API do Plugin de Transferência Bancária (TED) description: >- API completa para transferências bancárias brasileiras (TED OUT, TED IN, P2P) através da plataforma Lerian, incluindo iniciação de transferências, processamento, acompanhamento de status e cancelamento. version: 1.1.9 servers: - url: https://ted.sandbox.lerian.net description: Sandbox (placeholder — ainda não disponível para acesso público) security: - BearerAuth: [] - OAuth2ClientCredentials: - api - OAuth2Password: - api tags: - name: Transfers API description: Endpoints para iniciar, processar, acompanhar e cancelar transferências. - name: Webhooks description: >- Endpoints para registrar e gerenciar assinaturas de webhook com escopo de tenant para eventos de transferência. - name: Webhook DLQ description: >- Endpoints para inspecionar e reprocessar mensagens da dead-letter queue de webhooks. paths: /v1/transfers/{transferId}/cancel: post: tags: - Transfers API summary: Cancelar uma Transferência description: >- Use este endpoint para cancelar uma transferência que ainda não foi enviada para processamento. Apenas transferências com status CREATED ou PENDING podem ser canceladas. Cancelar uma transferência libera os fundos retidos no Midaz e define o status como CANCELLED. Chamar cancel em uma transferência já cancelada retorna sucesso. Este endpoint não recebe corpo de requisição — a transferência é identificada apenas pelo parâmetro de caminho. operationId: cancelTransfer parameters: - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/XIdempotencyKey' - name: transferId in: path required: true description: O identificador único da transferência a ser cancelada. schema: type: string format: uuid responses: '200': description: >- Indica que a transferência foi cancelada com sucesso e os fundos foram liberados. Chamadas repetidas com a mesma chave `X-Idempotency` reproduzem a resposta em cache. Consulte [Tentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes. content: application/json: schema: $ref: '#/components/schemas/CancelTransferResponse' examples: success: summary: Cancelamento bem-sucedido value: transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d status: CANCELLED cancelledAt: '2026-02-01T15:35:00-03:00' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/TransferNotFound' '409': $ref: '#/components/responses/CannotCancel' '422': $ref: '#/components/responses/CannotCancel' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: XOrganizationId: name: X-Organization-Id in: header required: true description: >- Escopo da organização Midaz para a requisição, usado para chamadas downstream ao CRM, Fees e Midaz. Obrigatório nas rotas de transferência com escopo de organização em todos os modos de implantação; um valor ausente ou que não seja UUID retorna 400. Este não é o identificador do tenant — o tenantId é derivado do JWT bearer ou do contexto autenticado, nunca deste cabeçalho. Workers em segundo plano (poller de TED IN, conciliação) não possuem cabeçalho de requisição e, no modo single-tenant, recorrem à variável de ambiente `ORGANIZATION_ID` da implantação. schema: type: string format: uuid example: 019c96a0-0a98-7287-9a31-786e0809c769 XIdempotencyKey: name: X-Idempotency in: header required: true description: >- Chave de idempotência obrigatória para tentativas seguras. Use um UUID v4 ou identificador de negócio único. Se a mesma chave for enviada novamente e a solicitação original já tiver sido processada, a resposta em cache será retornada. Consulte [Tentativas e idempotência](/pt/reference/retries-idempotency) para detalhes. schema: type: string maxLength: 255 example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b schemas: CancelTransferResponse: type: object required: - transferId - status - cancelledAt properties: transferId: type: string format: uuid example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d status: type: string enum: - CANCELLED example: CANCELLED cancelledAt: type: string format: date-time example: '2026-02-01T15:35:00-03:00' ErrorResponse: type: object required: - error properties: error: type: object required: - code - service - category - message - requestId properties: code: type: string description: >- O código de erro estável. Erros do plugin usam o formato `BTF-XXXX`; rejeições de negócio/autenticação do JD SPB repassam o código bruto do fornecedor literalmente (por exemplo, `AAC90`, `ACE95`, `DVE01`), e falhas de transporte no nível do JD expõem os marcadores sintéticos `TRANSPORT` ou `JD_MISSING_CODE`. Faça a correspondência com base neste valor, e não no status HTTP. example: BTF-0010 service: type: string description: O serviço ou domínio que produziu o erro. example: plugin category: type: string description: >- Categoria de erro legível por máquina usada para decisões de reprocessamento. enum: - deterministic - transient - rate_limit - plugin example: deterministic message: type: string description: Um resumo do erro legível por humanos. example: >- Transferências só podem ser iniciadas de segunda a sexta entre 06:30 e 17:00 horário de Brasília requestId: type: string description: O ID de correlação da requisição. Presente mesmo quando vazio. example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: type: object additionalProperties: true description: >- Metadados estruturados de validação ou reprocessamento quando disponíveis. Detalhes de validação em nível de campo, cabeçalho, caminho e consulta são todos retornados aqui. example: currentTime: '2026-02-01T18:30:00-03:00' operatingHours: Mon-Fri 06:30-17:00 UTC-3 responses: BadRequest: description: >- Indica que a requisição contém entrada inválida. Verifique os detalhes do campo para erros de validação específicos. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidInput: summary: Validation error value: error: code: BTF-0001 service: plugin category: deterministic message: >- The request contains invalid fields. Check the field details below. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: recipientIspb: must be 8 digits amount: must be positive Unauthorized: description: Indica que a requisição não possui um token de autenticação válido. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Missing authorization value: error: code: BTF-0401 service: plugin category: deterministic message: Missing or invalid authentication token requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f Forbidden: description: >- Indica que o chamador está autenticado mas não tem permissão para esta operação, ou o tenant não está licenciado para este endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notLicensed: summary: Tenant not licensed value: error: code: BTF-0403 service: plugin category: deterministic message: Tenant is not licensed to use this endpoint requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f permissionDenied: summary: Caller lacks permission value: error: code: BTF-0405 service: plugin category: deterministic message: Caller lacks permission for this resource requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f TransferNotFound: description: >- Indica que a transferência não foi encontrada ou pertence a uma organização diferente. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: transferNotFound: summary: Transfer ID invalid value: error: code: BTF-0200 service: plugin category: deterministic message: Transfer not found requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f CannotCancel: description: >- Indica que a transferência não pode ser cancelada porque seu status atual não permite cancelamento. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: cannotCancel: summary: Already processing value: error: code: BTF-0204 service: plugin category: deterministic message: >- Transfer cannot be cancelled in its current status. Only CREATED or PENDING transfers can be cancelled. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: currentStatus: PROCESSING allowedStatuses: - CREATED - PENDING RateLimitExceeded: description: >- Indica que o limite de requisições foi excedido. Tente novamente após o número de segundos especificado no cabeçalho Retry-After. headers: Retry-After: description: Segundos até o limite de requisições ser redefinido schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimitExceeded: summary: Too many requests value: 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 description: > As respostas de rate-limit usam o código dedicado `BTF-0429` com a categoria `rate_limit`. Os clientes devem aplicar backoff usando o status HTTP `429` e o cabeçalho `Retry-After`. InternalServerError: description: Indica que ocorreu um erro interno inesperado. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Internal error value: error: code: BTF-9000 service: plugin category: plugin message: Unexpected error while processing the request requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f ServiceUnavailable: description: >- Indica que um serviço externo (CRM, JD SPB, Midaz ou Fees) está temporariamente indisponível. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: crmUnavailable: summary: CRM service down value: error: code: BTF-0502 service: crm category: transient message: >- Unable to validate account. The CRM service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f jdUnavailable: summary: JD SPB unavailable value: error: code: TRANSPORT service: jd_spb category: transient message: >- Unable to submit transfer. The JD SPB service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f midazUnavailable: summary: Midaz ledger unavailable value: error: code: BTF-2000 service: midaz category: transient message: >- Unable to process transfer. The Midaz ledger service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f feeServiceUnavailable: summary: Fee service unavailable (fail-closed mode) value: error: code: BTF-3000 service: fees category: transient message: >- Unable to calculate fee. The fee service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f dlqInspectorUnavailable: summary: DLQ inspector not configured value: error: code: BTF-9005 service: plugin category: deterministic message: DLQ inspector is not configured requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Autenticação por token JWT Bearer. O tenantId é derivado do token bearer ou do contexto de requisição autenticado e não é fornecido por meio do X-Organization-Id. OAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /v1/login/oauth/access_token scopes: api: Acesso à API de transferências TED OAuth2Password: type: oauth2 flows: password: tokenUrl: /v1/login/oauth/access_token scopes: api: Acesso à API de transferências TED ````