Create bank transfer return operation

Prerequisite: the parent operation must be SENT, CONFIRMED, or DELIVERED before a return (the settled-outbound states) — 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 legacy STR0010 pipeline. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.

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

Create bank transfer return operation

cURL

curl --request POST \
  --url https://spb.sandbox.lerian.net/v1/str/operations/bank-transfers/{operationId}/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "recipientIspb": "00038166",
  "returnCode": "01",
  "senderIspb": "12345678",
  "amount": "50.00",
  "description": "Wrong account",
  "metadata": {}
}
'

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"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Idempotency key. Required on every mutation.

X-TTL · string

Idempotency key TTL in seconds.

Parámetros de ruta

operationId · string · requerido

Original bank-transfer operation UUID.

Cuerpo

application/json

recipientIspb · string · requerido

ISPB of the participant receiving the return, the 8-character BACEN institution identifier.

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

Ejemplo:

"00038166"

returnCode · string · requerido

BACEN STR return reason code (devolução) for the reversal.

Ejemplo:

"01"

senderIspb · string · requerido

ISPB of the participant initiating the return, the 8-character BACEN institution identifier.

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

Ejemplo:

"12345678"

amount · string

Optional return amount as a decimal string in BRL; when supplied it must equal the full original transfer amount, which is also the default when omitted. Canonical form only: exactly two decimal places and no leading integer zeros — the single spelling the durable column stores; anything else is refused at the door with 422.

Pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$

Ejemplo:

"50.00"

description · string

Optional free-text description of the return.

Ejemplo:

"Wrong account"

metadata · object

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

Show child attributes

Respuesta

201

application/json

Created

acceptedAt · string<date-time> · requerido

UTC RFC 3339 timestamp at which the command was accepted.

Ejemplo:

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

capabilityId · string · requerido

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

Ejemplo:

"STR0004"

correlationId · string · requerido

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

Ejemplo:

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

isReplay · boolean · requerido

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

Ejemplo:

false

operationFamily · enum<string> · requerido

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

Opciones disponibles: bankTransfer

Ejemplo:

"bankTransfer"

operationId · string<uuid> · requerido

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

Ejemplo:

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

status · enum<string> · requerido

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

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

Ejemplo:

"ACCEPTED"

protocolMetadata · object

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

Show child attributes