Cancel a Transfer

Use this endpoint to cancel a transfer that has not yet been submitted for processing. Only transfers in CREATED or PENDING status can be cancelled. Cancelling a transfer releases the held funds in Midaz and sets the status to CANCELLED. Calling cancel on an already-cancelled transfer returns success.

POST /v1/transfers/{transferId}/cancel

Cancel a Transfer

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>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "reason": "User requested cancellation"
}
'

200

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

Authorizations

Authorization · string · header · required

JWT Bearer token authentication. The token must include a tenantId claim that matches the X-Organization-Id header.

Headers

X-Organization-Id · string<uuid> · required

Organization ID used as the tenant identifier. All data is scoped to this organization. Must match the JWT tenantId claim when authentication is enabled.

X-Idempotency · string · required

Required idempotency key for safe retries. Use a UUID v4 or unique business identifier. If the same key is sent again and the original request was already processed, the cached response is returned.

See Retries and idempotency for details.

Maximum string length: 255

Path Parameters

transferId · string<uuid> · required

The unique identifier of the transfer to cancel.

Body

application/json

reason · string

The reason for the cancellation.

Maximum string length: 500

Response

200

application/json

Indicates that the transfer was successfully cancelled and funds were released.

Repeated calls with the same X-Idempotency key replay the cached response.

See Retries and idempotency for more details.

transferId · string<uuid> · required

Example:

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

status · enum<string> · required

Available options: CANCELLED

Example:

"CANCELLED"

cancelledAt · string<date-time> · required

Example:

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