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.

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' \
  --data '
{
  "recipientIspb": "<string>",
  "returnCode": "<string>",
  "senderIspb": "<string>",
  "amount": "<string>",
  "description": "<string>",
  "metadata": {}
}
'

201

{
  "acceptedAt": "2023-11-07T05:31:56Z",
  "capabilityId": "<string>",
  "correlationId": "<string>",
  "isReplay": true,
  "operationFamily": "<string>",
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "protocolMetadata": {
    "controlNumber": "<string>",
    "nuOp": "<string>"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

Authorization · string

Bearer JWT token.

X-Idempotency · string

Idempotency key (canonical).

X-Idempotency-Key · string

Idempotency key (legacy alias).

X-TTL · string

Idempotency key TTL in seconds.

Path Parameters

operationId · string · required

Original bank-transfer operation UUID.

Body

application/json

recipientIspb · string · required

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

Example:

38166

returnCode · string · required

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

Example:

"01"

senderIspb · string · required

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

Example:

"12345678"

amount · string

Optional partial return amount as a decimal string in BRL, minor-unit precision; defaults to the full original amount when omitted.

Pattern: ^[0-9]+(\.[0-9]+)?$

Example:

"50.00"

description · string

Optional free-text description of the return.

Example:

"Wrong account"

metadata · object

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

Show child attributes

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 · string · required

Operation family the accepted command belongs to (e.g. 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 · string · required

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

Example:

"ACCEPTED"

protocolMetadata · object

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

Show child attributes