Cancelar una Transferencia

Utilice este endpoint para cancelar una transferencia que aún no ha sido enviada para procesamiento. Solo las transferencias en estado CREATED o PENDING pueden ser canceladas. Cancelar una transferencia libera los fondos retenidos en Midaz y establece el estado en CANCELLED. Llamar a cancelar en una transferencia ya cancelada devuelve éxito.

POST /v1/transfers/{transferId}/cancel

Cancelar una Transferencia

cURL

curl --request POST \
  --url https://plugin-br-bank-transfer.sandbox.lerian.net/v1/transfers/{transferId}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "User requested cancellation"
}
'

200

success

{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "status": "CANCELLED",
  "cancelledAt": "2026-02-01T15:35:00-03:00"
}

Autorizaciones

Authorization · string · header · requerido

Autenticación mediante token JWT Bearer. El tenantId se deriva del token bearer o del contexto autenticado de la solicitud y no se proporciona a través de X-Organization-Id.

Encabezados

X-Organization-Id · string<uuid>

Alcance de organización Midaz para la solicitud. En despliegues multi-tenant este header es obligatorio. Este no es el identificador del tenant; el tenantId se deriva del JWT bearer o del contexto autenticado. En despliegues single-tenant los valores de X-Organization-Id proporcionados por el llamador son rechazados y la organización es proporcionada por SINGLE_TENANT_ORGANIZATION_ID.

X-Idempotency · string · requerido

Clave de idempotencia requerida para reintentos seguros. Utilice un UUID v4 o un identificador de negocio único. Si se envía la misma clave nuevamente y la solicitud original ya fue procesada, se devuelve la respuesta almacenada en caché.

Consulte Reintentos e idempotencia para más detalles.

Maximum string length: 255

Parámetros de ruta

transferId · string<uuid> · requerido

El identificador único de la transferencia a cancelar.

Cuerpo

application/json

reason · string

El motivo de la cancelación.

Maximum string length: 500

Respuesta

200

application/json

Indica que la transferencia fue cancelada exitosamente y los fondos fueron liberados.

Las llamadas repetidas con la misma clave X-Idempotency reproducen la respuesta en caché.

Consulte Reintentos e idempotencia para más detalles.

transferId · string<uuid> · requerido

Ejemplo:

"019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"

status · enum<string> · requerido

Opciones disponibles: CANCELLED

Ejemplo:

"CANCELLED"

cancelledAt · string<date-time> · requerido

Ejemplo:

"2026-02-01T15:35:00-03:00"