Create bank transfer cancellation operation

Prerequisite: the parent operation must exist and admit cancellation — read its state via getOperation (GET /v1/str/operations/); the path segment structurally ties the cancellation to its parent. A transfer is cancellable until it settles; once settled it takes a return instead (SPB-3006). Two endings: a transfer the STR already holds is cancelled by an STR0011 the STR adjudicates, and the cancellation operation comes back CANCEL_REQUESTED; a transfer that never reached the wire is abandoned locally, nothing is sent to BACEN, and the cancellation operation comes back already CANCELLED.

POST /v1/str/operations/bank-transfers/{operationId}/cancellations

Create bank transfer cancellation operation

cURL

curl --request POST \
  --url https://spb.sandbox.lerian.net/v1/str/operations/bank-transfers/{operationId}/cancellations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "senderIspb": "12345678",
  "metadata": {},
  "reason": "Client requested cancellation"
}
'

201

{
  "acceptedAt": "2026-05-06T18:30:00Z",
  "capabilityId": "STR0004",
  "correlationId": "req-7c8b3a2e-9f1d-4a55-9b8e-1e1234567890",
  "isReplay": false,
  "operationFamily": "bankTransfer",
  "operationId": "7c8b3a2e-9f1d-4a55-9b8e-1e1234567890",
  "status": "ACCEPTED",
  "protocolMetadata": {
    "controlNumber": "20260506000000000001",
    "nuOp": "12345678202605060000001"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key. Required on every mutation.

X-TTL · string

Idempotency key TTL in seconds.

Path Parameters

operationId · string · required

Original bank-transfer operation UUID.

Body

application/json

senderIspb · string · required

ISPB of the participant requesting the cancellation, the 8-character BACEN institution identifier.

Pattern: ^[0-9A-Z]{8}$

Example:

"12345678"

metadata · object

Opaque client-side metadata forwarded verbatim to the legacy submit DTO; not persisted on the cancellation intent.

Show child attributes

reason · string

Optional free-text reason for the cancellation.

Example:

"Client requested cancellation"

Response

201

application/json

Created

acceptedAt · string<date-time> · required

UTC RFC 3339 timestamp at which the command was accepted.

Example:

"2026-05-06T18:30:00Z"

capabilityId · string · required

STR capability identifier resolved for the accepted operation (e.g. STR0004).

Example:

"STR0004"

correlationId · string · required

Request correlation identifier for tracing the accept across logs and traces.

Example:

"req-7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"

isReplay · boolean · required

True when this response replays a prior idempotent accept rather than creating a new operation.

Example:

false

operationFamily · enum<string> · required

Operation family the accepted command belongs to (e.g. bankTransfer).

Available options: bankTransfer

Example:

"bankTransfer"

operationId · string<uuid> · required

Server-assigned operation aggregate UUID used for subsequent status, return, and cancellation calls.

Example:

"7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"

status · enum<string> · required

Current control-plane lifecycle status of the operation; ACCEPTED on initial accept.

Available options: ACCEPTED, SUBMITTED, SENT, CONFIRMED, REJECTED, FAILED, PENDING_CONFIGURATION, PENDING_RECONCILIATION, RETURN_REQUESTED, RETURNED, CANCEL_REQUESTED, CANCELLED, RECEIVED, DELIVERED

Example:

"ACCEPTED"

protocolMetadata · object

Optional SAFE protocol correlation fields; present once the operation is mapped to STR wire identifiers.

Show child attributes