Create bank transfer 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 bank transfer operation through the operation-centric API. The client declares the typed debtor and creditor roles (sender.party / recipient.party); the platform DERIVES the BACEN STR transfer code (STR0004 institution→institution, STR0005 non-account-holders, STR0006 client→IF, STR0007 IF→client, STR0008 client→client), persists the operation aggregate and SUBMITTED outbound relay work, and returns the canonical OperationAccepted envelope. This means 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/bank-transfers

Create bank transfer operation

cURL

curl --request POST \
  --url https://api.example.com/v1/str/operations/bank-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "150.00",
  "purposeCode": "00001",
  "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": "client-ref-1",
  "description": "Wire transfer for invoice 2026-Q2-A47",
  "metadata": {},
  "scheduledExecutionAt": "2026-06-23T10:00:00Z"
}
'

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

Transfer 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:

"150.00"

purposeCode · string · requerido

BACEN STR purpose code (finalidade), exactly 5 digits, and one the BACEN purpose dictionary names: 176 codes for the institution-level FinlddIF and 113 for the client-level FinlddCli. An unassigned five-digit number is refused.

Pattern: ^[0-9]{5}$

Ejemplo:

"00001"

recipient · object · requerido

Crediting (creditor) participant account receiving the transfer; its party role drives STR-code derivation.

Show child attributes

sender · object · requerido

Debiting (debtor) participant account originating the transfer; its party role drives STR-code derivation.

Show child attributes

clientReference · string

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

Ejemplo:

"client-ref-1"

description · string

Optional free-text description carried with the operation.

Ejemplo:

"Wire transfer for invoice 2026-Q2-A47"

metadata · object

Opaque client-side metadata forwarded verbatim to the legacy submit DTO. NOT persisted on the operation intent or sanitized payload; do not include sensitive fields (the legacy pipeline sees the raw value).

Show child attributes

scheduledExecutionAt · string<date-time>

Optional future settlement instant for a scheduled (agendada) STR transfer (RFC3339). BACEN window: at most 3 business days ahead, settlement hour must be one of 8/9/10/11/12 (Brasília), and at least 15 minutes ahead for same-day. Absent means immediate.

Ejemplo:

"2026-06-23T10:00:00Z"

split · object

Optional IBS/CBS tax-split group (all three children required when the group is present). Carried on the derived transfer codes STR0005/STR0007/STR0008.

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