Create bank transfer return operation

Gives back, by STR0010 (devolução de transferência indevida), a TED credit this institution received. Prerequisite: the path segment names the received credit, an INBOUND bank-transfer operation from STR0004R2..STR0008R2 in status DELIVERED — read it via getOperation (GET /v1/str/operations/); any other operation answers SPB-3006. The body carries only the reason (returnCode) and an optional description: the debited and credited ISPBs (this institution, then the credit’s sender), the amount (the credit’s full amount) and NumCtrlSTROr (the credit’s NumCtrlSTR) come from the received credit, and a credit that names another institution as credited is refused. A credit is returned once: a second return while one stands answers 409 (a rejected or failed one leaves the credit returnable). The accepted operation is RETURN_REQUESTED and its protocolMetadata.nuOp is the STR0010’s NUOp, the key its STR0010R1 answer and the settlement fact carry; an Efetivado STR0010R1 settles it as its own transfer and closes the operation RETURNED. Above the client’s alçada band the frame parks (status PENDING_APPROVAL) and leaves for the STR only when the quorum signs; a denial or expiry ends it without dispatch. Idempotent — the X-Idempotency key lives with the operation: the same key and parsed request (member order and whitespace do not count; any other difference, such as number spelling, null for an absent field, or an unknown member, is another request) answer the stored operation with X-Idempotency-Replayed: true, also after X-TTL has dropped the cached response, and the same key with another request answers 422.

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

Create bank transfer return operation

cURL

curl --request POST \
  --url https://api.example.com/v1/str/operations/bank-transfers/{operationId}/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "returnCode": "1",
  "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",
    "emissionApprovalId": "<string>",
    "nuOp": "12345678202605060000001"
  }
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Idempotency key. Required on every mutation.

X-TTL · string

Seconds the cached response is kept; it may only shorten IDEMPOTENCY_DEFAULT_TTL_SEC. The key itself lives with the operation.

Parâmetros de caminho

operationId · string · obrigatório

Operation UUID of the received TED credit being returned.

Corpo

application/json

returnCode · enum<string> · obrigatório

BACEN return reason (CodDevTransf) of the STR0010: one of the codes the BACEN dicionário de domínios keeps active, without a leading zero (type CodDevTransf, Catálogo v5.13 Vol IV). The retired 10-14, 78, 79 and 81 are refused.

Opções disponíveis: 1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 40, 51, 52, 53, 61, 63, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 80, 82, 83, 84, 85, 86

Exemplo:

"1"

description · string

Optional free-text description of the return (Hist).

Exemplo:

"Wrong account"

metadata · object

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

Show child attributes

Resposta

201

application/json

Created

acceptedAt · string<date-time> · obrigatório

UTC RFC 3339 timestamp at which the command was accepted.

Exemplo:

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

capabilityId · string · obrigatório

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

Exemplo:

"STR0004"

correlationId · string · obrigatório

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

Exemplo:

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

isReplay · boolean · obrigatório

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

Exemplo:

false

operationFamily · enum<string> · obrigatório

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

Opções disponíveis: bankTransfer

Exemplo:

"bankTransfer"

operationId · string<uuid> · obrigatório

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

Exemplo:

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

status · enum<string> · obrigatório

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

Opções disponíveis: ACCEPTED, SUBMITTED, SENT, CONFIRMED, REJECTED, FAILED, PENDING_CONFIGURATION, PENDING_RECONCILIATION, RETURN_REQUESTED, RETURNED, CANCEL_REQUESTED, CANCELLED, RECEIVED, DELIVERED

Exemplo:

"ACCEPTED"

protocolMetadata · object

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

Show child attributes