Create IBS repasse operation

Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts a STR0053 IBS-repasse operation (reserve repasse of IBS settlement values to the comitê gestor) through the operation-centric API. The handler translates the JSON request into the STR0053 XML request path, persists the operation aggregate and SUBMITTED outbound relay work, and returns the canonical OperationAccepted envelope. Dispatch was accepted, not BACEN settlement confirmation. 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/ibs-repasses

Create IBS repasse operation

cURL

curl --request POST \
  --url https://api.example.com/v1/str/operations/ibs-repasses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "1500.25",
  "dtRepFinanc": "2026-06-09",
  "identdRepFinanc": "REP-2026-0001",
  "recipient": {
    "ispb": "12345678",
    "account": "123456",
    "accountType": "CC",
    "branch": "0001",
    "document": "12345678901",
    "name": "João da Silva",
    "party": "institution",
    "paymentAccount": "00000000123456"
  },
  "sender": {
    "ispb": "12345678",
    "account": "123456",
    "accountType": "CC",
    "branch": "0001",
    "document": "12345678901",
    "name": "João da Silva",
    "party": "institution",
    "paymentAccount": "00000000123456"
  },
  "clientReference": "ibs-ref-1",
  "cnpjOrigdrRepFinanc": "12345678000199",
  "description": "Repasse IBS comite gestor",
  "infSeggc": [
    {
      "dtHrInfSeggc": "2026-06-09T12:00:00",
      "identdInfSeggc": "SEGGC-INFO-0001"
    }
  ],
  "metadata": {},
  "qtdTransc": "10"
}
'

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

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

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

Cuerpo

application/json

amount · string · requerido

Repasse amount as a decimal string in BRL, minor-unit precision (two decimal places). 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:

"1500.25"

dtRepFinanc · string · requerido

Financial repasse date in BACEN STR0053 ISO date form (e.g. 2026-06-09). Required and non-blank.

Minimum string length: 1

Ejemplo:

"2026-06-09"

identdRepFinanc · string · requerido

Financial-repasse identifier the comitê gestor keys the repasse on (required, 1-50 characters). This service mints no value for it: an absent or blank identifier is refused with 422.

Required string length: 1 - 50

Ejemplo:

"REP-2026-0001"

recipient · object · requerido

Crediting participant account (comitê gestor) receiving the IBS repasse.

Show child attributes

sender · object · requerido

Debiting participant account originating the IBS repasse.

Show child attributes

clientReference · string

Optional caller-supplied correlation reference echoed back for client-side reconciliation.

Ejemplo:

"ibs-ref-1"

cnpjOrigdrRepFinanc · string

Optional repasse-originator CNPJ (official CNPJ type: exactly 14 characters, [0-9A-Z]{12}[0-9]{2}). Omitted from the wire when absent.

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

Ejemplo:

"12345678000199"

description · string

Optional free-text description carried with the operation.

Ejemplo:

"Repasse IBS comite gestor"

infSeggc · object[] | null

Repeating segregation-informe group ([0..n]); each entry requires both an identifier and a timestamp. Absent means the repasse references no informe. No item ceiling is imposed: the official XSD declares maxOccurs='unbounded' and no BACEN rule caps it.

Show child attributes

metadata · object

Opaque client-side metadata forwarded verbatim to the legacy submit DTO. NOT persisted on the operation intent or sanitized payload.

Show child attributes

qtdTransc · string

Optional transaction count (digits only).

Ejemplo:

"10"

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