Orchestrate Core operation

Resolves participant routing, consumes quota when indirect, records settlement tracking, attributes fees/commissions, persists saga state, and emits Core domain events.

POST /api/v1/core/operations/

Orchestrate Core operation

cURL

curl --request POST \
  --url https://api.example.com/api/v1/core/operations/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": 15000,
  "commissionAmount": 10,
  "endToEndId": "E12345678202604281234ABCDE123456",
  "feeAmount": 25,
  "operationId": "op-20260428-0001",
  "senderISPB": "12345678",
  "commissionRecipientISPB": "87654321",
  "feePayerISPB": "12345678"
}
'

200

{
  "commissionAmount": 10,
  "feeAmount": 25,
  "feeAttributionId": "550e8400-e29b-41d4-a716-446655440000",
  "operationId": "op-20260428-0001",
  "routingDecision": {
    "isDirect": false,
    "quotaConsumed": 15000,
    "indirectISPB": "12345678",
    "sponsorISPB": "87654321"
  },
  "sagaId": "550e8400-e29b-41d4-a716-446655440000",
  "sagaStatus": "COMPLETED",
  "settlementId": "550e8400-e29b-41d4-a716-446655440000",
  "settlementStatus": "PENDING",
  "commissionRecipientISPB": "87654321",
  "feePayerISPB": "12345678"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Idempotency key, max 255 characters

Cuerpo

application/json

amount · integer<int64> · requerido

Transaction amount in centavos (BRL minor units); must be greater than zero.

Rango requerido: x >= 1

Ejemplo:

15000

commissionAmount · integer<int64> · requerido

Commission amount in centavos (BRL minor units); zero or positive.

Rango requerido: x >= 0

Ejemplo:

10

endToEndId · string · requerido

PIX EndToEndID of the transaction, 32 characters, shaped as BACEN's EndToEndIdType (E, then the 8-character participant segment, then YYYYMMDDHHMM, then an 11-character unique tail). The date and minute components are additionally parsed as a real instant, and the participant segment must equal senderISPB, before the operation is accepted.

Pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$

Ejemplo:

"E12345678202604281234ABCDE123456"

feeAmount · integer<int64> · requerido

Fee amount in centavos (BRL minor units); zero or positive.

Rango requerido: x >= 0

Ejemplo:

25

operationId · string · requerido

Caller-assigned idempotency/business identifier for the operation. Lerian's own bound, not BACEN's: 128 characters is what the orchestration command enforces and what core_sagas.operation_id stores.

Required string length: 1 - 128

Ejemplo:

"op-20260428-0001"

senderISPB · string · requerido

ISPB of the sending participant, exactly 8 digits or uppercase letters (BACEN ISPBType [0-9A-Z]{8}).

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

Ejemplo:

"12345678"

commissionRecipientISPB · string

ISPB of the participant receiving the commission (8 digits or uppercase letters); optional.

Ejemplo:

"87654321"

feePayerISPB · string

ISPB of the participant charged the fee (8 digits or uppercase letters); optional.

Ejemplo:

"12345678"

Respuesta

200

application/json

OK

commissionAmount · integer<int64> · requerido

Commission amount applied, in centavos (BRL minor units).

Ejemplo:

10

feeAmount · integer<int64> · requerido

Fee amount applied, in centavos (BRL minor units).

Ejemplo:

25

feeAttributionId · string · requerido

UUID of the fee attribution record; empty when no fee attribution was created.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

operationId · string · requerido

Caller-assigned identifier echoed from the request.

Ejemplo:

"op-20260428-0001"

routingDecision · object · requerido

Routing snapshot showing how the operation was directed through sponsor/indirect participants.

Show child attributes

sagaId · string · requerido

UUID of the orchestration saga coordinating the operation.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

sagaStatus · string · requerido

Current state of the orchestration saga (e.g. COMPLETED).

Ejemplo:

"COMPLETED"

settlementId · string · requerido

UUID of the settlement created for this operation.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

settlementStatus · string · requerido

Current state of the settlement (e.g. PENDING).

Ejemplo:

"PENDING"

commissionRecipientISPB · string

ISPB of the participant receiving the commission (8 digits or uppercase letters); omitted when no fee attribution applies.

Ejemplo:

"87654321"

feePayerISPB · string

ISPB of the participant charged the fee (8 digits or uppercase letters); omitted when no fee attribution applies.

Ejemplo:

"12345678"