Create bank transfer return operation
Prerequisite: the parent operation must be SETTLED before a return — read its state via getOperation (GET /v1/str/operations/); the path segment structurally ties the return to its parent. The handler resolves the original operation by operationId, validates that the lifecycle state admits a return (SPB-3006 otherwise), and delegates to the STR0010 return path. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.
Authorizations
JWT bearer token issued by the identity provider.
Headers
Bearer JWT token.
Idempotency key (canonical).
Idempotency key (legacy alias).
Idempotency key TTL in seconds.
Path Parameters
Original bank-transfer operation UUID.
Body
ISPB of the participant receiving the return, the 8-digit BACEN institution identifier.
38166
BACEN STR return reason code (devolução) for the reversal.
"01"
ISPB of the participant initiating the return, the 8-digit BACEN institution identifier.
"12345678"
Optional partial return amount as a decimal string in BRL, minor-unit precision; defaults to the full original amount when omitted.
^[0-9]+(\.[0-9]+)?$"50.00"
Optional free-text description of the return.
"Wrong account"
Opaque client-side metadata forwarded verbatim to the legacy submit DTO; not persisted on the return intent.
Response
Created
UTC RFC 3339 timestamp at which the command was accepted.
"2026-05-06T18:30:00Z"
STR capability identifier resolved for the accepted operation (e.g. STR0004).
"STR0004"
Request correlation identifier for tracing the accept across logs and traces.
"req-7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"
True when this response replays a prior idempotent accept rather than creating a new operation.
false
Operation family the accepted command belongs to (e.g. bankTransfer).
"bankTransfer"
Server-assigned operation aggregate UUID used for subsequent status, return, and cancellation calls.
"7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"
Current control-plane lifecycle status of the operation; ACCEPTED on initial accept.
"ACCEPTED"
Optional SAFE protocol correlation fields; present once the operation is mapped to STR wire identifiers.

