components: schemas: AccountReportRequestResponse: additionalProperties: false properties: correlationId: description: camt.060 AppHdr BizMsgIdr the inbound camt.052/053/054 report must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted to BACEN SPI examples: - camt.060.spi.1.9 type: string operationId: description: UUID of the recorded ACCOUNT_INFORMATION_REQUEST operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string queryType: description: Echo of the requested report selector (BALANCE, STATEMENT, or ENTRIES) examples: - BALANCE type: string requestedMessageName: description: "ISO 20022 report the camt.060 requests: camt.053 (BALANCE/saldo), camt.052 (STATEMENT/entry-list file), or camt.054 (ENTRIES/entry detail)" examples: - camt.053 type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - queryType - requestedMessageName - state type: object ApprovalResponse: additionalProperties: false properties: approvalId: description: Server-assigned approval decision identifier. type: string decidedAt: description: Time the decision was made; RFC3339, UTC. Absent until decided. examples: - "2026-06-14T12:00:00Z" type: string decidedBy: description: Subject of the operator who decided the approval. Returned by the approval read; absent until decided. type: string decisionReason: description: The decider's justification, verbatim. Returned by the approval read; absent until decided. type: string expiresAt: description: Time the approval request expires; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string requestReason: description: "The requester's justification, verbatim: the evidence the deciding operator weighs. Returned by the approval read." type: string requestedAction: description: The action the approval governs. type: string requestedAt: description: Time the approval was requested; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string requestedBy: description: Subject of the operator who requested the approval. Returned by the approval read. type: string state: description: "Approval lifecycle state: REQUESTED, APPROVED, DENIED, EXPIRED, or CANCELLED." examples: - APPROVED type: string subjectId: description: Identifier of the subject the approval applies to. type: string subjectType: description: "Approval subject type: SUPPORT_LEVEL_CHANGE, CATALOGUE_ACTIVATION, RECOVERY_ACTION, MANUAL_RESOLUTION, or RAW_PAYLOAD_ACCESS." type: string required: - approvalId - subjectType - subjectId - requestedAction - state type: object CancellationEmissionResponse: additionalProperties: false properties: correlationId: description: Emission AppHdr BizMsgIdr the inbound response must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted (camt.055 or camt.029) examples: - camt.055.spi.1.1 type: string operationId: description: UUID of the recorded cancellation operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string scheduleId: description: Schedule identifier the cancellation acted on examples: - SCHEDULE2026Ref001 type: string scheduleState: description: Schedule lifecycle state after emission, when known examples: - CANCELLATION_PENDING type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - scheduleId - state type: object CapabilityDetailResponse: additionalProperties: false properties: capability: $ref: "#/components/schemas/CapabilityResponse" description: The requested capability detail. correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. examples: - req-7a3f9c2e type: string required: - capability - correlationId type: object CapabilityListResponse: additionalProperties: false properties: correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. examples: - req-7a3f9c2e type: string items: description: Capabilities on this page. items: $ref: "#/components/schemas/CapabilityResponse" type: array limit: description: Page size applied to this response (max items returned). examples: - 50 format: int64 type: integer nextCursor: description: Opaque cursor for the next page; absent when there are no further pages. type: string required: - items - limit - correlationId type: object CapabilityResponse: additionalProperties: false properties: capabilityId: description: "Public capability identifier: the rail's message code (STR0004 on SPB, the ISO 20022 message type pacs.008 on SPI)." type: string direction: description: "Message flow direction: INBOUND (received), OUTBOUND (submitted), or BIDIRECTIONAL." enum: - INBOUND - OUTBOUND - BIDIRECTIONAL examples: - OUTBOUND type: string disposition: description: "Coverage disposition for this capability: full — a client transacts or queries this code end to end; notice — a routed inbound notice handled with domain semantics and an emitted event, rather than bare routing; deferred — the capability is not built on this rail; not-addressed — the message exists in the protocol but is addressed to NEITHER leg of this participant, so this deployment can never send or receive it. isAvailable is the coarser boolean and answers a different question: whether the capability can be exercised right now. This answers what coverage is claimed for it." enum: - full - notice - deferred - not-addressed examples: - full type: string handlingMode: description: "How the capability may be exercised: PUBLICLY_SUBMITTABLE (caller-initiated), RECEIVE_ONLY (inbound only), LIFECYCLE_RESPONSE (protocol-driven reply), DIAGNOSTIC_ONLY, NOT_APPLICABLE, or NOT_READY." enum: - PUBLICLY_SUBMITTABLE - RECEIVE_ONLY - LIFECYCLE_RESPONSE - DIAGNOSTIC_ONLY - NOT_APPLICABLE - NOT_READY examples: - PUBLICLY_SUBMITTABLE type: string isAvailable: description: Whether the capability is currently available for use. examples: - true type: boolean name: description: Human-readable capability name. type: string operationFamily: description: Operation family the capability belongs to (bankTransfer on SPB, the ISO 20022 family PACS on SPI). type: string protocolMetadata: additionalProperties: {} description: Optional capability-specific protocol metadata (safe codes and feature flags only). type: object supportsAudit: description: Whether the capability records audit evidence. examples: - true type: boolean supportsEvents: description: Whether the capability emits lifecycle events on the event-delivery surface. examples: - true type: boolean supportsInbound: description: Whether the capability processes inbound messages from BACEN. examples: - false type: boolean supportsSubmission: description: Whether the capability accepts caller-initiated submissions. examples: - true type: boolean required: - capabilityId - name - operationFamily - direction - handlingMode - isAvailable - disposition - supportsSubmission - supportsInbound - supportsEvents - supportsAudit type: object ConnectivityTestResponse: additionalProperties: false properties: correlationId: description: pibr.001 AppHdr BizMsgIdr the inbound pibr.002 response must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted to BACEN SPI examples: - pibr.001.spi.1.3 type: string operationId: description: UUID of the recorded CONNECTIVITY_TEST operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - state type: object CorrelationResponse: additionalProperties: false properties: messageType: description: Catalogue message type. examples: - pacs.008 type: string operationRef: description: Operation identity the row is keyed on. type: string protocolRef: description: Rail protocol control number / reference. type: string required: - operationRef type: object CreateAccountReportRequest: additionalProperties: false properties: balanceType: description: "BALANCE only: CSA (the Conta PI balances, the default) or CRE (the Conta PI remuneration statement of periodFromDate). Sent as camt.060 ReqdBalTp/CdOrPrtry/Prtry." enum: - CSA - CRE examples: - CSA type: string entryId: description: "ENTRIES only, and required there: the entry to detail — a Pix EndToEndId, a return RtrId (32 characters) or an STR control number (20 characters). Sent as camt.060 RptgReq/Id." examples: - E1234567820260601120000abcdefghi pattern: ^([ED][0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][0-2][0-9][0-5][0-9][a-zA-Z0-9]{11}|[A-Z]{3}[0-9]{4}[0-1][0-9][0-3][0-9][a-zA-Z0-9]{9})$ type: string periodFromDate: description: Inclusive start of the reporting period, YYYY-MM-DD. Omitted for the current balance; the previous day of a closing balance or the credit day of a CRE; required for REL, TRD and TRT (the first day of the month for TRD and TRT). examples: - "2026-06-01" type: string periodFromTime: description: "REL only, with periodToTime: UTC time of periodFromDate the entries window opens at, hh:mm:ss.sssZ. Without it the window opens at the start of periodFromDate." examples: - 02:00:00.105Z pattern: ^[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$ type: string periodToDate: description: Inclusive end of the reporting period, YYYY-MM-DD. Required for REL (even when equal to periodFromDate, at most 24 hours after its start) and refused for every other report. examples: - "2026-06-01" type: string periodToTime: description: "REL only, with periodFromTime: UTC time of periodToDate the entries window closes at, hh:mm:ss.sssZ. Without it the window closes at the end of periodToDate." examples: - 17:00:00.250Z pattern: ^[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$ type: string queryType: description: "Conta PI report selector: BALANCE (camt.053 — the SALDO/balance), STATEMENT (camt.052 — the entry-list file pointer), or ENTRIES (camt.054 — entry detail). Upper case; this is Lerian's own selector, not a BACEN code." enum: - BALANCE - STATEMENT - ENTRIES examples: - BALANCE type: string statementType: description: "STATEMENT only: REL (the file of Conta PI entries, the default), TRD (the RCO statement file) or TRT (the RCO total file). Sent as camt.060 ReqdBalTp/CdOrPrtry/Prtry." enum: - REL - TRD - TRT examples: - REL type: string required: - queryType type: object CreateApprovalRequest: additionalProperties: false properties: expiresInSeconds: description: Optional expiry override in seconds; values <= 0 use the 24h default, values above the 7-day cap are clamped. format: int64 type: integer requestReason: description: "Free-form justification for requesting the approval; persisted for audit (1..2000 characters). Lerian's own bound. A blank justification is refused: an audit row nobody can read is not an audit row." maxLength: 2000 minLength: 1 type: string requestedAction: description: "The action being requested for approval (1..255 characters). Lerian's own bound: the four-eyes ledger is Lerian SPI control plane and never reaches an SFN wire." maxLength: 255 minLength: 1 type: string subjectId: description: UUID of the subject the approval applies to (e.g. the recovery action or operation id). format: uuid type: string subjectType: description: "Approval subject type: SUPPORT_LEVEL_CHANGE, CATALOGUE_ACTIVATION, RECOVERY_ACTION, MANUAL_RESOLUTION, or RAW_PAYLOAD_ACCESS." enum: - SUPPORT_LEVEL_CHANGE - CATALOGUE_ACTIVATION - RECOVERY_ACTION - MANUAL_RESOLUTION - RAW_PAYLOAD_ACCESS type: string required: - subjectType - subjectId - requestedAction - requestReason type: object CreateConnectivityTestRequest: additionalProperties: false properties: echoData: description: Optional free text; only its SHA-256 is recorded with the dispatch evidence, and it is not sent to the SPI, whose pibr.001 echo payload is the correlationId examples: - CONNECTIVITY TEST type: string type: object CreateEvidenceExportRequest: additionalProperties: false properties: includeRawPayload: description: When true, request inclusion of the raw payload in the export; subject to the raw-payload access policy. examples: - false type: boolean operationId: description: Operation whose evidence is being exported. examples: - op-1 minLength: 1 type: string payloadFingerprint: description: Optional canonical payload hash (hex) to bind the export to a specific payload version. examples: - 0123abcd... type: string reason: description: "Free-form reason for the export; persisted for audit. A blank reason is refused: an audit row nobody can read is not an audit row." examples: - audit review pull minLength: 1 type: string required: - operationId - reason type: object CreateMandateCancellation: additionalProperties: false properties: mandate: $ref: "#/components/schemas/MandateDetailsRequest" description: Mandate body identifying the mandate being cancelled originatorTaxId: description: "Tax identifier of the party requesting cancellation, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "23933333316" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string reasonCode: description: ISO 20022 mandate-cancellation reason code (BACEN MotivoCancelamentoCode, pain.011.spi.1.3.xsd:249) enum: - ACCL - CPCL - DCSD - ERSL - FRUD - NRES - OTHS - PCFD - SJUD - SLCR - SLDB examples: - SLDB type: string required: - originatorTaxId - reasonCode - mandate type: object CreateMandateRequest: additionalProperties: false properties: mandate: $ref: "#/components/schemas/Pain009MandateDetailsRequest" description: Mandate body carried by the emission requestExpiresAt: description: Expiry of the mandate confirmation request, RFC3339 UTC. It must also fall after the request's creation instant, which only the service can check. examples: - "2026-06-10T15:00:00Z" format: date-time type: string required: - requestExpiresAt - mandate type: object CreateMandateResolution: additionalProperties: false properties: accepted: description: Whether the mandate is accepted (true) or rejected (false) examples: - true type: - boolean - "null" authorizationJourney: description: Adhesion journey through which the payer granted the permission (MndtPrcgTp AUTn). Required when mandateStatus is CFDB and refused otherwise enum: - AUT1 - AUT2 - AUT3 - AUT4 examples: - AUT1 type: string authorizedAt: description: Instant the payer granted the permission, RFC3339. Stamped as the AUTn processing instant and, on AUT1, AUT2 and AUT4, as the UPDT instant. Required when mandateStatus is CFDB and refused otherwise examples: - "2026-06-10T09:03:00.480Z" format: date-time type: string mandate: $ref: "#/components/schemas/MandateDetailsRequest" description: Mandate body identifying the mandate being resolved mandateStatus: description: "ISO 20022 mandate status code. Required when accepted is true and refused when accepted is false. PDNG acknowledges receipt of a mandate awaiting confirmation (the jornada-1 answer to a pain.009, owed within 1 minute): it answers the received pain.009 recorded on the mandate and is sent without changing the mandate, which keeps awaiting the payer's decision. CFDB communicates the payer's authorization and requires authorizationJourney, authorizedAt and payerMunicipalityCode: with AUT1 it activates a mandate awaiting confirmation from a received pain.009; with AUT2, AUT3 or AUT4 (QR-code journeys) it activates that same mandate if it awaits confirmation, or else registers the mandate from this body directly as active; a mandate held in any other state is refused with 409. CCLD confirms a cancellation requested by a received pain.011 and is the only acceptance a mandate with a pending cancellation takes" examples: - CFDB type: string payerMunicipalityCode: description: 7-digit IBGE code of the payer's município (Dbtr/PstlAdr/TwnNm); 0000000 when the payer's domicile is unknown. Required when mandateStatus is CFDB and refused otherwise examples: - "5300108" pattern: ^[0-9]{7}$ type: string recurrenceCreatedAt: description: Instant the recurrence was created, RFC3339, read from the Rec the payer's institution fetched from the recebedor's Pix API. Stamped as the CRTN processing instant of a QR-code authorization. Required when authorizationJourney is AUT2, AUT3 or AUT4 and the mandate is not yet held here. When the mandate is held (a received pain.009 awaits confirmation) it may be omitted; if sent it must be the same instant the pain.009 recorded, which is what the message echoes. Refused on every other resolution, which echoes the instant recorded from the received pain.009 or pain.011 examples: - "2026-06-09T00:01:00.620Z" format: date-time type: string rejectReason: description: "ISO 20022 rejection reason code (BACEN MotivoRejeicaoCode). Required when accepted is false and refused when accepted is true. A rejection names what it answers from the mandate's record: after this rail sent the PDNG it is the payer's rejection and names nothing; before it, it answers the received pain.009; on a pending cancellation it answers the received pain.011" examples: - AC01 type: string settlementConfirmationReceivedAt: description: Instant the payer's institution received the pacs.002 confirming the settlement, RFC3339. Stamped as the UPDT instant of a jornada-3 authorization. Required when authorizationJourney is AUT3 and refused otherwise examples: - "2026-06-10T09:04:10.250Z" format: date-time type: string required: - accepted - mandate type: object CreatePaymentRequest: additionalProperties: false properties: acceptedAt: description: "t0': the instant your system received the paying user's confirmation to send this order, or, for a legal-entity payer, accepted the request after its security checks and the amount block (Manual de Tempos do Pix v7.0 §4.1). Written verbatim to AccptncDtTm; BACEN measures its §4.1.1.1 indicator from it, so it is never filled in here. RFC 3339. Required. Refused with 422 when later than the instant this rail creates the pacs.008 by more than 2 s, the allowance for your servers' clocks against this rail's; within it, written unchanged. A retry under the same X-Idempotency must resend the same request, this instant included (member order and whitespace do not count): another request is refused with 422." examples: - "2026-06-10T12:00:00.000Z" format: date-time type: string amount: description: Payment amount as a positive decimal string with exactly two fraction digits, BRL. Shaped as BACEN's monetary pattern (API Pix 2.9 \d{1,10}\.\d{2}; the SPI wire type ActiveCurrencyAndAmount_SimpleType allows 18 total digits with 2 fraction digits). The 0.01..9999999999.99 range is checked by the payment domain, which a string schema cannot express. examples: - "150.00" pattern: ^[0-9]{1,10}\.[0-9]{2}$ type: string creditorISPB: description: "ISPB (8 digits or uppercase letters) of the participant holding the receiver's transactional account (participanteDoUsuarioRecebedor). Required: it names where the money lands." examples: - "87654321" type: string endToEndId: description: "SPI end-to-end identifier (E{ISPB}{YYYYMMDD}{uniqueID}, 32 chars). Optional: when omitted the server generates it." examples: - E1234567820250307ABCDEFGHIJKLMNO type: string initiationType: description: "Forma de iniciação of the pacs.008 (MndtRltdInf/Tp/LclInstrm/Prtry): MANU account data keyed in, DICT Pix key keyed in, QRES/QRDN static/dynamic QR Code, APES/APDN static/dynamic Pix por aproximação, INIC payment initiation service, AUTO Pix Automático settlement. It decides the other fields (PACS008.xlsx 5.13.2, Manual de Padrões do Pix v2.9.0 §3.2): receiver.pixKey is required except on MANU and AUTO, where it is refused; txId is required on QRDN/APDN (26-35 characters) and INIC (up to 25), optional on QRES/APES (up to 25, omit when the static QR has none or '***'), refused otherwise; scheduleId is AUTO's; initiatorCNPJ is required on INIC. Refused with 422 when they disagree. Optional: omitted means MANU." enum: - MANU - DICT - INIC - QRES - QRDN - APES - APDN - AUTO examples: - DICT type: string initiatorCNPJ: description: CNPJ of the institution that provided the payment initiation service (cnpjIniciadorPagamento, InitgPty), unpunctuated. Required when the payment was started through a payment initiator, whatever the initiationType, and only then (PACS008.xlsx row 29); required on INIC. The initiator mints the endToEndId (Manual de Padrões §3.2), so it must be sent and its 8-character agent must be this CNPJ's first 8 characters. examples: - "13866572000140" pattern: ^[0-9A-Z]{12}[0-9]{2}$ type: string originatorISPB: description: ISPB (8 digits or uppercase letters) of the originating participant. examples: - "12345678" type: string payer: $ref: "#/components/schemas/PaymentPayerRequest" description: The paying user (usuário pagador) whose transactional account is debited. purpose: description: "Finalidade of the payment (Purp/Cd): IPAY purchase or transfer, GSCB Pix Troco, OTHR Pix Saque. GSCB and OTHR require withdrawal and IPAY refuses it. A saque starts only from QRDN, APDN, QRES, APES or INIC, a troco only from QRDN, APDN or INIC (Regulamento Pix art. 11-I; Manual de Padrões v2.9.0 §2.6.1: no troco on a static QR Code). Optional: omitted means IPAY." enum: - IPAY - GSCB - OTHR examples: - IPAY type: string receiver: $ref: "#/components/schemas/PaymentReceiverRequest" description: The receiving user (usuário recebedor) whose transactional account is credited. remittanceInfo: description: "Free text between the users (informacoesEntreUsuarios): from the payer to the payee; under AUTO (Pix Automático), from the payee to the payer. Sent on the pacs.008 as RmtInf/Ustrd (PACS008.xlsx: Max140Text, [0..1]), trimmed of leading and trailing whitespace. Optional: omitted or blank sends no RmtInf. At most 140 characters, counted as characters, not bytes, and before that whitespace is trimmed; only characters valid in XML 1.0 are accepted, and any other character is refused with 422." examples: - Aluguel de março maxLength: 140 type: string scheduleId: description: "PmtInfId of the pain.013 that originated the Pix Automático instruction this payment settles, written to (idConciliacaoRecebedor). Required when initiationType is AUTO, except when initiatorCNPJ is sent (an initiated AUTO carries no TxId), and refused otherwise. 26 to 35 alphanumeric characters (PACS008.xlsx, rule for AUTO). Not the recurrence id: a recurrence spans many cycles, each with its own pain.013." examples: - SCHEDULE2026REF0000000000A pattern: ^[a-zA-Z0-9]{26,35}$ type: string scheduled: description: "Declares this order a Pix Agendado — a common Pix whose settlement the paying user scheduled. It is emitted with tipoPrioridadePagamento PAGAGD and prioridadePagamento NORM, and BACEN settles it over the secondary channel within 45 minutes instead of over the primary within 40 seconds. Unrelated to the Pix Automático, which schedules through POST /api/v1/spi/scheduled-payments. Optional: omitted means an ordinary, immediate Pix." examples: - false type: boolean txId: description: "idConciliacaoRecebedor of a QR Code, Pix por aproximação or initiation-service payment, written verbatim to : the QR Code's txid (dynamic: from the payload JSON) or the one the initiation service received. Its presence and length depend on initiationType; use scheduleId for AUTO." examples: - QRDYNAMIC2026REF000000000AB pattern: ^[a-zA-Z0-9]{1,35}$ type: string withdrawal: $ref: "#/components/schemas/PaymentWithdrawalRequest" description: "The Pix Saque or Pix Troco block (RmtInf/Strd), required when purpose is GSCB or OTHR and refused otherwise. Map it from the QR Code read (Manual de Padrões Anexo V §2): the amount is the whole IntrBkSttlmAmt, purchase plus cash on a troco, the cash alone on a saque." required: - amount - creditorISPB - payer - receiver - acceptedAt type: object CreateScheduleCancellation: additionalProperties: false properties: cancellationId: description: Identifier assigned to this cancellation request (BACEN IdCancelamentoAgendamentoType) examples: - CA123456782026061112345abcdef pattern: ^CA[0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][a-zA-Z0-9]{11}$ type: string endToEndId: description: "Optional 32-character Pix end-to-end identifier (BACEN EndToEndIdType) selecting which pain.013 under scheduleId is cancelled: a received retry attempt (NTAG/RIFL) shares its charge's schedule identifier under a new EndToEndId. Names that attempt, or the charge by its own EndToEndId; any other value is refused with 404. Omitted, the charge is cancelled." examples: - E12345678202607011200abcdefghijk pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string originatorTaxId: description: "Tax identifier of the party requesting cancellation, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "23933333316" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string reasonCode: description: ISO 20022 cancellation reason code (BACEN ExternalCancellationReason1Code); CCLD and FAIL only when the installation is the payer's participant on the schedule enum: - ACCT - BLCK - CCLD - FAIL - OTHR - SLBD - SLCR examples: - SLBD type: string scheduleId: description: Schedule identifier being cancelled, 1 to 35 alphanumeric characters (BACEN TxIdType); the camt.055 names the EndToEndId its pain.013 recorded examples: - SCHEDULE2026Ref001 pattern: ^[a-zA-Z0-9]{1,35}$ type: string required: - cancellationId - scheduleId - originatorTaxId - reasonCode type: object CreateScheduleCancellationResolution: additionalProperties: false properties: accepted: description: Whether the cancellation is accepted (true) or rejected (false) examples: - true type: - boolean - "null" cancellationCorrelationId: description: AppHdr BizMsgIdr of the received camt.055 being answered, 32 characters (BACEN MsgIdType); the camt.029 echoes that camt.055's participants, cancellation id, schedule id and EndToEndId examples: - M2222222212345678901234567890123 pattern: ^M[0-9A-Z]{8}[a-zA-Z0-9]{23}$ type: string rejectReason: description: ISO 20022 rejection reason code; required only when accepted is false examples: - PRJL type: string required: - cancellationCorrelationId - accepted type: object CreateScheduledPayment: additionalProperties: false properties: amount: description: "Collection amount in BRL as a decimal string with exactly two fraction digits, up to 16 integer digits (BACEN ActiveOrHistoricCurrencyAndAmount_SimpleType: 18 total digits, 2 fraction digits)" examples: - "7700.23" pattern: ^[0-9]{1,16}\.[0-9]{2}$ type: string creditorAccountId: description: Creditor account number at the creditor's institution, 1 to 20 digits (BACEN Max20Numeric) examples: - "23683707994215" pattern: ^[0-9]{1,20}$ type: string creditorAccountIssuer: description: Branch (agência) code of the creditor account examples: - "5770" type: string creditorAccountType: description: "ISO 20022 cash account type of the creditor account (BACEN ExternalCashAccountType2Code): CACC (current), SVGS (savings) or TRAN (transactional). SLRY is NOT in BACEN's pain.013 type and is refused." enum: - CACC - SVGS - TRAN examples: - CACC type: string creditorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the creditor's institution examples: - "22222222" pattern: ^[0-9A-Z]{8}$ type: string creditorTaxId: description: "Creditor (recebedor) tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "45454545455" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string debtorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the debtor's institution examples: - "11111111" pattern: ^[0-9A-Z]{8}$ type: string debtorTaxId: description: "Debtor (pagador) tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "23933333316" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string endToEndId: description: 32-character Pix end-to-end identifier for the scheduled collection (BACEN EndToEndIdType). The 11-character tail is case-sensitive and is sent exactly as given. examples: - E12345678202607011200abcdefghijk pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string executionAt: description: "Instant the recebedor's PSP received the charge from its user, RFC3339 UTC, carried as ReqdExctnDt/DtTm. Required when purpose is AGND (PAIN013.xlsx, row 16): an AGND without it is refused with 422 before anything is recorded or sent." examples: - "2026-07-01T12:00:00Z" type: string expiryDate: description: Last date the instruction may settle, YYYY-MM-DD examples: - "2026-07-10" format: date type: string mandateId: description: Identifier of the Pix Automático mandate authorising this collection (BACEN IdRecorrenciaType) examples: - RR123456782026061012345abcdef pattern: ^[RC][RN][0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][a-zA-Z0-9]{11}$ type: string purpose: description: "ISO 20022 payment purpose code (BACEN FinalidadeAgendamentoType): AGND (agendamento), NTAG (nova tentativa pós-vencimento) or RIFL (reenvio por falha de liquidação)" enum: - AGND - NTAG - RIFL examples: - AGND type: string remittanceInfo: description: Free-text remittance information for the collection examples: - cobrança mensal type: string scheduleId: description: Scheduled-payment (agendamento) identifier, 1 to 35 alphanumeric characters (BACEN TxIdType, carried as PmtInfId) examples: - SCHEDULE2026Ref001 pattern: ^[a-zA-Z0-9]{1,35}$ type: string ultimateDebtorName: description: Name of the ultimate debtor when different from the account holder examples: - Fulano da Silva type: string ultimateDebtorTaxId: description: Tax identifier of the ultimate debtor (CPF or CNPJ), no punctuation examples: - "98722222234" type: string required: - scheduleId - mandateId - endToEndId - amount - expiryDate - debtorTaxId - debtorAgentIspb - creditorTaxId - creditorAgentIspb - creditorAccountId - creditorAccountType - purpose type: object CreateScheduledPaymentResolution: additionalProperties: false properties: accepted: description: Whether the scheduled payment is accepted (true) or rejected (false) examples: - true type: - boolean - "null" endToEndId: description: "Optional 32-character Pix end-to-end identifier (BACEN EndToEndIdType) selecting which pain.013 under originalScheduleId is resolved: a received retry attempt (NTAG/RIFL) shares its charge's schedule identifier under a new EndToEndId. Names that attempt, or the charge by its own EndToEndId; any other value is refused with 404. Omitted, the charge is resolved." examples: - E12345678202607011200abcdefghijk pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string originalScheduleId: description: Schedule identifier of the pain.013 being resolved, 1 to 35 alphanumeric characters (BACEN TxIdType); the pain.014 echoes the EndToEndId, creditor agent and creditor tax id that pain.013 recorded examples: - SCHEDULE2026Ref001 pattern: ^[a-zA-Z0-9]{1,35}$ type: string rejectReason: description: ISO 20022 rejection reason code; required only when accepted is false. The accepted set shrinks under catalogue 5.13.2, so it is checked by the builder against the kit in force rather than published as a fixed list. examples: - AB10 type: string required: - originalScheduleId - accepted type: object CreateSettlementReportRequest: additionalProperties: false properties: transactions: description: Internally settled transactions to report (at least one) items: $ref: "#/components/schemas/SettlementReportTransactionRequest" minItems: 1 type: - array - "null" required: - transactions type: object CreateStructuredOperationRequest: additionalProperties: false properties: businessKey: description: Optional client-supplied correlation key for the operation; not unique-enforced. examples: - client-payment-001 type: string metadata: additionalProperties: {} description: Optional free-form metadata object attached to the operation; also scanned for raw-payload tunneling. Top-level keys the rail owns (pain_lifecycle_state, pain_pending_request_id, pain_pending_recurrence_created_at, pain_pending_cancellation_id, pain_authorization_status_id, pain_sent_request_id, pain_schedule_cancellation_id, pain_received_schedule_cancellation_id, pain_schedule_debtor_agent_ispb, pain_schedule_creditor_agent_ispb, pain_schedule_side, pain_schedule_end_to_end_id, pain_schedule_creditor_tax_id, pain_receipt_acknowledged_at, owed_schedule_verdict, owed_schedule_verdict_message_type, owed_schedule_refusal_reason, owed_schedule_refusal_reserved_at, owed_mandate_verdict, owed_mandate_verdict_message_type, owed_mandate_verdict_message_id, answer_reserved_message_type, answer_reserved_message_id, answer_reserved_state, answer_reserved_at, answer_reserved_from_state, answer_reserved_landed_at, request_reserved_message_type, request_reserved_message_id, request_reserved_state, request_reserved_from_state, request_reserved_at, request_reserved_resource_id, request_refused_at, request_refused_reason, request_reserved_sender_ispb, request_reserved_originator_tax_id, request_reserved_reason_code, request_reserved_processed_at, request_resend_count, request_resend_message_id, request_resend_at, request_resend_resource_id, request_resend_landed_at, request_resend_refused_at, request_resend_refused_reason, received_camt055_cancellation_id, received_camt055_content_fingerprint, received_camt055_schedule_id, received_camt055_requester_ispb, received_camt055_addressee_ispb, received_camt055_original_end_to_end_id, reconciliation_devolucao_row_id, reconciliation_return_id, reconciliation_amount, reconciliation_currency, reconciliation_end_to_end_id, reconciliation_origin_message, reconciliation_reason, reconciliation_actor) are refused with 422 RESERVED_METADATA_KEY. type: object operationType: description: Structured operation type; variant validators own the payload schema for each type. enum: - PAYMENT_TRANSFER - PAYMENT_RETURN - CONNECTIVITY_TEST - ACCOUNT_INFORMATION_REQUEST - PARTICIPANT_ADMINISTRATION - PIX_AUTOMATIC_AUTHORIZATION - SCHEDULED_PAYMENT_INSTRUCTION - TRACKING_REPORT examples: - PAYMENT_TRANSFER type: string participant: $ref: "#/components/schemas/ParticipantDTO" description: SPI participant context (BACEN participant identity) the operation acts on behalf of. payload: additionalProperties: {} description: Operation payload as a free-form object; decoded as a map so the recursive raw-payload scanner runs before schema validation. type: object requestedExecutionAt: description: Optional requested execution time; RFC3339, parsed to UTC. Absent means execute now. examples: - "2030-01-01T00:00:00Z" type: string required: - operationType - participant - payload type: object DeactivatePixCertificateRequest: additionalProperties: false properties: reason: description: Optional operator rationale recorded in the audit trail. examples: - rotated to Q3 leaf maxLength: 512 type: string type: object DecideApprovalRequestBody: additionalProperties: false properties: decision: description: "Decider verdict: APPROVE or DENY." enum: - APPROVE - DENY type: string decisionReason: description: "Free-form justification for the decision; persisted for audit (1..2000 characters). Lerian's own bound. A blank justification is refused: an audit row nobody can read is not an audit row." maxLength: 2000 minLength: 1 type: string required: - decision - decisionReason type: object Detail: additionalProperties: false properties: code: description: "Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN)." type: string correlationId: description: Request-scoped correlation identifier echoing X-Request-ID. examples: - req-7a3f9c2e type: string detail: description: A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: "#/components/schemas/ErrorDetail" type: - array - "null" instance: description: A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: "#/components/schemas/Upstream" description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one." required: - correlationId type: object DevolucaoHorario: additionalProperties: false properties: liquidacao: description: Instant this PSP recorded the return settled; present only when DEVOLVIDO. format: date-time type: string solicitacao: description: Instant the return was requested at this PSP (RFC 3339, UTC). format: date-time type: string type: object DevolucaoResponse: additionalProperties: false properties: descricao: description: Free-text return description (≤140 chars). type: string horario: $ref: "#/components/schemas/DevolucaoHorario" description: When the return was requested and, once DEVOLVIDO, settled. id: description: "DevolucaoId ([a-zA-Z0-9]{1,35}): the client's, or the full-return key derived from the Pix." type: string natureza: description: Return nature implied by the return's pacs.004 reason (MD06→ORIGINAL, SL02→RETIRADA, BE08→MED_OPERACIONAL, FR01→MED_FRAUDE). enum: - ORIGINAL - RETIRADA - MED_OPERACIONAL - MED_FRAUDE type: string rtrId: description: pacs.004 ReturnIdentification ([a-zA-Z0-9]{32}) allocated for this attempt. type: string status: description: Return status. enum: - EM_PROCESSAMENTO - DEVOLVIDO - NAO_REALIZADO type: string valor: description: Returned amount as a decimal string, scale 2 (BRL). type: string required: - id - valor - natureza - horario - status type: object DevolucaoSolicitadaRequest: additionalProperties: false properties: descricao: description: Optional free-text return description (≤140 chars), sent on the pacs.004 as RmtInf/Ustrd. Only characters valid in XML 1.0 are accepted; any other character is refused with 422. maxLength: 140 type: string natureza: description: Return nature; absent ⇒ ORIGINAL. ORIGINAL → pacs.004 MD06, RETIRADA → SL02. enum: - ORIGINAL - RETIRADA type: string valor: description: Requested return amount; the sum of all returns must not exceed the original Pix value. examples: - "30.00" pattern: ^\d{1,10}\.\d{2}$ type: string required: - valor type: object ErrorDetail: additionalProperties: false properties: location: description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object EvidenceExportResponse: additionalProperties: false properties: accessRef: description: Opaque storage handle for the export artifact (e.g. S3 URI or Vault path); never raw payload bytes. examples: - "" type: string actorId: description: Identifier of the actor that requested the export. examples: - user:fred type: string actorType: description: "Actor principal class: USER, SERVICE, or SYSTEM." examples: - USER type: string createdAt: description: Job creation timestamp; RFC3339, UTC. examples: - "2026-05-06T12:00:00Z" type: string expiresAt: description: Time the export artifact/access expires; RFC3339, UTC. examples: - "" type: string includeRawPayload: description: Whether the export was requested to include the raw payload. examples: - false type: boolean jobId: description: Server-assigned evidence export job identifier. examples: - export-1 type: string operationId: description: Operation whose evidence is being exported. examples: - op-1 type: string reason: description: Reason supplied when the export was requested. examples: - audit review pull type: string state: description: Export job lifecycle state (e.g. QUEUED). examples: - QUEUED type: string updatedAt: description: Job last-update timestamp; RFC3339, UTC. examples: - "2026-05-06T12:00:00Z" type: string required: - jobId - operationId - state - includeRawPayload type: object EvidenceItemResponse: additionalProperties: false properties: actorSubject: description: Subject identifier of the actor that produced the evidence, if attributed. type: string actorType: description: "Actor principal class: USER, SERVICE, or SYSTEM." examples: - SERVICE type: string category: description: "Evidence category: VALIDATION, SECURITY, DISPATCH, RESPONSE, STATE, OPERATOR, APPROVAL, or PAYLOAD." examples: - VALIDATION type: string correlationId: description: Correlation identifier linking this evidence to a wider trace or flow. type: string messageId: description: Rail message identifier the evidence is anchored to, if any. examples: - 550e8400-e29b-41d4-a716-446655440002 type: string metadata: additionalProperties: {} description: Optional free-form metadata object attached to the evidence record. type: object operationId: description: Operation this evidence record belongs to. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string payloadHash: description: Hash anchoring the evidence to a payload; omitted when the access policy denies it. examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string rawPayloadAccessReason: description: Reason the raw payload reference was granted or denied for this item. type: string rawPayloadRef: description: Opaque reference to the retained raw payload; populated only when includeRawPayloadRef=true and the access policy allows it. type: string recordedAt: description: Time the evidence was recorded; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string result: description: "Evidence outcome: PASSED, FAILED, RECORDED, or SKIPPED." examples: - PASSED type: string source: description: Origin of the evidence (e.g. the pipeline stage or rail that produced it). type: string summary: description: Human-readable summary of the evidence record. type: string required: - category - result - summary - source - recordedAt type: object EvidencePageResponse: additionalProperties: false properties: items: description: Chronological page of evidence items for the operation. items: $ref: "#/components/schemas/EvidenceItemResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque cursor to fetch the next page; absent on the last page. type: string required: - items - limit type: object FailedRepliesPageWire: additionalProperties: false properties: asOf: description: The database instant every remainingSeconds and overdue on the page was read at (RFC3339 UTC). format: date-time type: string correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: "The FAILED replies, soonest deadline first: the overdue ones lead, then the one with the least time left." items: $ref: "#/components/schemas/FailedReplyWire" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque cursor for the next page; absent when exhausted. type: string required: - items - limit - asOf type: object FailedReplyWire: additionalProperties: false properties: attempts: description: Resends claimed; 0 for the first send. examples: - 0 format: int64 type: integer cancellationCorrelationId: description: "On a camt.029: the received camt.055's BizMsgIdr, the cancellationCorrelationId its resend takes." examples: - M2222222212345678901234567890123 type: string deadline: description: "The instant past which no resend is accepted (RFC3339 UTC): 2h after the pain.013 arrived, 12h after the camt.055 did." format: date-time type: string failedAt: description: "When the reply last moved: the refusal or the release that left it FAILED (RFC3339 UTC)." format: date-time type: string failureReason: description: The reason the last admi.002 refusing the reply recorded; absent when none did (an operator released a first send). type: string messageId: description: "The MsgId (BizMsgIdr) BACEN refused: the reply's last send." examples: - M12345678202610221100abcdefghijk type: string messageType: description: "The reply: a pain.014 answering a received pain.013, or a camt.029 answering a received camt.055." enum: - pain.014 - camt.029 examples: - pain.014 type: string operationId: description: "The operation the reply answers: its evidence (GET /api/v1/spi/operations/{operationId}/evidence) holds the admi.002 that refused it." format: uuid type: string operationState: description: "The operation's state now. A refusal moves no operation: the verdict stands." examples: - AWAITING_RESPONSE type: string operationType: description: The operation's type. examples: - SCHEDULED_PAYMENT_INSTRUCTION type: string overdue: description: "True once the deadline passed (by the database clock at asOf): no resend is accepted any more." type: boolean reasonCode: description: The reason a refusing reply states; absent on an acceptance. examples: - MIDI type: string remainingSeconds: description: Whole seconds from asOf to the deadline, negative once it passed. overdue is the authority on whether a resend is still accepted. examples: - 5400 format: int64 type: integer resourceId: description: BACEN's PI-ResourceId from the 201 that delivered messageId, when one landed before the refusal. examples: - c7e3d74bca8e type: string scheduleId: description: "The schedule the reply concerns: the pain.013's a pain.014 resolves (the originalScheduleId its resend takes), or the one the received camt.055 cancels." examples: - SCHEDULE2026Ref001 type: string sentAt: description: When messageId was built (RFC3339 UTC). format: date-time type: string verdict: description: The verdict the reply states (ACSP or RJCT on a pain.014, ACCR or RJCR on a camt.029); a resend restates it. examples: - RJCT type: string required: - operationId - messageType - verdict - messageId - attempts - failedAt - deadline - remainingSeconds - overdue type: object InitiatePaymentReturnRequest: additionalProperties: false properties: amount: description: Amount to return (BRL); absent ⇒ the original Pix value. The sum of all returns must not exceed it. examples: - "30.00" pattern: ^\d{1,10}\.\d{2}$ type: string devolucaoId: description: DevolucaoId the return is recorded and replayed under; absent ⇒ the full-return key derived from the Pix, which a partial return may not use. examples: - med01 pattern: ^[a-zA-Z0-9]{1,35}$ type: string reason: description: BACEN return reason code (BE08, FR01, MD06, SL02); it goes on the pacs.004 as sent. examples: - FR01 minLength: 1 type: string required: - reason type: object MandateDetailsRequest: additionalProperties: false properties: collectionAmount: description: Fixed per-collection amount in BRL as a decimal string, scale 2; omit for variable-amount mandates examples: - "100.00" type: string creditorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the creditor's institution examples: - "22222222" pattern: ^[0-9A-Z]{8}$ type: string creditorName: description: Creditor (recebedor) name, 1 to 140 characters (BACEN Max140Text). The builder additionally counts bytes, so an accented name near the ceiling can still be refused there. examples: - Empresa XPTO maxLength: 140 minLength: 1 type: string creditorReference: description: Free-text creditor reference for reconciliation examples: - contrato 42 type: string creditorTaxId: description: "Creditor tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "12345678000195" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string debtorAccountId: description: Debtor account number at the debtor's institution, 1 to 20 digits (BACEN Max20Numeric) examples: - "1111108" pattern: ^[0-9]{1,20}$ type: string debtorAccountIssuer: description: Branch (agência) code of the debtor account examples: - "0001" type: string debtorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the debtor's institution examples: - "11111111" pattern: ^[0-9A-Z]{8}$ type: string debtorTaxId: description: "Debtor (pagador) tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "23933333316" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string finalCollectionDate: description: Date of the last scheduled collection, YYYY-MM-DD; omit for open-ended mandates examples: - "2027-07-01" type: string firstCollectionDate: description: Date of the first scheduled collection, YYYY-MM-DD examples: - "2026-07-01" format: date type: string frequency: description: "ISO 20022 collection frequency code (BACEN Frequency6Code): MIAN (twice a year), MNTH (monthly), QURT (quarterly), WEEK (weekly) or YEAR (yearly)" enum: - MIAN - MNTH - QURT - WEEK - YEAR examples: - MNTH type: string mandateId: description: Pix Automático mandate (recorrência) identifier, 29 characters (BACEN IdRecorrenciaType) examples: - RR123456782026061012345abcdef pattern: ^[RC][RN][0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][a-zA-Z0-9]{11}$ type: string mandateRequestId: description: Mandate confirmation-request identifier (solicitação de confirmação). Its prefix depends on the emission consuming this body — SC on a pain.009 request, IC on a pain.011 cancellation, IS on a pain.012 resolution — so only its presence is published and the shape is applied per message. examples: - SC123456782026061012345abcdef minLength: 1 type: string referredDocumentNumber: description: Reference document/contract number underpinning the mandate, 1 to 35 characters (BACEN Max35Text) examples: - "1234567890" maxLength: 35 minLength: 1 type: string trackingIndicator: description: Whether the mandate uses a tracked (jornada de tracking) flow examples: - false type: boolean ultimateDebtorName: description: Name of the ultimate debtor when different from the account holder examples: - Sicrano da Silva type: string ultimateDebtorTaxId: description: Tax identifier of the ultimate debtor (CPF or CNPJ), no punctuation examples: - "02822222215" type: string required: - mandateId - mandateRequestId - frequency - firstCollectionDate - trackingIndicator - creditorName - creditorTaxId - creditorAgentIspb - debtorTaxId - debtorAccountId - debtorAgentIspb - referredDocumentNumber type: object MandateEmissionResponse: additionalProperties: false properties: correlationId: description: Emission AppHdr BizMsgIdr the inbound response must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string mandateId: description: Mandate identifier the emission acted on examples: - RR123456782026061012345abcdef type: string mandateState: description: Mandate lifecycle state after emission examples: - PENDING_CONFIRMATION type: string messageType: description: ISO 20022 message type emitted (pain.009, pain.011, or pain.012) examples: - pain.009.spi.1.1 type: string operationId: description: UUID of the recorded mandate operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - mandateId - mandateState - state type: object MandateListResponse: additionalProperties: false properties: correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: Mandate operations, newest first. items: $ref: "#/components/schemas/MandateReadModelResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer offset: description: Zero-based offset of the first item in this page. format: int64 type: integer total: description: Total number of mandate operations matching the status filter (COUNT over the same predicate, excluding limit/offset); stable across pages. format: int64 type: integer required: - items - total - limit - offset type: object MandateReadModelResponse: additionalProperties: false properties: cancellationReceived: description: "True while a pain.011 this installation received keeps the mandate cancellation-pending (mandateState REQUEST_CANCELLATION_PENDING or CANCELLATION_PENDING): the pain.012 answering it is this installation's to send. False when its own pain.011 parked the mandate, which then waits on the other PSP's pain.012, and in every other state." examples: - false type: boolean correlationId: description: Persisted correlation handle (client_operations.business_key). examples: - recurrence|RR123456782026061012345abcdef type: string createdAt: description: Operation creation timestamp (RFC3339 UTC). examples: - "2026-06-10T15:00:00Z" format: date-time type: string mandateId: description: Mandate (recorrência) identifier the operation tracks. examples: - RR123456782026061012345abcdef type: string mandateState: description: Mandate lifecycle state (metadata pain_lifecycle_state); empty before any lifecycle transition. examples: - PENDING_CONFIRMATION type: string operationId: description: UUID of the recorded mandate operation (client_operations.id). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string operationState: description: Operation lifecycle state (client_operations.state). examples: - AWAITING_RESPONSE type: string requestReceived: description: "True when this installation received the mandate's pain.009, as the payer's PSP: the pain.012 answering it is this installation's to send. False when it sent the pain.009, or none opened the mandate." examples: - true type: boolean updatedAt: description: Operation last-update timestamp (RFC3339 UTC). examples: - "2026-06-10T15:05:00Z" format: date-time type: string required: - operationId - mandateId - mandateState - operationState - correlationId - requestReceived - cancellationReceived - createdAt - updatedAt type: object ManualResolutionRequest: additionalProperties: false properties: approvalId: description: Identifier of the previously-APPROVED approval_decisions row authorising this manual resolution. format: uuid type: string outcome: description: "Verdict the operator declares for an outbound Pix or a devolução BACEN has not answered, required on one and refused on any other operation: the Pix or the devolução closes as BACEN's pacs.002 would close it and its settled or rejected fact reaches the client's ledger. The approval must name it: MANUAL_RESOLVE_SETTLED or MANUAL_RESOLVE_REJECTED (MANUAL_RESOLVE without an outcome)." enum: - SETTLED - REJECTED type: string previousState: description: Operation state expected before resolution; guards against resolving from an unexpected state (optimistic check). Upper case, and compared verbatim against the stored state. minLength: 1 type: string reason: description: Free-form operator reason for the manual resolution; persisted for audit (1..2000 characters). Lerian's own bound, the same one the approval rationales carry. maxLength: 2000 minLength: 1 type: string settledAt: description: "BACEN's settlement instant of a Pix or a devolução declared SETTLED, read from the evidence (RFC 3339 with offset): required with SETTLED and refused otherwise, never in the future nor before the Pix or the devolução was created. The settled fact and its settlement carry it." format: date-time type: string required: - approvalId - reason - previousState type: object ManualResolutionResponse: additionalProperties: false properties: newState: description: Operation lifecycle state after resolution (typically MANUALLY_RESOLVED). type: string operationId: description: Operation that was manually resolved. type: string resolvedAt: description: Time the operation was resolved; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string required: - operationId - newState type: object MessageLogDetailResponse: additionalProperties: false properties: correspondent: $ref: "#/components/schemas/MessageLogRowResponse" description: "Mensagem Correspondente: the sibling row sharing operation_id, if any." message: $ref: "#/components/schemas/MessageLogRowResponse" description: "Mensagem Original: the requested message_records row." required: - message type: object MessageLogPageResponse: additionalProperties: false properties: correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: Message-log rows, newest first. items: $ref: "#/components/schemas/MessageLogRowResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque cursor for the next page; absent when exhausted. type: string total: description: Total number of message-log rows matching the filter (COUNT over the same predicates, excluding the cursor); stable across pages. format: int64 type: integer required: - items - total - limit type: object MessageLogRowResponse: additionalProperties: false properties: businessKey: description: Business correlation key. type: string createdAt: description: Row creation timestamp (Data/Hora, RFC 3339 UTC). examples: - "2025-03-07T14:30:00Z" type: string direction: description: "Flow (Fluxo): INBOUND / OUTBOUND / INTERNAL." examples: - OUTBOUND type: string family: description: Message family. examples: - PACS type: string messageRecordId: description: message_records row id. type: string messageType: description: Catalogue message type (Tipo). examples: - pacs.008 type: string operationId: description: Correlated operation id; empty for uncorrelated rows. type: string participantIspb: description: Participant ISPB (8 digits or uppercase letters). examples: - "12345678" type: string payloadHash: description: SHA-256 hex digest of the upstream payload (audit-by-hash; the raw payload is never stored). type: string payloadRetained: description: Always false on SPI unless an external vault retains the bytes; the raw signed XML is never persisted at rest. type: boolean receivedAt: description: Receipt timestamp for inbound rows (RFC 3339 UTC). examples: - "2025-03-07T14:30:00Z" type: string state: description: Lifecycle state (Situação). examples: - SUBMITTED type: string required: - messageRecordId - family - messageType - direction - state - payloadHash - payloadRetained - createdAt type: object MessageRequest: additionalProperties: false properties: xml: description: "ISO 20022 message as a raw XML string (e.g. pacs.008). Only its presence is published: the real gate is XSD validation against the vendored BACEN catalogue, which no JSON Schema keyword can express." examples: - ... minLength: 1 type: string required: - xml type: object MessageResponse: additionalProperties: false properties: messageType: description: ISO 20022 message type detected for the submitted payload. examples: - pacs.008 type: string status: description: Validation result for the submitted message (e.g. valid). examples: - valid type: string required: - messageType - status type: object OperationRepliesWire: additionalProperties: false properties: items: description: The replies the operation sent, at most one per type; empty when it sent none. The operation's STATE and OPERATOR evidence is at GET /api/v1/spi/operations/{operationId}/evidence. items: $ref: "#/components/schemas/OperationReplyWire" type: array required: - items type: object OperationReplyWire: additionalProperties: false properties: attempts: description: Resends claimed; 0 for the first send. examples: - 0 format: int64 type: integer deadline: description: "The instant past which no resend is accepted (RFC3339 UTC): 2h after the pain.013 arrived, 12h after the camt.055 did." format: date-time type: string messageId: description: "The MsgId (BizMsgIdr) the reply was last sent under: the id to confirm with BACEN, and the one a release names." examples: - M12345678202610221100abcdefghijk type: string messageType: description: "The reply: a pain.014 answering the pain.013 the operation received, or a camt.029 answering its camt.055." enum: - pain.014 - camt.029 examples: - pain.014 type: string reasonCode: description: The reason a refusing reply states; absent on an acceptance. examples: - MIDI type: string resourceId: description: "BACEN's PI-ResourceId from the 201 that delivered messageId. Present means BACEN took it: only an admi.002 reopens such a reply, never a release." examples: - c7e3d74bca8e type: string sentAt: description: When messageId was built (RFC3339 UTC). format: date-time type: string state: description: "SENT: the reply under messageId may be at BACEN, and nothing may send another. FAILED: BACEN refused it (admi.002) or an operator released it; the endpoint that sent it resends the same verdict before the deadline." enum: - SENT - FAILED examples: - SENT type: string stuck: description: "True when the reply is SENT with no resource id and older than the transport's submit budget (by the database clock): it may or may not be at BACEN, nothing resends it, and only an admi.002 or a release reopens it. A younger one may still be on its way to its 201 and is not stuck." type: boolean verdict: description: "The verdict the reply states: ACSP or RJCT on a pain.014, ACCR or RJCR on a camt.029. A resend restates it." examples: - RJCT type: string required: - messageType - verdict - state - messageId - stuck - attempts type: object OperatorAffordanceResp: additionalProperties: false properties: reasonCode: description: Stable machine code for display + telemetry only. type: string requirement: description: "Gating tier: DIRECT, APPROVAL_REQUIRED, or ADVISORY." examples: - DIRECT type: string semanticsNote: description: Display-only note clarifying what the verb does on this row. type: string verb: description: Operator intent this affordance authorizes on the row. enum: - ACKNOWLEDGE - INVESTIGATE - DISMISS - RESOLVE - RETRY - REPLAY - REDRIVE - RESUBMIT - MANUAL_RESOLUTION - RECONCILE_WITH_BACEN examples: - RETRY type: string required: - verb - requirement type: object PaginacaoBlock: additionalProperties: false properties: itensPorPagina: description: Items per page. format: int64 minimum: 1 type: integer paginaAtual: description: Current page (0-based per BACEN). format: int64 minimum: 0 type: integer quantidadeDePaginas: description: Number of pages across the full matched result set. format: int64 minimum: 1 type: integer quantidadeTotalDeItens: description: Total matched items across all pages (COUNT over the same filter predicates, excluding limit/offset). format: int64 minimum: 0 type: integer required: - paginaAtual - itensPorPagina - quantidadeDePaginas - quantidadeTotalDeItens type: object Pain009MandateDetailsRequest: additionalProperties: false properties: collectionAmount: description: Fixed per-collection amount in BRL as a decimal string, scale 2; omit for variable-amount mandates examples: - "100.00" type: string creditorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the creditor's institution examples: - "22222222" pattern: ^[0-9A-Z]{8}$ type: string creditorName: description: Creditor (recebedor) name, 1 to 140 characters (BACEN Max140Text). The builder additionally counts bytes, so an accented name near the ceiling can still be refused there. examples: - Empresa XPTO maxLength: 140 minLength: 1 type: string creditorReference: description: Free-text creditor reference for reconciliation examples: - contrato 42 type: string creditorTaxId: description: "Creditor tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "12345678000195" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string debtorAccountId: description: Debtor account number at the debtor's institution, 1 to 20 digits (BACEN Max20Numeric) examples: - "1111108" pattern: ^[0-9]{1,20}$ type: string debtorAccountIssuer: description: Branch (agência) code of the debtor account examples: - "0001" type: string debtorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the debtor's institution examples: - "11111111" pattern: ^[0-9A-Z]{8}$ type: string debtorTaxId: description: "Debtor (pagador) tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "23933333316" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string finalCollectionDate: description: Date of the last scheduled collection, YYYY-MM-DD; omit for open-ended mandates examples: - "2027-07-01" type: string firstCollectionDate: description: Date of the first scheduled collection, YYYY-MM-DD examples: - "2026-07-01" format: date type: string frequency: description: "ISO 20022 collection frequency code (BACEN Frequency6Code): MIAN (twice a year), MNTH (monthly), QURT (quarterly), WEEK (weekly) or YEAR (yearly)" enum: - MIAN - MNTH - QURT - WEEK - YEAR examples: - MNTH type: string mandateId: description: Pix Automático mandate (recorrência) identifier, 29 characters (BACEN IdRecorrenciaType) examples: - RR123456782026061012345abcdef pattern: ^[RC][RN][0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][a-zA-Z0-9]{11}$ type: string mandateRequestId: description: Mandate confirmation-request identifier (solicitação de confirmação). Its prefix depends on the emission consuming this body — SC on a pain.009 request, IC on a pain.011 cancellation, IS on a pain.012 resolution — so only its presence is published and the shape is applied per message. examples: - SC123456782026061012345abcdef minLength: 1 type: string maximumAmountFloor: description: "Floor the creditor sets under any maximum amount the payer gives this mandate (pisoValorMaximo), in BRL as a decimal string, scale 2. Only on variable-amount mandates: sent together with collectionAmount the request is refused with 422. Omit when the creditor sets no floor." examples: - "50.00" type: string referredDocumentNumber: description: Reference document/contract number underpinning the mandate, 1 to 35 characters (BACEN Max35Text) examples: - "1234567890" maxLength: 35 minLength: 1 type: string trackingIndicator: description: Whether the mandate uses a tracked (jornada de tracking) flow examples: - false type: boolean ultimateDebtorName: description: Name of the ultimate debtor when different from the account holder examples: - Sicrano da Silva type: string ultimateDebtorTaxId: description: Tax identifier of the ultimate debtor (CPF or CNPJ), no punctuation examples: - "02822222215" type: string required: - mandateId - mandateRequestId - frequency - firstCollectionDate - trackingIndicator - creditorName - creditorTaxId - creditorAgentIspb - debtorTaxId - debtorAccountId - debtorAgentIspb - referredDocumentNumber type: object ParametrosConsultaPix: additionalProperties: false properties: cnpj: description: Echoed payer CNPJ filter. type: string cpf: description: Echoed payer CPF filter. type: string devolucaoPresente: description: Echoed devolucaoPresente filter. type: boolean fim: description: Window end (RFC 3339). type: string inicio: description: Window start (RFC 3339). type: string paginacao: $ref: "#/components/schemas/PaginacaoBlock" description: Pagination metadata. txIdPresente: description: Echoed txIdPresente filter. type: boolean txid: description: Echoed txid filter. type: string required: - inicio - fim - paginacao type: object ParkedICOMMessageListWire: additionalProperties: false properties: count: description: Number of rows in items. examples: - 1 format: int64 type: integer items: description: Parked and closed messages, newest park first. items: $ref: "#/components/schemas/ParkedICOMMessageWire" type: array required: - items - count type: object ParkedICOMMessageWire: additionalProperties: false properties: attempts: description: Consecutive non-terminal rail-boundary forwards of this message, including failed replays. 1 on first sight for an oversized or empty message; a redelivery after a failed dedup marker adds one. examples: - 5 format: int64 type: integer channel: description: Which physical ICOM out-stream served the message. A replay goes back through this channel's boundary. enum: - CPM - CSM examples: - CPM type: string closedAt: description: When a replay closed it (RFC3339 UTC). Absent while PARKED. format: date-time type: string closedStatus: description: The terminal rail-boundary status the closing replay received. examples: - 200 format: int64 type: integer firstRefusedAt: description: When the rail boundary first refused it (RFC3339 UTC). format: date-time type: string lastRefusedAt: description: When the rail boundary last refused it (RFC3339 UTC). format: date-time type: string lastStatusCode: description: The rail boundary's last HTTP status. Absent when the forward never completed. examples: - 500 format: int64 type: integer messageType: description: Message type sniffed from the envelope, empty when the body could not be classified. Lets an operator tell a poison pacs.008 from a poison camt.053 without opening either. examples: - pacs.008 type: string parkedAt: description: "When the message was stored and acked: on the refusal that crossed the threshold, or on first sight for an oversized or empty body (RFC3339 UTC)." format: date-time type: string payloadBytes: description: Size of the stored message in bytes; for an oversized message, the size of the stored prefix, and 0 for an empty one. The message itself is never returned by any route. examples: - 4096 format: int64 type: integer pulledAt: description: When ICOM served the message (RFC3339 UTC). A replay re-presents it with this original receipt time. format: date-time type: string reason: description: "Why the message parked: 'transport' (the boundary never answered), 'status' (it answered non-terminally), 'oversized' (the body exceeded the size cap; only its first bytes are stored) or 'empty' (the body was empty; nothing is stored). Oversized and empty messages are never forwarded and cannot be replayed. Closed vocabulary — never error text." enum: - transport - status - oversized - empty examples: - status type: string resourceId: description: BACEN's PI-ResourceId for the message — the only handle on a parked message, and the id every other operation here takes. examples: - c7e3d74bca8e type: string state: description: "PARKED: stored and awaiting a replay, except an oversized or empty message, which is kept as the record only and cannot be replayed. CLOSED: a replay reached a terminal rail-boundary outcome; the row is kept as history." enum: - PARKED - CLOSED examples: - PARKED type: string required: - resourceId - channel - state - attempts - reason - payloadBytes type: object ParticipantDTO: additionalProperties: false properties: participantIspb: description: "BACEN participant ISPB (ISPBType [0-9A-Z]{8}): exactly 8 digits or uppercase letters." examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string participantType: description: "Participant type: DIRECT, INDIRECT, SYSTEM, or UNKNOWN." enum: - DIRECT - INDIRECT - SYSTEM - UNKNOWN examples: - DIRECT type: string sponsorIspb: description: Sponsor participant ISPB (8 digits or uppercase letters); required only when ParticipantType is INDIRECT and the sponsor has been resolved upstream. examples: - "87654321" type: string required: - participantIspb - participantType type: object PaymentEventResponse: additionalProperties: false properties: occurredAt: description: Timestamp at which the event occurred (RFC 3339, UTC). examples: - "2025-03-07T14:30:00Z" type: string payload: additionalProperties: type: string description: Event-specific key/value attributes; contents vary by event type. type: object type: description: Lifecycle event type (e.g. PAYMENT_INITIATED, PAYMENT_SETTLED). examples: - PAYMENT_INITIATED type: string required: - type - occurredAt type: object PaymentHistoryResponse: additionalProperties: false properties: endToEndId: description: SPI end-to-end identifier whose history is returned (32 chars). examples: - E1234567820250307ABCDEFGHIJKLMNO type: string history: description: Ordered list of lifecycle events for the payment. items: $ref: "#/components/schemas/PaymentEventResponse" type: array historyDegraded: description: True when the event history could not be fully retrieved and may be incomplete. examples: - false type: boolean historyDegradedReason: description: Explanation for degraded history, present only when historyDegraded is true. examples: - "" type: string required: - endToEndId - history type: object PaymentPageResponse: additionalProperties: false properties: items: description: Pix sent and received, newest first. items: $ref: "#/components/schemas/PaymentResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque cursor for the next page; absent on the last page. type: string required: - items - limit type: object PaymentPayerRequest: additionalProperties: false properties: account: description: Transactional account number of the paying user, including its check digit when one exists (contaUsuarioPagador). Up to 20 characters, digits and uppercase letters. examples: - "1234567" type: string accountType: description: Type of the paying user's transactional account (tipoContaUsuarioPagador). enum: - CACC - OTHR - SLRY - SVGS - TRAN examples: - CACC type: string branch: description: "Branch holding the paying user's account, without a check digit (agenciaUsuarioPagador). Optional: omit when the account has no branch." examples: - "0001" type: string name: description: Name or corporate name of the paying user, as registered (nomeUsuarioPagador). Up to 140 characters. examples: - MARIA DE SOUZA type: string taxId: description: CPF (11 digits) or CNPJ (12 alphanumeric characters plus 2 check digits) of the paying user, unpunctuated (cpfCnpjUsuarioPagador). examples: - "12345678901" type: string required: - name - taxId - account - accountType type: object PaymentReceiverRequest: additionalProperties: false properties: account: description: Transactional account number of the receiving user, including its check digit when one exists (contaUsuarioRecebedor). Up to 20 characters, digits and uppercase letters. examples: - "7654321" type: string accountType: description: "Type of the receiving user's transactional account (tipoContaUsuarioRecebedor). Conta-salário (SLRY) is rejected: that account type cannot receive payments." enum: - CACC - OTHR - SVGS - TRAN examples: - CACC type: string branch: description: Branch holding the receiving user's account, without a check digit (agenciaUsuarioRecebedor). Optional. examples: - "0001" type: string pixKey: description: The receiving user's chave Pix exactly as the DICT returned it (CdtrAcct/Prxy/Id), up to 77 characters. Required for every initiationType except MANU and AUTO, which refuse it. examples: - fulano@example.com maxLength: 77 type: string taxId: description: CPF (11 digits) or CNPJ (12 alphanumeric characters plus 2 check digits) of the receiving user, unpunctuated (cpfCnpjUsuarioRecebedor). examples: - "98765432100" type: string required: - taxId - account - accountType type: object PaymentResponse: additionalProperties: false properties: amount: description: Payment amount as a decimal string, scale 2 (BRL). examples: - "150.00" type: string channel: description: "ICOM channel the Pix's pacs.008 rode: on a sent Pix the one it left on, CSM (secondary) for a scheduled Pix (PAGAGD) and CPM (primary) otherwise; on a received Pix the one it arrived on. Omitted when none was recorded: a sent Pix created before this rail kept its channel, or a received Pix whose channel was unknown." enum: - CPM - CSM examples: - CPM type: string createdAt: description: Payment creation timestamp (RFC 3339, UTC). examples: - "2025-03-07T14:30:00Z" type: string creditorISPB: description: ISPB (8 digits or uppercase letters) of the creditor (payee) participant. examples: - "87654321" type: string direction: description: "Which side of the rail the Pix is on: sent (the client ordered it; the counterparty is creditorISPB) or received (BACEN delivered it; the counterparty is originatorISPB)." enum: - sent - received examples: - sent type: string endToEndId: description: SPI end-to-end identifier (E{ISPB}{YYYYMMDD}{uniqueID}, 32 chars). examples: - E1234567820250307ABCDEFGHIJKLMNO type: string history: description: Ordered list of payment lifecycle events; omitted when not requested. items: $ref: "#/components/schemas/PaymentEventResponse" type: - array - "null" historyDegraded: description: True when the event history could not be fully retrieved and may be incomplete. examples: - false type: boolean historyDegradedReason: description: Explanation for degraded history, present only when historyDegraded is true. examples: - "" type: string id: description: Server-assigned payment identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string originatorISPB: description: ISPB (8 digits or uppercase letters) of the originating participant. examples: - "12345678" type: string returnReason: description: BACEN return reason code, present only when the payment was returned. examples: - BE08 type: string status: description: "Current payment lifecycle status: PENDING, SENT, ACCEPTED, COMPLETED (settled), REJECTED, FAILED, RETURN_PENDING or RETURNED." examples: - COMPLETED type: string updatedAt: description: Timestamp of the last status change (RFC 3339, UTC). examples: - "2025-03-07T14:30:05Z" type: string required: - id - endToEndId - amount - direction - status - createdAt - updatedAt type: object PaymentWithdrawalRequest: additionalProperties: false properties: agentModality: description: "Modalidade do agente de saque (modalidadeAgente): AGTEC commercial establishment, AGTOT other legal entity or correspondent, AGFSS the withdrawal facilitator itself (map the QR Code's AGPSS to AGFSS). A troco is AGTEC or AGTOT; a saque read from a static QR Code is AGTEC." enum: - AGTEC - AGTOT - AGFSS examples: - AGTEC type: string facilitatorISPB: description: "ISPB of the Pix Saque or Pix Troco facilitator (facilitadorDoServicoDeSaque): the QR Code's fss or prestadorDoServicoDeSaque. 8 characters [0-9A-Z] (XSD ISPBType)." examples: - "01234567" pattern: ^[0-9A-Z]{8}$ type: string purchaseAmount: description: Purchase part of a Pix Troco (VLCP), below amount; the rest of amount is the cash (VLDN). Required on GSCB, refused on OTHR, where the whole amount is cash. examples: - "100.00" pattern: ^[0-9]{1,10}\.[0-9]{2}$ type: string required: - agentModality - facilitatorISPB type: object PixAwaitingFundingItem: additionalProperties: false properties: endToEndId: description: EndToEndID of the arriving Pix; the identifier a funding decision names it by. examples: - E1234567820260220123456789012350 type: string horario: description: Instant this rail recorded the arriving Pix (RFC 3339, UTC). examples: - "2026-07-31T14:30:00Z" type: string pagadorISPB: description: ISPB (8 digits or uppercase letters) of the participant that sent the Pix (participanteDoUsuarioPagador), verbatim from the pacs.008 DbtrAgt. Omitted when the arriving message did not carry it — never reconstructed from the endToEndId. examples: - "87654321" type: string txid: description: Transaction id the arriving pacs.008 carried, when present. examples: - cobv001 type: string valor: description: Amount the arriving Pix carries, verbatim from the pacs.008 (BRL, scale 2). examples: - "10.00" type: string required: - endToEndId - valor - horario type: object PixAwaitingFundingResponse: additionalProperties: false properties: items: description: Arriving Pix awaiting a funding decision, oldest arrival last. items: $ref: "#/components/schemas/PixAwaitingFundingItem" type: array limit: description: Effective page size applied to this response. format: int64 type: integer total: description: Total number of parked Pix awaiting a funding decision, across all pages. format: int64 type: integer required: - items - total - limit type: object PixCertificateAuditWire: additionalProperties: false properties: action: description: Audited verb. enum: - UPLOAD - DEACTIVATE examples: - UPLOAD type: string actor: description: Subject who performed the action. examples: - operator-1 type: string at: description: Action timestamp (RFC3339 UTC). examples: - "2026-06-21T18:30:00Z" format: date-time type: string reason: description: Optional operator rationale. examples: - quarterly rotation type: string required: - action - at type: object PixCertificateDetailResponse: additionalProperties: false properties: actions: description: Append-only audit trail, newest first. items: $ref: "#/components/schemas/PixCertificateAuditWire" type: array certificate: $ref: "#/components/schemas/PixCertificateWire" description: The certificate's structured public metadata. required: - certificate - actions type: object PixCertificateListResponse: additionalProperties: false properties: items: description: Managed Pix certificates, newest first. items: $ref: "#/components/schemas/PixCertificateWire" type: array required: - items type: object PixCertificateWire: additionalProperties: false properties: activationDate: description: Certificate NotBefore (RFC3339 UTC); null when unknown. examples: - "2026-01-01T00:00:00Z" format: date-time type: string certType: description: Role the certificate serves. enum: - PIC - PIA - UriQRCode - JwsQRCode - CERTPIC - SIGNING examples: - PIC type: string commonName: description: Parsed Subject CN. examples: - spi.example.br type: string createdAt: description: Row creation timestamp (RFC3339 UTC). examples: - "2026-06-21T18:30:00Z" format: date-time type: string createdBy: description: Subject who uploaded the certificate. examples: - operator-1 type: string custody: description: "Where the matching private key lives: LOCAL keystore file or HSM/CloudHSM (KMIP). HSM keys never cross this boundary." enum: - LOCAL - HSM examples: - LOCAL type: string expiryDate: description: Certificate NotAfter (RFC3339 UTC); null when unknown. examples: - "2027-01-01T00:00:00Z" format: date-time type: string fileName: description: Operator-supplied upload file name. examples: - pic.cer type: string fingerprint: description: SHA-256 of the DER public certificate (hex). Content-addressable identity; never key material. examples: - 9f2c...e1 type: string id: description: Certificate row UUID. examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string origin: description: Who issued the certificate. enum: - PSP - BACEN examples: - BACEN type: string serial: description: Certificate serial number (hex). examples: - 00A1B2C3 type: string status: description: Lifecycle status. enum: - ACTIVE - DEACTIVATED - EXPIRED examples: - ACTIVE type: string updatedAt: description: Last update timestamp (RFC3339 UTC). examples: - "2026-06-21T18:30:00Z" format: date-time type: string required: - id - certType - origin - fingerprint - serial - status - custody - createdAt - updatedAt type: object PixConsultadosResponse: additionalProperties: false properties: parametros: $ref: "#/components/schemas/ParametrosConsultaPix" description: Echoed query parameters plus pagination metadata. pix: description: Received Pix matching the filters, each with its devoluções. items: $ref: "#/components/schemas/PixResponse" type: array required: - parametros - pix type: object PixResponse: additionalProperties: false properties: devolucoes: description: Returns issued against this Pix; omitted when none. items: $ref: "#/components/schemas/DevolucaoResponse" type: array endToEndId: description: SPI end-to-end identifier (32 chars). type: string horario: description: Settlement timestamp (RFC 3339, UTC). type: string valor: description: Received amount as a decimal string, scale 2 (BRL). type: string required: - endToEndId - valor - horario type: object ProcessInboundRequest: additionalProperties: false properties: antifraudDecision: description: "Set to true to declare that the refusal is the decision of the client's antifraud system. Valid only with refusalReason FRAD on an endToEndId: any other combination with true — another refusalReason, none, authorized, the funding evidence, or a returnId — is refused (422). refusalReason is trimmed and compared case-insensitively (\"frad\" and \" FRAD \" count as FRAD; whitespace-only counts as empty). false or absent states nothing." examples: - true type: boolean authorized: description: "Set to true to declare that the caller's own system authorized the credit. The Pix is accepted exactly as an assessed approval is and settles only on the SPI's ACCC, and this rail assesses nothing: the caller decided, and it measured no balance for this rail to re-evaluate. Supply it INSTEAD of the three evidence fields and INSTEAD of refusalReason, never alongside either. false is not a disposition and states nothing; a refusal travels as refusalReason." examples: - true type: boolean availableBalance: description: Receiver's available balance as a non-negative decimal string (BRL). "0.00" is valid and means no balance. Required together with availableLimit and riskScore, and only when neither authorized nor refusalReason is supplied. examples: - "50000.00" pattern: ^[0-9]{1,16}(\.[0-9]{1,2})?$ type: string availableLimit: description: Receiver's available credit limit as a non-negative decimal string (BRL). "0.00" is valid and means no limit. Required together with availableBalance and riskScore, and only when neither authorized nor refusalReason is supplied. examples: - "100000.00" pattern: ^[0-9]{1,16}(\.[0-9]{1,2})?$ type: string endToEndId: description: EndToEndID of the parked inbound Pix, as returned by listPixAwaitingFunding (E{ISPB}{YYYYMMDD}{HHMM}{uniqueID}, 32 characters). Shaped exactly as the pacs.008 XSD types EndToEndIdType — the participant segment admits [0-9A-Z] and the unique tail is case-sensitive and may be lower-case — so this surface never refuses an id the wire that parked the Pix accepts. Supply it INSTEAD of returnId, never alongside it. examples: - E1234567820260220123456789012350 pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string refusalReason: description: "Refusal the caller's own system measured, which concludes the Pix REJECTED without this rail assessing anything. Supply it INSTEAD of the three evidence fields and INSTEAD of authorized, never alongside either. It is a pacs.002 ExternalStatusReason1Code: AC03 when the key resolves to nothing or the account does not exist, AC06 when the account exists and cannot receive, AC07 when the account is closed, BE01 when the receiver CPF/CNPJ is not the account holder's, and AG01 when your institution judges the account to exploit illegal fixed-odds betting — AG01 only under BACEN catalogue kit 5.13.2, which defines it (under 5.12.1 it is answered DS04). Any other value is recorded as CREDIT_DECLINED_BY_CLIENT (DS04), because this rail states no cause it did not establish, EXCEPT FRAD together with antifraudDecision true, which is recorded and answered as FRAD (FRAD without the mark stays DS04). For a devolução (returnId) it is one of AC03, AC06, AC07 (account closed), BE01 or AM09 (the amount exceeds what is left to return), and any other value is refused (422)." examples: - AC03 maxLength: 64 minLength: 1 type: string returnId: description: RtrId of a parked devolução a third party sent against a Pix your client sent, as spi.payment.return_received announced it (pacs.004 RtrIdType, 32 characters). Supply it INSTEAD of endToEndId, never alongside it. A devolução is decided with authorized or refusalReason only; the funding evidence does not apply to it. examples: - D1234567820260220123456789012350 pattern: ^D[0-9A-Z]{8}[0-9]{4}[0-1][0-9][0-3][0-9][0-2][0-9][0-5][0-9][a-zA-Z0-9]{11}$ type: string riskScore: description: Risk score (0-100) for the inbound payment; higher values indicate greater risk. Required together with availableBalance and availableLimit, and only when neither authorized nor refusalReason is supplied. examples: - 15 format: int64 maximum: 100 minimum: 0 type: integer type: object ProcessInboundResponse: additionalProperties: false properties: decision: description: Inbound processing outcome (e.g. ACCEPT, REJECT). examples: - ACCEPT type: string events: description: Lifecycle event types emitted while processing the inbound message. items: type: string type: - array - "null" messageType: description: ISO 20022 message type of the processed inbound message. examples: - pacs.008 type: string paymentId: description: Local payment identifier (UUID) created or matched for the inbound message, when known. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string reason: description: Reason code explaining the decision, present only on rejection or deferral. examples: - "" type: string replayed: description: True when the inbound message was a duplicate already processed (idempotent replay). examples: - false type: boolean responseCode: description: "ISO 20022 status code the rail answers BACEN with: ACSP when the Pix is accepted, RJCT when it is refused, PDNG while it stays parked." examples: - ACSP type: string settled: description: "Always false on a decision: an accepted Pix settles only when the SPI confirms it with ACCC, which spi.payment.settled announces." examples: - false type: boolean required: - messageType - decision - responseCode - settled - replayed type: object RailCapabilitiesResponse: additionalProperties: false properties: hasCrashWindowRecovery: description: True only for SPB (evidence-first crash-window recovery). type: boolean hasDeadlineExpiry: description: True when the rail detects operations past a deadline (detection only; terminalization is operator-driven, never automatic). type: boolean hasDeadlineSweep: description: True when a background sweep re-attempts/ages stuck rows. type: boolean hasDlqReplay: description: True when the rail exposes an operator DLQ list/replay surface. type: boolean hasInboundStuckDetection: description: True when the rail detects inbound messages stuck mid-processing. type: boolean rail: description: Rail this manifest describes. examples: - spi type: string replayNowWired: description: True when an operator REPLAY actually re-sends stored bytes. type: boolean supportedVerbs: description: Closed set of verbs this rail can ever offer on any row. items: enum: - ACKNOWLEDGE - INVESTIGATE - DISMISS - RESOLVE - RETRY - REPLAY - REDRIVE - RESUBMIT - MANUAL_RESOLUTION - RECONCILE_WITH_BACEN type: string type: array required: - rail - supportedVerbs - hasCrashWindowRecovery - hasDeadlineSweep - hasDlqReplay - hasInboundStuckDetection - hasDeadlineExpiry - replayNowWired type: object ReceivedPixPIIFilters: additionalProperties: false properties: cnpj: description: Optional payer CNPJ filter ([0-9A-Z]{12}[0-9]{2} — the BACEN alphanumeric-CNPJ PICnpj facet); mutually exclusive with cpf. pattern: ^[0-9A-Z]{12}[0-9]{2}$ type: string cpf: description: Optional payer CPF filter; mutually exclusive with cnpj. pattern: ^\d{11}$ type: string type: object RegisterResponsiblesRequest: additionalProperties: false properties: director: $ref: "#/components/schemas/ResponsibleDirectorRequest" description: Statutory director block (DIRETORPSP) directorCpf: description: Director's CPF, exactly 11 digits, no punctuation (BACEN CpfType). examples: - "11111111111" pattern: ^[0-9]{11}$ type: string keyword: description: "BACEN-assigned keyword (palavra-chave) authorising the registration: exactly 8 alphanumeric characters (BACEN PalavraChave)." examples: - XXPOHH88 pattern: ^[a-zA-Z0-9]{8}$ type: string pspContact: $ref: "#/components/schemas/ResponsibleContactRequest" description: PSP operational contact block (CONTATOPSP) required: - pspContact - director - keyword - directorCpf type: object RegisterResponsiblesResponse: additionalProperties: false properties: correlationId: description: reda.022 AppHdr BizMsgIdr the inbound reda.016 status advice must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted to BACEN SPI examples: - reda.022.spi.1.4 type: string operationId: description: UUID of the recorded PARTICIPANT_ADMINISTRATION operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - state type: object RegulatoryArchiveItemWire: additionalProperties: false properties: archivedAt: description: When the item was archived (RFC3339 UTC). format: date-time type: string bodySha256: description: "SHA-256 of the archived body: the signed envelope's hash the rail records on its messages, or a certificate's fingerprint." type: string endToEndId: description: The DICT PI-EndToEndId. type: string exchangeId: description: "The exchange the item belongs to: a sent message and BACEN's answer, or a DICT request and its answer, share it." format: uuid type: string id: description: The item's index id. format: uuid type: string kind: description: What the item is. enum: - ICOM_SENT_REQUEST - ICOM_SENT_RESPONSE - ICOM_RECEIVED - DICT_REQUEST - DICT_RESPONSE - CERTIFICATE type: string messageType: description: The ISO 20022 MsgDefIdr of an ICOM envelope, or the DICT §14 policy of a DICT exchange. type: string record: $ref: "#/components/schemas/RegulatoryArchiveRecordWire" description: The exchange leg as it travelled. resourceId: description: The ICOM PI-ResourceId. type: string retainUntil: description: Nothing deletes the item before this instant (RFC3339 UTC). format: date-time type: string retentionClass: description: The Manual de Segurança v6.00 cap. 7 row the item is kept under. enum: - ICOM_10Y - DICT_QUERY_2Y - DICT_WRITE_10Y - INCIDENT_10Y - CERTIFICATE_10Y type: string required: - id - exchangeId - kind - retentionClass - bodySha256 - archivedAt - retainUntil - record type: object RegulatoryArchiveRecordWire: additionalProperties: false properties: body: contentEncoding: base64 description: "The body byte for byte, base64-encoded: the signed XML (decoded from any transport compression), or a certificate's DER." type: string headers: additionalProperties: items: type: string type: - array - "null" description: The HTTP headers that travelled with the body. type: object method: description: The request method, on a request leg. type: string statusCode: description: The answer's HTTP status, on a response leg. format: int64 type: integer target: description: The request target, on a request leg. type: string required: - body type: object ReleaseReservationRequest: additionalProperties: false properties: bacenConfirmedNonReceipt: description: "The operator's assertion that BACEN confirmed the message never arrived. False is invalid (422), refused before the reservation is read: releasing a message that may be at BACEN would let a corrected retry double-send it." type: boolean messageId: description: The MsgId the operator inspected (the emission's DISPATCH evidence) and confirmed with BACEN. A reservation under any other MsgId is refused (409). maxLength: 64 minLength: 1 type: string messageType: description: The message whose kept reservation is released. enum: - pain.009 - pain.011 - pain.012 - pain.013 - camt.055 type: string reason: description: Operator justification, recorded as OPERATOR evidence on the operation with who released and the assertion. maxLength: 512 minLength: 1 type: string required: - messageType - messageId - bacenConfirmedNonReceipt - reason type: object ReleaseStuckReplyRequest: additionalProperties: false properties: bacenConfirmedNonReceipt: description: "The operator's assertion that BACEN confirmed messageId never arrived. False is invalid (422), refused before the reply is read: releasing a reply that may be at BACEN would let a resend double-send it." type: boolean messageId: description: The MsgId the operator inspected and confirmed with BACEN. A reply under any other MsgId is refused (409). maxLength: 64 minLength: 1 type: string messageType: description: The reply to release. enum: - pain.014 - camt.029 type: string reason: description: Operator justification, recorded as OPERATOR evidence on the operation with who released and the assertion. maxLength: 512 minLength: 1 type: string required: - messageType - messageId - bacenConfirmedNonReceipt - reason type: object ReleasedReservationWire: additionalProperties: false properties: lifecycleState: description: "The lifecycle state it was returned to: the one it was reserved from, from which a corrected message can be sent." examples: - PENDING_CONFIRMATION type: string messageId: description: The MsgId the released reservation was taken under. examples: - M12345678202610221100abcdefghijk type: string messageType: description: The message whose reservation was released. examples: - pain.012 type: string operationId: description: The operation whose lifecycle was released. format: uuid type: string operationState: description: The operation's state after the release. A released pain.012's operator case returns to AWAITING_RESPONSE with no verdict owed. examples: - AWAITING_RESPONSE type: string releasedState: description: The lifecycle state the message had reserved. examples: - ACTIVE type: string required: - operationId - messageType - messageId - releasedState - lifecycleState - operationState type: object ReplayParkedICOMMessageWire: additionalProperties: false properties: attempts: description: The message's attempt count after this replay. examples: - 6 format: int64 type: integer channel: description: The ICOM channel the replay was forwarded through. enum: - CPM - CSM examples: - CPM type: string resourceId: description: The replayed message's PI-ResourceId. examples: - c7e3d74bca8e type: string state: description: CLOSED when the rail boundary reached a terminal outcome. PARKED when it refused again — the message is kept, never discarded. enum: - PARKED - CLOSED examples: - CLOSED type: string statusCode: description: The rail boundary's HTTP status. Absent when the forward never completed. examples: - 200 format: int64 type: integer terminal: description: Whether the rail boundary reached a final verdict on this replay. examples: - true type: boolean required: - resourceId - state - terminal - attempts - channel type: object ResponsibleContactRequest: additionalProperties: false properties: email: description: PSP operational contact email address, at most 77 characters (BACEN EmailType). examples: - monitoramento@psp.example.com.br maxLength: 77 pattern: ^(.+)@(.+)$ type: string fax: description: PSP operational contact fax number examples: - +55-1177777777 type: string mobile: description: PSP operational contact mobile number examples: - +55-1166666666 type: string phone: description: "PSP operational contact landline (CONTATOPSP): a plus sign, 1 to 3 country-code digits, a hyphen, then the subscriber digits, at most 30 characters." examples: - +55-1133333333 maxLength: 30 pattern: ^\+[0-9]{1,3}-[0-9]+$ type: string required: - phone - email type: object ResponsibleDirectorRequest: additionalProperties: false properties: email: description: Statutory director email address, at most 77 characters (BACEN EmailType). examples: - diretor@psp.example.com.br maxLength: 77 pattern: ^(.+)@(.+)$ type: string mobile: description: Statutory director mobile number examples: - +55-1155555555 type: string name: description: Full name of the statutory director (DIRETORPSP), 1 to 140 characters (BACEN Max140Text). The builder additionally counts bytes, so an accented name near the ceiling can still be refused there. examples: - Fulano Diretor de Tal maxLength: 140 minLength: 1 type: string phone: description: "Statutory director landline: a plus sign, 1 to 3 country-code digits, a hyphen, then the subscriber digits, at most 30 characters." examples: - +55-1144444444 maxLength: 30 pattern: ^\+[0-9]{1,3}-[0-9]+$ type: string required: - name - phone - email type: object ResponsiblesContactWire: additionalProperties: false properties: email: description: PSP operational contact email (CONTATOPSP). examples: - monitoramento@psp.example.com.br type: string fax: description: PSP operational contact fax number. examples: - +55-1177777777 type: string mobile: description: PSP operational contact mobile number. examples: - +55-1166666666 type: string phone: description: PSP operational contact landline. examples: - +55-1133333333 type: string type: object ResponsiblesDirectorWire: additionalProperties: false properties: cpf: description: Statutory director CPF (11 digits, no punctuation). examples: - "11111111111" type: string email: description: Statutory director email. examples: - diretor@psp.example.com.br type: string mobile: description: Statutory director mobile number. examples: - +55-1155555555 type: string name: description: Statutory director full name (DIRETORPSP). examples: - Fulano Diretor de Tal type: string phone: description: Statutory director landline. examples: - +55-1144444444 type: string type: object ResponsiblesWire: additionalProperties: false properties: director: $ref: "#/components/schemas/ResponsiblesDirectorWire" description: Statutory director block (DIRETORPSP). palavraChave: description: BACEN 8-alphanumeric audit keyword (regulatory identifier, not a password). Returned verbatim; it is masked on display. examples: - XXPOHH88 type: string participantIspb: description: ISPB (8 digits or uppercase letters) the responsibles belong to. examples: - "12345678" type: string pspContact: $ref: "#/components/schemas/ResponsiblesContactWire" description: PSP operational contact block (CONTATOPSP). recordedAt: description: When this last-known snapshot was written/refreshed (RFC3339 UTC). examples: - "2026-06-21T18:30:00Z" format: date-time type: string source: description: "How the last-known record was established: written at reda.022 submit time, or confirmed by the inbound reda.016 COMP advice." enum: - SUBMITTED - COMP_CONFIRMED examples: - COMP_CONFIRMED type: string required: - participantIspb - pspContact - director - source - recordedAt type: object SPIBalanceSnapshot: additionalProperties: false properties: accountIspb: description: Conta-PI account ISPB (8 digits or uppercase letters), verbatim. examples: - "12345678" type: string amount: description: Balance amount BACEN sent, verbatim as text — never parsed or summed. examples: - "1000000.00" type: string balanceDateTime: description: BACEN balance timestamp, verbatim. examples: - "2026-06-15T10:00:00.000Z" type: string balanceType: description: Raw 4-letter BACEN BalanceTypeCode, verbatim (it is mapped to meaning). examples: - SADP type: string correlationId: description: camt.060 correlation id the balance answers. examples: - M12345678Abc123 type: string creditDebitIndicator: description: Credit/debit indicator, verbatim. examples: - CRDT type: string currency: description: Currency, verbatim. examples: - BRL type: string receivedAt: description: When the balance was projected (RFC 3339 UTC). examples: - "2026-06-15T10:00:01Z" type: string required: - correlationId - accountIspb - balanceType - amount - currency - creditDebitIndicator - receivedAt type: object SPIBalancesResponse: additionalProperties: false properties: items: description: Conta-PI balance snapshots BACEN sent in the window (camt.053), projected verbatim, newest first. items: $ref: "#/components/schemas/SPIBalanceSnapshot" type: array window: $ref: "#/components/schemas/SPIReportWindowResponse" description: Echo of the resolved report window. required: - items - window type: object SPIExtractSummary: additionalProperties: false properties: accountIspb: description: Conta-PI account ISPB (8 digits or uppercase letters), verbatim. examples: - "99999010" type: string correlationId: description: camt.060 correlation id the extrato answers. examples: - M12345678Abc123 type: string countsMatch: description: "COUNT-recon FLAG: declared == parsed. A mismatch is operator-reviewable, never fatal." examples: - true type: boolean declaredEntryCount: description: camt.052 NbOfNtries — the declared record COUNT. examples: - 16 format: int64 type: integer fileName: description: AddtlRptInf file handle (== SHA-256 of the file content). type: string integrityVerified: description: True when sha256(fetched file) == AddtlRptInf. examples: - true type: boolean parsedEntryCount: description: RCO data rows parsed. A COUNT, never money. examples: - 16 format: int64 type: integer receivedAt: description: When the extrato was projected (RFC 3339 UTC). examples: - "2026-06-15T10:00:01Z" type: string reportKind: description: "Detected RCO shape: DEMONST_RCO / TOTAL_RCO / UNKNOWN." examples: - DEMONST_RCO type: string required: - correlationId - integrityVerified - declaredEntryCount - parsedEntryCount - countsMatch - receivedAt type: object SPIExtractsResponse: additionalProperties: false properties: items: description: Conta-PI extrato (camt.052/RCO) rows received in the window with integrity flags, newest first. Entries are not inlined. items: $ref: "#/components/schemas/SPIExtractSummary" type: array window: $ref: "#/components/schemas/SPIReportWindowResponse" description: Echo of the resolved report window. required: - items - window type: object SPIRejectedResponse: additionalProperties: false properties: items: description: One page of rejected payments, newest first. items: $ref: "#/components/schemas/SPIRejectedRow" type: array nextCursor: description: Opaque cursor for the next page; absent when exhausted (its absence signals end-of-list). type: string reasonRetained: description: Always false — the detailed reject reason is not retained; the report carries status + business key only. examples: - false type: boolean totalCount: description: Total rejected payments in the window (COUNT). examples: - 7 format: int64 type: integer window: $ref: "#/components/schemas/SPIReportWindowResponse" description: Echo of the resolved report window. required: - totalCount - reasonRetained - items - window type: object SPIRejectedRow: additionalProperties: false properties: createdAt: description: Row creation timestamp (RFC 3339 UTC). examples: - "2026-06-01T12:30:00Z" type: string endToEndId: description: Payment EndToEndID (business key). examples: - E12345678202606011230abcdef01234567 type: string status: description: "Terminal-rejected status: REJECTED / FAILED / RETURN_PENDING." examples: - REJECTED type: string updatedAt: description: Last status-change timestamp (RFC 3339 UTC). examples: - "2026-06-01T12:31:00Z" type: string required: - endToEndId - status - createdAt type: object SPIReportWindowResponse: additionalProperties: false properties: fromDate: description: Inclusive window start (UTC). examples: - "2026-06-01" type: string toDate: description: Inclusive window end (UTC). examples: - "2026-06-30" type: string required: - fromDate - toDate type: object SPIVolumetriaBucket: additionalProperties: false properties: count: description: Record COUNT for this (dimension, day) bucket. examples: - 42 format: int64 type: integer day: description: UTC day bucket (YYYY-MM-DD). examples: - "2026-06-01" type: string dimension: description: The message type, status, or participant ISPB for this bucket (per groupBy). examples: - pacs.008 type: string required: - dimension - day - count type: object SPIVolumetriaResponse: additionalProperties: false properties: buckets: description: COUNT(*) buckets, oldest day first. items: $ref: "#/components/schemas/SPIVolumetriaBucket" type: array countOnly: description: Always true — SPI volumetria is COUNT-only; the payments record persists no amount. examples: - true type: boolean groupBy: description: Resolved grouping axis. examples: - messageType type: string window: $ref: "#/components/schemas/SPIReportWindowResponse" description: Echo of the resolved report window. required: - groupBy - countOnly - buckets - window type: object ScheduleEmissionResponse: additionalProperties: false properties: correlationId: description: Emission AppHdr BizMsgIdr the inbound response must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted (pain.013 or pain.014) examples: - pain.013.spi.2.2 type: string operationId: description: UUID of the recorded schedule operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string scheduleId: description: Schedule identifier the emission acted on examples: - SCHEDULE2026Ref001 type: string scheduleState: description: Schedule lifecycle state after emission examples: - SCHEDULED type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - scheduleId - scheduleState - state type: object ScheduleListResponse: additionalProperties: false properties: correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: Schedule operations, newest first. items: $ref: "#/components/schemas/ScheduleReadModelResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer offset: description: Zero-based offset of the first item in this page. format: int64 type: integer total: description: Total number of schedule operations matching the filters (COUNT over the same predicate, excluding limit/offset); stable across pages. format: int64 type: integer required: - items - total - limit - offset type: object ScheduleReadModelResponse: additionalProperties: false properties: cancellationReceived: description: "True while a camt.055 this installation received for the schedule awaits the camt.029 it sends: the one that parked the schedule cancellation-pending (scheduleState SCHEDULED_CANCELLATION_PENDING or CANCELLATION_PENDING), or one that parked nothing (it crossed this installation's own camt.055, or the schedule owes this installation's own pain.014 RJCT and stays SCHEDULED). A camt.055 naming a retry attempt's EndToEndId counts on that attempt's row. False once the camt.029 is sent, and when only this installation's own camt.055 holds the schedule." examples: - true type: boolean correlationId: description: Persisted correlation handle (client_operations.business_key). examples: - schedule|SCHEDULE2026Ref001 type: string createdAt: description: Operation creation timestamp (RFC3339 UTC). examples: - "2026-06-10T15:00:00Z" format: date-time type: string operationId: description: UUID of the recorded schedule operation (client_operations.id). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string operationState: description: Operation lifecycle state (client_operations.state). examples: - AWAITING_RESPONSE type: string ownMessageRefused: description: "True while BACEN refused (admi.002) a message this installation sent for the schedule and the operator owes its next step: its own camt.055, until the operator releases its reservation; its pain.014, or the camt.029 RJCR answering a received camt.055, until resent within the reply's deadline (2 hours after the pain.013, 12 hours after the camt.055). False otherwise." examples: - false type: boolean refusalSweepPending: description: "True while this installation owes the received pain.013 its own pain.014 RJCT (the mandate is unknown or not confirmed) and the refusal sweep still sends it within the 2 hours: no operator answer is due. False once the sweep hands it to the operator (operationState REQUIRES_OPERATOR_ACTION), and on every other schedule." examples: - false type: boolean refusedCancellationMessageId: description: "The MsgId of this installation's own camt.055 that BACEN refused (admi.002) while it holds the schedule cancellation-pending: the reservation the operator releases (POST /api/v1/spi/operations/{operationId}/reservations/release) once BACEN confirms it never arrived. Always the first attempt's MsgId, which a resend never replaces. Empty otherwise." examples: - "" type: string scheduleId: description: Schedule (agendamento) identifier the operation tracks. examples: - SCHEDULE2026Ref001 type: string scheduleState: description: Schedule lifecycle state (metadata pain_lifecycle_state); empty before any lifecycle transition. examples: - SCHEDULED type: string side: description: "The PSP this installation is for the schedule (metadata pain_schedule_side): PAYER when it received the pain.013 and answers it with a pain.014, RECEIVER when it sent it; empty before the schedule opens." examples: - PAYER type: string updatedAt: description: Operation last-update timestamp (RFC3339 UTC). examples: - "2026-06-10T15:05:00Z" format: date-time type: string required: - operationId - scheduleId - scheduleState - operationState - correlationId - side - cancellationReceived - ownMessageRefused - refusalSweepPending - refusedCancellationMessageId - createdAt - updatedAt type: object SettlementReportPartyRequest: additionalProperties: false properties: accountId: description: Party account number at the holding institution, 1 to 20 upper-case alphanumeric characters (BACEN ContaUsuarioType) examples: - "1234567" pattern: ^[0-9A-Z]{1,20}$ type: string accountIssuer: description: Branch (agência) code issuing the account examples: - "0001" type: string accountType: description: "ISO 20022 cash account type: CACC (current), OTHR (other), SLRY (salary), SVGS (savings) or TRAN (transactional)" enum: - CACC - OTHR - SLRY - SVGS - TRAN examples: - CACC type: string taxId: description: "Party tax identifier, no punctuation: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (BACEN PICpfCnpj)" examples: - "12345678901" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string required: - taxId - accountId - accountType type: object SettlementReportResponse: additionalProperties: false properties: correlationId: description: trck.002 AppHdr BizMsgIdr the inbound camt.025 receipt must reference examples: - M12345678Abc123Def456Ghi789Jkl0 type: string messageType: description: ISO 20022 message type emitted to BACEN SPI examples: - trck.002.spi.1.1 type: string operationId: description: UUID of the recorded TRACKING_REPORT operation examples: - 550e8400-e29b-41d4-a716-446655440000 type: string state: description: Operation lifecycle state after emission examples: - AWAITING_RESPONSE type: string required: - operationId - correlationId - messageType - state type: object SettlementReportTransactionRequest: additionalProperties: false properties: amount: description: Settled amount in BRL as a decimal string with exactly two fraction digits. The 0.01..9999999999.99 range is checked by the amount domain, which a string schema cannot express. examples: - "150.25" pattern: ^[0-9]{1,10}\.[0-9]{2}$ type: string creditor: $ref: "#/components/schemas/SettlementReportPartyRequest" description: Creditor (payee) party of the settled transaction creditorAccountProxy: description: Optional Pix key (proxy) addressing the creditor account examples: - user@example.com type: string creditorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the creditor's institution examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string debtor: $ref: "#/components/schemas/SettlementReportPartyRequest" description: Debtor (payer) party of the settled transaction debtorAgentIspb: description: 8-character ISPB (digits or uppercase letters) of the debtor's institution examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string endToEndId: description: 32-character Pix end-to-end identifier of the settled transaction (BACEN EndToEndIdType). The 11-character tail is case-sensitive and is sent exactly as given; the date and minute components are additionally parsed as a real instant. examples: - E1234567820260220123456789012345 pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string instructionId: description: Optional instruction identifier of the settled transaction examples: - D1234567820260220123456789012345 type: string localInstrument: description: BACEN local-instrument code classifying the Pix initiation channel (BACEN PrtryLclInstrmCode) enum: - APDN - APES - AUTO - DICT - INIC - MANU - QRDN - QRES examples: - MANU type: string requestedExecutionAt: description: The instant the transaction settled in your system (DataHoraDaTransacao, ReqdExctnDt/DtTm), RFC3339 UTC. BACEN measures the Manual de Tempos §4.5.1 indicator (P99 300 s) as the report's creation instant minus this one. Refused with 422 when later than the report's creation instant by more than 2 s, the allowance for your servers' clocks against this rail's; within it, written unchanged. A transaction reported more than 30 days after it settled is still sent, and it raises the brspi_trck002_late_transactions_total alarm. examples: - "2026-06-10T12:00:00.000Z" format: date-time type: string scenario: description: MED 2.0 internal-settlement (book transfer) scenario code enum: - BOK1 - BOK2 examples: - BOK1 type: string required: - endToEndId - localInstrument - scenario - amount - requestedExecutionAt - debtor - debtorAgentIspb - creditor - creditorAgentIspb type: object SpiAccountBalanceItem: additionalProperties: false properties: accountIspb: description: ISPB (8 digits or uppercase letters) of the Conta PI account the balance belongs to (Stmt/Acct/Id), verbatim examples: - "12345678" type: string amount: description: Balance amount BACEN sent (Bal/Amt), verbatim as text — never parsed or summed examples: - "1000000.00" type: string balanceDateTime: description: BACEN balance timestamp (Bal/Dt/DtTm), verbatim examples: - "2026-06-15T10:00:00.000Z" type: string balanceType: description: Raw BACEN BalanceTypeCode (PSSR/REMN/SABK/SADP/VSME/VVSR), verbatim — the code is mapped to its meaning examples: - SADP type: string creditDebitIndicator: description: Credit/debit indicator (Bal/CdtDbtInd), verbatim (CRDT) examples: - CRDT type: string currency: description: Currency of the amount (Bal/Amt Ccy), verbatim (BRL) examples: - BRL type: string required: - accountIspb - balanceType - amount - currency - creditDebitIndicator type: object SpiAccountBalanceResponse: additionalProperties: false properties: balances: description: Conta PI balances BACEN sent in the camt.053, projected verbatim. Empty while PENDING items: $ref: "#/components/schemas/SpiAccountBalanceItem" type: array correlationId: description: camt.060 AppHdr BizMsgIdr correlating the request to its camt.053 balance response examples: - M12345678Abc123Def456Ghi789Jkl0 type: string receivedAt: description: RFC3339 UTC freshness timestamp the balance set was projected. Empty while PENDING examples: - "2026-06-15T10:00:01Z" format: date-time type: string status: description: PENDING until the inbound camt.053 balance arrives; ANSWERED once it has been projected examples: - ANSWERED type: string required: - correlationId - status - balances type: object SpiAccountExtractEntryItem: additionalProperties: false properties: columns: additionalProperties: type: string description: RCO row cells keyed by BACEN's exact CSV column name, verbatim. The shape depends on reportKind (DEMONST_RCO / TOTAL_RCO) type: object lineNumber: description: 1-based data-row order within the RCO file examples: - 1 format: int64 type: integer required: - lineNumber - columns type: object SpiAccountExtractResponse: additionalProperties: false properties: accountIspb: description: ISPB (8 digits or uppercase letters) of the Conta PI account the extrato addresses (Rpt/Acct/Id), verbatim. Empty while PENDING examples: - "99999010" type: string correlationId: description: camt.060 AppHdr BizMsgIdr correlating the request to its camt.052 extrato response examples: - M12345678Abc123Def456Ghi789Jkl0 type: string countsMatch: description: "COUNT recon FLAG: declaredEntryCount == parsedEntryCount. A mismatch is operator-reviewable, never fatal" examples: - true type: boolean declaredEntryCount: description: camt.052 NbOfNtries (quantidadeLancamentos) — the declared record count examples: - 16 format: int64 type: integer entries: description: RCO lançamentos rows BACEN generated, projected verbatim. Empty while PENDING items: $ref: "#/components/schemas/SpiAccountExtractEntryItem" type: array fileName: description: AddtlRptInf file handle (== SHA-256 of the file content). Empty while PENDING examples: - 0c71ebdc4736bf09a888457750aa22f7c895026afb64b40f8fbd94092c61c19b type: string integrityVerified: description: True when sha256(fetched file) == AddtlRptInf (integrity passed) examples: - true type: boolean parsedEntryCount: description: Number of RCO data rows parsed from the file examples: - 16 format: int64 type: integer receivedAt: description: RFC3339 UTC freshness timestamp the extrato was projected. Empty while PENDING examples: - "2026-06-15T10:00:01Z" format: date-time type: string reportKind: description: "Detected RCO shape: DEMONST_RCO (saque-facilitator demonstrativo), TOTAL_RCO (per-account-pair totals), or UNKNOWN. Empty while PENDING" examples: - DEMONST_RCO type: string status: description: PENDING until the inbound camt.052 extrato is fetched + verified + projected; ANSWERED once it has been persisted examples: - ANSWERED type: string required: - correlationId - status - integrityVerified - declaredEntryCount - parsedEntryCount - countsMatch - entries type: object StructuredOperationResponse: additionalProperties: false properties: createdAt: description: Operation creation timestamp; RFC3339, UTC. examples: - "2030-01-01T00:00:00Z" type: string operationId: description: Server-assigned operation identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string operationType: description: Structured operation type echoed back from the request. examples: - PAYMENT_TRANSFER type: string payloadFingerprint: description: Canonical hash of the payload computed by the domain validator; hex-encoded. examples: - 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef type: string state: description: Initial lifecycle state of the created operation. examples: - PENDING type: string required: - operationId - operationType - state - payloadFingerprint - createdAt type: object StuckOperationViewResponse: additionalProperties: false properties: affordances: description: The ONLY source of operator buttons for this row; a verb the rail cannot perform is absent. items: $ref: "#/components/schemas/OperatorAffordanceResp" type: array age: description: Normalized staleness bucket. examples: - OVER_15_MIN type: string correlation: $ref: "#/components/schemas/CorrelationResponse" description: Protocol identity the row is keyed on (no monetary fields). detail: additionalProperties: {} description: Render-only per-rail drill-down blob; it is rendered but never branched on. type: object disposition: description: What happens if the operator does nothing. examples: - PARKED_AWAITING_OPERATOR type: string rail: description: Rail that owns the row (spb or spi). examples: - spi type: string reason: description: Normalized cause the row needs attention. examples: - DEADLINE_EXPIRED type: string state: description: Canonical operation lifecycle state. examples: - FAILED type: string required: - rail - state - correlation - reason - disposition - affordances type: object StuckPageResponse: additionalProperties: false properties: capabilities: $ref: "#/components/schemas/RailCapabilitiesResponse" description: Rail-level honest capability manifest (returned inline to save a round trip). correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: Stuck-operation rows needing operator attention. items: $ref: "#/components/schemas/StuckOperationViewResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque cursor for the next page; absent when exhausted (its absence signals end-of-list). type: string required: - items - capabilities - limit - correlationId type: object SubmitStuckActionRequest: additionalProperties: false properties: operationRef: description: Row key exactly as the listing returned it in correlation.operationRef. minLength: 1 type: string reason: description: Operator justification, persisted with the outcome. maxLength: 512 minLength: 1 type: string verb: description: Operator intent. Must be one of the verbs the listing offered on THIS row; anything else is refused before the money path is touched. enum: - ACKNOWLEDGE - INVESTIGATE - DISMISS - RESOLVE - RETRY - REPLAY - REDRIVE - RESUBMIT - MANUAL_RESOLUTION - RECONCILE_WITH_BACEN examples: - RECONCILE_WITH_BACEN minLength: 1 type: string required: - operationRef - verb - reason type: object TimelineEventResponse: additionalProperties: false properties: actorId: description: Identifier of the actor that triggered the event, if attributed. type: string actorType: description: "Actor principal class: USER, SERVICE, or SYSTEM." type: string category: description: Event category classifying the kind of timeline entry. type: string createdAt: description: Time the event was persisted; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string evidenceMetadata: additionalProperties: {} description: Optional evidence metadata object attached to EVIDENCE-class events. type: object failureCategory: description: Failure classification for failure-related events. type: string id: description: Timeline event identifier. type: string messageId: description: Rail message identifier associated with the event, if any. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string newState: description: Operation state set by this event, for state-change entries. type: string occurredAt: description: Time the event occurred; RFC3339, UTC. examples: - "2026-06-14T12:00:00Z" type: string operationId: description: Operation this timeline event belongs to. type: string railReference: description: External rail reference (e.g. SPI end-to-end id) tied to the event. examples: - E1234567820260614ABCDEFGHIJKLMNO type: string reason: description: Free-form reason text associated with the event. type: string reasonCode: description: Stable machine-readable reason code associated with the event. type: string source: description: Origin of the event (e.g. the pipeline stage or rail that produced it). type: string summary: description: Human-readable summary of the event. type: string required: - id - category - operationId - occurredAt type: object TimelinePageResponse: additionalProperties: false properties: items: description: Page of timeline events for the operation, oldest-to-newest within the page. items: $ref: "#/components/schemas/TimelineEventResponse" type: array limit: description: Page size requested for this response (default 50, max 200). format: int64 type: integer nextCursor: description: Opaque cursor to fetch the next page; absent on the last page. type: string required: - items - limit type: object UploadPixCertificateRequest: additionalProperties: false properties: certType: description: Role the certificate serves. enum: - PIC - PIA - UriQRCode - JwsQRCode - CERTPIC - SIGNING examples: - PIC type: string fileName: description: Operator-supplied display name for the uploaded file. examples: - pic.cer maxLength: 256 type: string materialBase64: description: Base64-encoded PUBLIC certificate material (.cer; PEM CERTIFICATE block or raw DER). A private-key payload (.p12 / PEM PRIVATE KEY) is rejected fail-closed — the private key never crosses this boundary. examples: - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... type: string origin: description: Who issued the certificate. enum: - PSP - BACEN examples: - BACEN type: string reason: description: Optional operator rationale recorded in the audit trail. examples: - initial import maxLength: 512 type: string required: - certType - origin - materialBase64 type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object VerbOutcomeResponse: additionalProperties: false properties: accepted: description: Whether the rail accepted the verb. False with a 2xx never happens — a refusal is an error status. type: boolean correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string railActionRef: description: Rail-native reference for follow-up. type: string reasonCode: description: Stable machine code for display and telemetry only. type: string requirement: description: "Gating tier the verb resolved to: DIRECT, APPROVAL_REQUIRED, or ADVISORY." examples: - DIRECT type: string resultState: description: Canonical operation state after the verb, when it moved one. type: string required: - accepted - requirement - correlationId type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: 'OpenAPI surface for Lerian SPI: ISO 20022 payment messaging with BACEN over the Brazilian Instant Payment System (Pix/SPI). Covers payments and returns, received Pix and their funding decision, Pix Automático mandates and schedules, inbound message validation and parked inbound messages, Conta PI account reporting, certificates, approvals, evidence, operation recovery, and volumetria/rejected/balance reports.' license: name: Lerian Studio General License title: Lerian SPI API version: 1.0.0 openapi: 3.1.0 paths: /api/v1/spi/account-reports/requests: post: description: "Prerequisite: this is the request step of the account-reporting chain (camt.060 request → camt.052/053/054 result read); the camt.060 request MUST be submitted and correlated first — the camt.05x result is read back only after this request is acknowledged. Builds a camt.060 account-reporting request (BALANCE → camt.053 the SALDO/balance, STATEMENT → camt.052 the entry-list file pointer, ENTRIES → camt.054 the entry detail), records an ACCOUNT_INFORMATION_REQUEST operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface. It always queries the installation's own Conta PI: the camt.060 names the direct participant this rail sends as, never one a caller supplies." operationId: createAccountReportRequest parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateAccountReportRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/AccountReportRequestResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Request a Conta PI account report tags: - Operations - account-reporting x-mint: href: /pt/reference/rails/spi/spi/create-account-report-request /api/v1/spi/account-reports/{correlationId}/balance: get: description: Result step of the account-reporting chain (camt.060 request → camt.053 balance read). Returns the Conta PI SALDO balances BACEN sent in the inbound camt.053, projected verbatim and keyed by the camt.060 correlation id. Reads PENDING until the camt.053 arrives, then ANSWERED with the typed balance set (raw BalanceTypeCode + verbatim amounts) plus a freshness timestamp. Lerian SPI projects the balance BACEN sends; it never computes a position. operationId: getAccountReportBalance parameters: - description: Correlation id returned by createAccountReportRequest (the camt.060 AppHdr BizMsgIdr) in: path name: correlationId required: true schema: description: Correlation id returned by createAccountReportRequest (the camt.060 AppHdr BizMsgIdr) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SpiAccountBalanceResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Read a Conta PI balance (camt.053 result) tags: - Operations - account-reporting x-mint: href: /pt/reference/rails/spi/spi/get-account-report-balance /api/v1/spi/account-reports/{correlationId}/extract: get: description: Result step of the account-reporting chain (camt.060 SOLIC_REL_LANCAMENTO request → camt.052 extrato read). Returns the RCO lançamentos rows BACEN generated on the ARQ rail, fetched + SHA-256-verified + parsed + projected verbatim, keyed by the camt.060 correlation id. Reads PENDING until the camt.052 extrato is received and verified, then ANSWERED with the parsed rows plus the integrity and row-COUNT recon status (declaredEntryCount vs parsedEntryCount). Lerian SPI projects the extrato BACEN sends and reconciles its integrity + row count; it never sums an amount nor computes a position. operationId: getAccountReportExtract parameters: - description: Correlation id returned by createAccountReportRequest (the camt.060 AppHdr BizMsgIdr) in: path name: correlationId required: true schema: description: Correlation id returned by createAccountReportRequest (the camt.060 AppHdr BizMsgIdr) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SpiAccountExtractResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Read a Conta PI extrato (camt.052 RCO lançamentos result) tags: - Operations - account-reporting x-mint: href: /pt/reference/rails/spi/spi/get-account-report-extract /api/v1/spi/approvals: post: description: Creates a new approval_decisions row in REQUESTED state. operationId: createApproval parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateApprovalRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ApprovalResponse" description: Created "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create approval request tags: - Approvals x-mint: href: /pt/reference/rails/spi/spi/create-approval /api/v1/spi/approvals/{approvalId}: get: description: Retrieves an approval_decisions row by id. operationId: getApproval parameters: - description: Approval identifier in: path name: approvalId required: true schema: description: Approval identifier format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApprovalResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get approval tags: - Approvals x-mint: href: /pt/reference/rails/spi/spi/get-approval /api/v1/spi/approvals/{approvalId}/decision: post: description: Records an Approve or Deny decision on an approval_decisions row. operationId: decideApproval parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Approval identifier in: path name: approvalId required: true schema: description: Approval identifier format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DecideApprovalRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApprovalResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Decide approval tags: - Approvals x-mint: href: /pt/reference/rails/spi/spi/decide-approval /api/v1/spi/capabilities: get: description: Returns the public catalog of SPI/Pix capabilities. Every authenticated caller sees the same rows. Supports filtering by operation family, handling mode, direction, and availability. operationId: listSPICapabilities parameters: - description: Exact-match operation family filter (e.g. PACS). explode: false in: query name: operationFamily schema: description: Exact-match operation family filter (e.g. PACS). type: string - description: Canonical HandlingMode filter. explode: false in: query name: handlingMode schema: description: Canonical HandlingMode filter. enum: - PUBLICLY_SUBMITTABLE - RECEIVE_ONLY - LIFECYCLE_RESPONSE - DIAGNOSTIC_ONLY - NOT_APPLICABLE - NOT_READY type: string - description: Direction filter. explode: false in: query name: direction schema: description: Direction filter. enum: - INBOUND - OUTBOUND - BIDIRECTIONAL type: string - description: Filter by availability flag. Absent means no filter. explode: false in: query name: isAvailable schema: description: Filter by availability flag. Absent means no filter. enum: - "true" - "false" type: string - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 100 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CapabilityListResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List SPI capabilities tags: - Capabilities x-mint: href: /pt/reference/rails/spi/spi/list-spi-capabilities /api/v1/spi/capabilities/{capabilityId}: get: description: Returns the detail of a single SPI/Pix capability identified by its message type (e.g. "pacs.008"). operationId: getSPICapability parameters: - description: SPI capability identifier (ISO 20022 message type, e.g. pacs.008). in: path name: capabilityId required: true schema: description: SPI capability identifier (ISO 20022 message type, e.g. pacs.008). type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CapabilityDetailResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get SPI capability by ID tags: - Capabilities x-mint: href: /pt/reference/rails/spi/spi/get-spi-capability /api/v1/spi/certificates: get: description: Returns the managed Pix-side certificate inventory (PIC/PIA/QR-code/CERTPIC/signing) with type, origin, status, custody, and validity window — structured public metadata only. Key material is never exposed. operationId: listPixCertificates parameters: - description: Optional lifecycle-status filter; omit (empty) for all. explode: false in: query name: status schema: description: Optional lifecycle-status filter; omit (empty) for all. enum: - ACTIVE - DEACTIVATED - EXPIRED type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PixCertificateListResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List Pix certificates tags: - Certificates x-mint: href: /pt/reference/rails/spi/spi/list-pix-certificates post: description: Imports a PUBLIC certificate (.cer; base64-encoded PEM or DER). The private key NEVER crosses this boundary — a .p12/private-key payload is rejected with 422 (fail-closed), reported through this operation's generic error response (Detail), not a distinguished per-status schema entry. For an HSM-custody key (the KMIP signing leaf) the flow is CSR-generate-in-HSM then upload the issued .cer only. operationId: uploadPixCertificate requestBody: content: application/json: schema: $ref: "#/components/schemas/UploadPixCertificateRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PixCertificateWire" description: Created "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Upload a Pix certificate (public .cer) tags: - Certificates x-mint: href: /pt/reference/rails/spi/spi/upload-pix-certificate /api/v1/spi/certificates/{id}: delete: description: Flips an ACTIVE certificate to DEACTIVATED and appends a DEACTIVATE audit row. Never a hard delete — the inventory and its audit trail are retained. operationId: deactivatePixCertificate parameters: - description: Certificate row UUID. in: path name: id required: true schema: description: Certificate row UUID. format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DeactivatePixCertificateRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PixCertificateWire" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Deactivate a Pix certificate tags: - Certificates x-mint: href: /pt/reference/rails/spi/spi/deactivate-pix-certificate get: description: Returns one certificate's structured public metadata plus its append-only audit trail (UPLOAD/DEACTIVATE), newest first. operationId: getPixCertificate parameters: - description: Certificate row UUID. in: path name: id required: true schema: description: Certificate row UUID. format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PixCertificateDetailResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get a Pix certificate with its audit trail tags: - Certificates x-mint: href: /pt/reference/rails/spi/spi/get-pix-certificate /api/v1/spi/connectivity-tests: post: description: "Prerequisite: this is the rail-liveness step of the onboarding chain (connectivity-test → submit); a passing connectivity test is the prerequisite for a submit operation (see createPayment, createStructuredOperation). Builds a pibr.001 echo request, records a CONNECTIVITY_TEST operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface." operationId: createConnectivityTest parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateConnectivityTestRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ConnectivityTestResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Initiate SPI connectivity test tags: - Operations - onboarding x-mint: href: /pt/reference/rails/spi/spi/create-connectivity-test /api/v1/spi/evidence/exports: post: description: Creates an evidence_export_jobs row in QUEUED state. Idempotent — a duplicate X-Idempotency returns the existing job. operationId: createEvidenceExport parameters: - description: "Caller-supplied idempotency key (1..255 characters) and the ONLY source of one: a repeat returns the existing job. The request body carries no key — a body naming one is refused. Lerian's own bound." in: header name: X-Idempotency required: true schema: description: "Caller-supplied idempotency key (1..255 characters) and the ONLY source of one: a repeat returns the existing job. The request body carries no key — a body naming one is refused. Lerian's own bound." examples: - idem-001 maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateEvidenceExportRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/EvidenceExportResponse" description: Created "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create evidence export job tags: - Evidence x-mint: href: /pt/reference/rails/spi/spi/create-evidence-export /api/v1/spi/evidence/exports/{exportId}: get: description: Returns the export job state for the given id. operationId: getEvidenceExport parameters: - description: Evidence export job identifier in: path name: exportId required: true schema: description: Evidence export job identifier type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EvidenceExportResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get evidence export job tags: - Evidence x-mint: href: /pt/reference/rails/spi/spi/get-evidence-export /api/v1/spi/icom/parked: get: description: "Lists inbound BACEN messages the rail boundary refused past the threshold, and messages whose body was empty or exceeded the size cap. Each was stored durably and acked toward ICOM so the out-stream could advance; an empty or oversized one keeps no body (an oversized one keeps its first bytes) and cannot be replayed, every other one waits for an operator replay. Metadata only: PI-ResourceId, channel, message type, size, a closed-vocabulary reason, attempts and timestamps — never the message body, a tax id, a key or an account. Nothing in this surface discards a message." operationId: listParkedICOMMessages parameters: - description: Maximum rows to return (1-200). explode: false in: query name: limit schema: default: 50 description: Maximum rows to return (1-200). format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ParkedICOMMessageListWire" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List parked ICOM messages tags: - ICOM x-mint: href: /pt/reference/rails/spi/spi/list-parked-icom-messages /api/v1/spi/icom/parked/{resourceId}: get: description: Returns one parked message's metadata by PI-ResourceId. Never returns the message body. operationId: getParkedICOMMessage parameters: - description: BACEN's PI-ResourceId for the parked message. in: path name: resourceId required: true schema: description: BACEN's PI-ResourceId for the parked message. maxLength: 64 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ParkedICOMMessageWire" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get one parked ICOM message tags: - ICOM x-mint: href: /pt/reference/rails/spi/spi/get-parked-icom-message /api/v1/spi/icom/parked/{resourceId}/replay: post: description: "Re-presents a parked message at the rail boundary with its original bytes and original receipt time, through the same channel and the same idempotency key the first forward used. A terminal outcome closes the row; a non-terminal one leaves it parked with one more attempt. This is the ONLY way a message leaves the parked set — there is no discard verb. An empty or oversized message is refused with 409: its body was not stored." operationId: replayParkedICOMMessage parameters: - description: "Idempotency key, max 255 characters. Required: a replay pushes a real BACEN message at the rail, so a retried click must not forward it twice." in: header name: X-Idempotency required: true schema: description: "Idempotency key, max 255 characters. Required: a replay pushes a real BACEN message at the rail, so a retried click must not forward it twice." type: string - description: BACEN's PI-ResourceId for the parked message to replay. in: path name: resourceId required: true schema: description: BACEN's PI-ResourceId for the parked message to replay. maxLength: 64 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReplayParkedICOMMessageWire" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Replay a parked ICOM message tags: - ICOM x-mint: href: /pt/reference/rails/spi/spi/replay-parked-icom-message /api/v1/spi/mandates: get: description: INTERNAL operator read. Returns a page of the platform's PIX_AUTOMATIC_AUTHORIZATION operations with their mandate lifecycle state, optionally filtered by status. Projects stored operation facts verbatim — no monetary value or position is returned or computed. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint. operationId: listMandates parameters: - description: Optional mandate lifecycle state filter (pain_lifecycle_state), e.g. PENDING_CONFIRMATION, ACTIVE, CANCELLED. explode: false in: query name: status schema: description: Optional mandate lifecycle state filter (pain_lifecycle_state), e.g. PENDING_CONFIRMATION, ACTIVE, CANCELLED. type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Number of rows to skip (offset pagination). explode: false in: query name: offset schema: default: 0 description: Number of rows to skip (offset pagination). format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/MandateListResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List recorded Pix Automático mandate operations (internal operator read) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/list-mandates post: description: Builds a pain.009 mandate-confirmation request, validates the mandate state machine, records the PIX_AUTOMATIC_AUTHORIZATION operation, and submits the signed payload to the BACEN catalogue surface. operationId: createMandateRequest parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateMandateRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/MandateEmissionResponse" description: Created "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Request confirmation of a Pix Automático mandate (pain.009) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-mandate-request /api/v1/spi/mandates/cancellations: post: description: Builds a pain.011 cancellation for an EXISTING mandate, validates the mandate state machine, and submits the signed payload to BACEN. operationId: createMandateCancellation parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateMandateCancellation" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/MandateEmissionResponse" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Cancel a Pix Automático mandate (pain.011) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-mandate-cancellation /api/v1/spi/mandates/resolutions: post: description: "Builds a pain.012 acceptance report for a mandate the platform holds, validates the mandate state machine, and submits the signed payload to BACEN. A pain.012 answering a pain.009 or pain.011 this installation sent is refused with 422: only the PSP that received it answers it. A PDNG acceptance is the jornada-1 receipt acknowledgement: it is recorded and sent without changing the mandate, so the payer's later decision (CFDB or a rejection) goes through this same route. A CFDB through a QR-code journey (AUT2, AUT3 or AUT4) is the one resolution that needs no held mandate: when no pain.009 preceded it, it registers the mandate from the request as active and names the recurrence creation instant read from the Rec." operationId: createMandateResolution parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateMandateResolution" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/MandateEmissionResponse" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Accept or reject a Pix Automático mandate (pain.012) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-mandate-resolution /api/v1/spi/mandates/{mandateId}: get: description: INTERNAL operator read. Returns the recorded PIX_AUTOMATIC_AUTHORIZATION operation for the mandate id, with its lifecycle state. Unknown mandate ids return 404 so existence is non-enumerable. Projects stored facts verbatim — no monetary value or position. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint. operationId: getMandate parameters: - description: Mandate (recorrência) identifier to inspect. in: path name: mandateId required: true schema: description: Mandate (recorrência) identifier to inspect. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MandateReadModelResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unknown mandate id. "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Inspect a recorded Pix Automático mandate operation (internal operator read) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/get-mandate /api/v1/spi/messages: get: description: Returns a chronological, filterable page of message_records rows (Data/Hora, Tipo, Fluxo, Situação). Each row carries metadata + the SHA-256 payload hash only — the raw signed XML is never persisted at rest — and no monetary or position field is returned. operationId: listMessageLog parameters: - description: Message family filter (ADMI, CAMT, PACS, PAIN, PIBR, REDA, TRCK, SIGNATURE). explode: false in: query name: family schema: description: Message family filter (ADMI, CAMT, PACS, PAIN, PIBR, REDA, TRCK, SIGNATURE). type: string - description: Catalogue message type filter (e.g. pacs.008). explode: false in: query name: messageType schema: description: Catalogue message type filter (e.g. pacs.008). type: string - description: "Flow filter: INBOUND (recebida), OUTBOUND (enviada), or INTERNAL." explode: false in: query name: direction schema: description: "Flow filter: INBOUND (recebida), OUTBOUND (enviada), or INTERNAL." type: string - description: "Lifecycle state filter: RECEIVED, CLASSIFIED, SUBMITTED, ACKNOWLEDGED, PENDING, REJECTED or FAILED." explode: false in: query name: state schema: description: "Lifecycle state filter: RECEIVED, CLASSIFIED, SUBMITTED, ACKNOWLEDGED, PENDING, REJECTED or FAILED." type: string - description: Participant ISPB filter (8 digits or uppercase letters). explode: false in: query name: participantIspb schema: description: Participant ISPB filter (8 digits or uppercase letters). type: string - description: Business correlation key filter. explode: false in: query name: businessKey schema: description: Business correlation key filter. type: string - description: Operation id filter (correlated rows). explode: false in: query name: operationId schema: description: Operation id filter (correlated rows). type: string - description: Inclusive lower bound on created_at (RFC 3339 UTC). explode: false in: query name: from schema: description: Inclusive lower bound on created_at (RFC 3339 UTC). type: string - description: Inclusive upper bound on created_at (RFC 3339 UTC). explode: false in: query name: to schema: description: Inclusive upper bound on created_at (RFC 3339 UTC). type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Opaque pagination cursor. explode: false in: query name: cursor schema: description: Opaque pagination cursor. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MessageLogPageResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List the SPI message log tags: - Messages x-mint: href: /pt/reference/rails/spi/spi/list-message-log /api/v1/spi/messages/inbound/process: post: description: "Addresses exactly one parked item: a Pix by endToEndId, or a devolução a third party sent against a Pix your client sent by returnId (the RtrId spi.payment.return_received announced); a request naming both, or neither, is refused (422). A devolução is decided with authorized (answered ACSP; it is returned only when the SPI settles it, which spi.payment.returned or spi.payment.partial_returned announces) or refusalReason, one of AC03, AC06, AC07, BE01 or AM09 (answered RJCT and announced by spi.payment.return_declined); the funding evidence does not apply to it, and a verdict after its window closed is refused (409), the rail having refused it with AB09. Prerequisite for a Pix: it must be parked awaiting funding — enumerate it via listPixAwaitingFunding (GET /api/v1/spi/pix/awaiting-funding) and use the endToEndId it returns. Concludes that payment one of three ways, and a request states exactly one of them. Supply the funding evidence your own system holds (availableBalance, availableLimit, riskScore) and this rail assesses it against the amount: the Pix is accepted, or it is refused with the reason the assessment produced. An accepted Pix is answered ACSP to BACEN and is not settled yet (settled is false): it settles when the SPI confirms with ACCC, which spi.payment.settled announces, or is refused if the SPI rejects it. Supply authorized instead, with no evidence, when your own system has already authorized the credit: the Pix is accepted exactly as an assessed approval is and nothing is assessed, because you decided and you measured no balance for this rail to weigh. Supply refusalReason instead, with no evidence, when your system has already refused the credit for a reason that is not about money — the key resolving to nothing (AC03), an account that cannot receive (AC06), a closed account (AC07), an account held by someone other than the stated receiver (BE01) or, under catalogue kit 5.13.2, an account your institution judges to exploit illegal fixed-odds betting (AG01; DS04 under 5.12.1): the Pix is refused with that reason and nothing is assessed. A refusalReason of FRAD together with antifraudDecision=true declares the refusal of the client's antifraud system and is answered RJCT FRAD; FRAD without the mark is answered DS04. antifraudDecision with any other refusal, with no refusal, or with returnId is refused (422) and changes nothing. A request carrying none of the three, or more than one, is refused (422) and changes nothing. An endToEndId this rail is not holding is refused (404) and changes nothing; a payment or devolução that already concluded is refused (409, code SPI-3006). A verdict that arrives after the Pix or devolução ran out of its regulatory window is also refused (409, code SPI-3008), and that one is final: the rail has closed the window itself and no other evidence reopens it, so abandon the decision rather than retrying it. These and every other rejection here are reported through this operation's generic error response (Detail), not a distinguished per-status schema entry." operationId: processInboundMessage requestBody: content: application/json: schema: $ref: "#/components/schemas/ProcessInboundRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ProcessInboundResponse" description: OK links: prerequisite: description: "Lifecycle prerequisite: the endToEndId must come from listPixAwaitingFunding — the funding decision only concludes a Pix this rail already received and parked." operationId: listPixAwaitingFunding "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Decide a parked inbound Pix or devolução tags: - Messages - lifecycle x-mint: href: /pt/reference/rails/spi/spi/process-inbound-message /api/v1/spi/messages/inbound/validate: post: description: Validates an inbound ISO 20022 XML message (schema and signature) without processing it. operationId: validateInboundMessage requestBody: content: application/json: schema: $ref: "#/components/schemas/MessageRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/MessageResponse" description: OK "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Validate inbound message tags: - Messages x-mint: href: /pt/reference/rails/spi/spi/validate-inbound-message /api/v1/spi/messages/{messageRecordId}: get: description: Returns the requested message_records row plus its correspondent — the sibling row sharing operation_id (Mensagem Original + Mensagem Correspondente). Hash-only metadata; no raw XML and no payload body are returned, and the original<->correspondent pairing is a single indexed lookup, never a monetary aggregate. operationId: getMessageLogDetail parameters: - description: message_records row id to inspect. in: path name: messageRecordId required: true schema: description: message_records row id to inspect. type: string - description: Alternative lookup by operation id; ignored when the path id resolves a row. explode: false in: query name: operationId schema: description: Alternative lookup by operation id; ignored when the path id resolves a row. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MessageLogDetailResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Inspect a message-log entry and its correspondent tags: - Messages x-mint: href: /pt/reference/rails/spi/spi/get-message-log-detail /api/v1/spi/operations: post: description: "Prerequisite: a passing connectivity test (see createConnectivityTest) confirms the rail is reachable before a submit. Submits a structured business operation to the SPI rail. Raw regulated payloads are forbidden anywhere in the request body." operationId: createStructuredOperation parameters: - description: "Caller-supplied idempotency key (1..255 characters) and the ONLY source of one: a repeat with the same key returns the original result instead of creating a duplicate. The request body carries no key — a body naming one is refused. Lerian's own bound." in: header name: X-Idempotency required: true schema: description: "Caller-supplied idempotency key (1..255 characters) and the ONLY source of one: a repeat with the same key returns the original result instead of creating a duplicate. The request body carries no key — a body naming one is refused. Lerian's own bound." examples: - idem-001 maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateStructuredOperationRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/StructuredOperationResponse" description: Created links: prerequisite: description: "Onboarding prerequisite: a passing connectivity test (createConnectivityTest) confirms the rail is reachable before a structured-operation submit." operationId: createConnectivityTest "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create structured operation tags: - Operations - onboarding x-mint: href: /pt/reference/rails/spi/spi/create-structured-operation /api/v1/spi/operations/replies/failed: get: description: "Lists, across operations, the pain.014 and camt.029 replies this rail sent that BACEN refused with an admi.002 (or an operator released), soonest deadline first, each with the time left for its resend. Only an operation's own reply is listed: a camt.029 echoed to a resent camt.055 owes no resend. Nothing is sent: the endpoint that sent the reply resends the same verdict before the deadline." operationId: listFailedReplies parameters: - description: Keep one reply type; absent keeps both. explode: false in: query name: messageType schema: description: Keep one reply type; absent keeps both. enum: - pain.014 - camt.029 type: string - description: true keeps the replies past their deadline (no resend is accepted any more), false those still inside it; absent keeps both. explode: false in: query name: overdue schema: description: true keeps the replies past their deadline (no resend is accepted any more), false those still inside it; absent keeps both. enum: - "true" - "false" type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Opaque pagination cursor. explode: false in: query name: cursor schema: description: Opaque pagination cursor. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FailedRepliesPageWire" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List the replies BACEN refused tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/list-the-replies-bacen-refused /api/v1/spi/operations/stuck: get: description: Returns the cross-rail operator dashboard page of operations needing attention, conformed to the shared recovery vocabulary. Each row carries only the verbs SPI can actually perform on it (a verb SPI cannot perform is absent) and the disposition ('what happens if I do nothing'). No monetary or position fields are returned. operationId: listStuckOperations parameters: - description: "Attention reason filter: STUCK_OUTBOUND, AWAITING_RAIL_RESPONSE, REQUIRES_OPERATOR_ACTION, DEADLINE_EXPIRED or STUCK_INBOUND" explode: false in: query name: reason schema: description: "Attention reason filter: STUCK_OUTBOUND, AWAITING_RAIL_RESPONSE, REQUIRES_OPERATOR_ACTION, DEADLINE_EXPIRED or STUCK_INBOUND" type: string - description: Age bucket filter (OVER_5_MIN, OVER_15_MIN, OVER_1_HOUR, OVER_1_DAY) explode: false in: query name: age schema: description: Age bucket filter (OVER_5_MIN, OVER_15_MIN, OVER_1_HOUR, OVER_1_DAY) type: string - description: Canonical operation state filter (e.g. AWAITING_RESPONSE, REQUIRES_OPERATOR_ACTION) explode: false in: query name: state schema: description: Canonical operation state filter (e.g. AWAITING_RESPONSE, REQUIRES_OPERATOR_ACTION) type: string - description: Page size (default 50, max 100) explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque pagination cursor explode: false in: query name: cursor schema: description: Opaque pagination cursor type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/StuckPageResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List stuck operations (operator dashboard) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/list-stuck-operations /api/v1/spi/operations/stuck/actions: post: description: Spends one of the affordances the stuck-operations listing offered on a row. The verb is re-evaluated against the LIVE row at submit time, so an affordance that has since become unsafe is refused here even though the listing offered it. A devolução row offers only the BACEN lookup of its RtrId; its manual resolution goes through its PAYMENT_RETURN operation, under approval. operationId: submitStuckOperationAction parameters: - description: Required key used to replay the original accepted result without repeating the action. in: header name: X-Idempotency required: true schema: description: Required key used to replay the original accepted result without repeating the action. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SubmitStuckActionRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/VerbOutcomeResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Submit an operator verb against a stuck row tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/submit-stuck-operation-action /api/v1/spi/operations/{operationId}/evidence: get: description: Returns a chronological page of normalized evidence records for an operation. Raw payload references are denied by default. operationId: getOperationEvidence parameters: - description: Operation identifier in: path name: operationId required: true schema: description: Operation identifier type: string - description: Evidence category filter (VALIDATION, SECURITY, DISPATCH, RESPONSE, STATE, OPERATOR, APPROVAL, PAYLOAD) explode: false in: query name: category schema: description: Evidence category filter (VALIDATION, SECURITY, DISPATCH, RESPONSE, STATE, OPERATOR, APPROVAL, PAYLOAD) type: string - description: Request the opaque raw payload reference (true/false) explode: false in: query name: includeRawPayloadRef schema: description: Request the opaque raw payload reference (true/false) type: string - description: Page size (default 100, max 500) explode: false in: query name: limit schema: default: 100 description: Page size (default 100, max 500) format: int64 maximum: 500 minimum: 1 type: integer - description: Opaque pagination cursor explode: false in: query name: cursor schema: description: Opaque pagination cursor type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EvidencePageResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get operation evidence tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/get-operation-evidence /api/v1/spi/operations/{operationId}/recovery/manual-resolution: post: description: Closes a stuck operation by operator decision, gated by an APPROVED approval_decisions row. operationId: manualResolveOperation parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Operation identifier in: path name: operationId required: true schema: description: Operation identifier type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ManualResolutionRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ManualResolutionResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Manually resolve operation tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/manual-resolve-operation /api/v1/spi/operations/{operationId}/replies: get: description: "Lists the pain.014 or camt.029 the operation sent in answer to the pain.013 or camt.055 it received: verdict, state, the MsgId to confirm with BACEN, whether a 201 landed (resourceId) and the resend deadline. A reply that is SENT without a resource id is stuck: nothing resends it until an admi.002 refuses it or an operator releases it." operationId: listOperationReplies parameters: - description: "The operation the replies answer: the schedule a pain.014 resolves, the received camt.055 a camt.029 answers." in: path name: operationId required: true schema: description: "The operation the replies answer: the schedule a pain.014 resolves, the received camt.055 a camt.029 answers." format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/OperationRepliesWire" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List the replies an operation sent tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/list-the-replies-an-operation-sent /api/v1/spi/operations/{operationId}/replies/release: post: description: "Releases a reply stuck SENT without a resource id after BACEN confirmed out of band that its MsgId never arrived: the reply becomes FAILED, as an admi.002 leaves it, and the endpoint that sent it resends the same verdict before its deadline. When the operation never reached its operator case, it is moved to REQUIRES_OPERATOR_ACTION owing the verdict the reply's reservation reserved, so a later manual resolution emits it. Invalid (422) without bacenConfirmedNonReceipt; refused (409) for a reply that is not stuck under messageId: already FAILED, delivered with a resource id, moved to another MsgId, or younger than the transport's submit budget. The release and its justification are recorded as OPERATOR evidence on the operation; nothing is sent." operationId: releaseStuckReply parameters: - description: "Idempotency key, max 255 characters. Required: a release reopens a reply for a resend, so a retried click must not act twice." in: header name: X-Idempotency required: true schema: description: "Idempotency key, max 255 characters. Required: a release reopens a reply for a resend, so a retried click must not act twice." type: string - description: The operation the reply answers. in: path name: operationId required: true schema: description: The operation the reply answers. format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReleaseStuckReplyRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OperationReplyWire" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Release a stuck reply tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/release-a-stuck-reply /api/v1/spi/operations/{operationId}/reservations/release: post: description: "Releases the lifecycle reservation a pain.009, pain.011, pain.013, camt.055 or pain.012 kept after an uncertain submit, once BACEN confirmed out of band that the message never arrived: the lifecycle returns to the state it was reserved from, so a corrected message can be sent. Releasing a pain.012 drops the mandate verdict its operator case owed (it was never delivered) and returns an operation in REQUIRES_OPERATOR_ACTION to AWAITING_RESPONSE. Invalid (422) without bacenConfirmedNonReceipt; refused (409) when the lifecycle holds no reservation of that message by this rail (or one under another messageId), when the counterparty's answer already moved it, when BACEN acknowledged the send with a 201, when the operation is closed (a manual resolution may already have emitted the owed verdict; a pain.012's operation must still be PENDING, AWAITING_RESPONSE or REQUIRES_OPERATOR_ACTION), or when the reservation is younger than the transport's submit budget. The release and its justification are recorded as OPERATOR evidence on the operation; nothing is sent." operationId: releaseReservation parameters: - description: "Idempotency key, max 255 characters. Required: a release reopens the lifecycle for a corrected message, so a retried click must not act twice." in: header name: X-Idempotency required: true schema: description: "Idempotency key, max 255 characters. Required: a release reopens the lifecycle for a corrected message, so a retried click must not act twice." type: string - description: "The operation whose lifecycle the message reserved: the mandate a pain.009, pain.011 or pain.012 moves, the schedule a pain.013 or camt.055 does." in: path name: operationId required: true schema: description: "The operation whose lifecycle the message reserved: the mandate a pain.009, pain.011 or pain.012 moves, the schedule a pain.013 or camt.055 does." format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReleaseReservationRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReleasedReservationWire" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Release a kept reservation tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/release-a-kept-reservation /api/v1/spi/operations/{operationId}/timeline: get: description: Returns a chronological page of timeline events for one operation. Limit defaults to 50, capped at 200. operationId: getOperationTimeline parameters: - description: Operation identifier in: path name: operationId required: true schema: description: Operation identifier type: string - description: Page size (default 50, max 200) explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200) format: int64 maximum: 200 minimum: 1 type: integer - description: Opaque pagination cursor explode: false in: query name: cursor schema: description: Opaque pagination cursor type: string - description: Include EVIDENCE-class events (true/false) explode: false in: query name: includeEvidence schema: description: Include EVIDENCE-class events (true/false) type: string - description: Use the unified multi-source aggregator (true/false, default true) explode: false in: query name: aggregated schema: description: Use the unified multi-source aggregator (true/false, default true) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TimelinePageResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get operation timeline tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/get-operation-timeline /api/v1/spi/payments: get: description: "Returns one page of the Pix this rail sent and received, newest first, filterable by direction, status, creation window and counterparty ISPB. An operational rail read, not a BACEN API-Pix endpoint: the BACEN recebidos listing is listReceivedPix." operationId: listPayments parameters: - description: sent or received; absent lists both. explode: false in: query name: direction schema: description: sent or received; absent lists both. enum: - sent - received type: string - description: Payment lifecycle status. explode: false in: query name: status schema: description: Payment lifecycle status. enum: - PENDING - SENT - ACCEPTED - COMPLETED - REJECTED - FAILED - RETURN_PENDING - RETURNED type: string - description: Inclusive lower bound on createdAt (RFC 3339). explode: false in: query name: from schema: description: Inclusive lower bound on createdAt (RFC 3339). format: date-time type: string - description: Inclusive upper bound on createdAt (RFC 3339). explode: false in: query name: to schema: description: Inclusive upper bound on createdAt (RFC 3339). format: date-time type: string - description: "ISPB of the far side: the creditor of a sent Pix, the originator of a received one." explode: false in: query name: counterpartyIspb schema: description: "ISPB of the far side: the creditor of a sent Pix, the originator of a received one." pattern: ^[0-9A-Z]{8}$ type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Opaque cursor from the previous page's nextCursor. explode: false in: query name: cursor schema: description: Opaque cursor from the previous page's nextCursor. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentPageResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List payments sent and received tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/list-payments post: description: "Prerequisite: a passing connectivity test (see createConnectivityTest) confirms the rail is reachable before a submit. Initiates a new BRL-only SPI payment via BACEN. Generates an EndToEndID if not provided. The EndToEndID format is E{ISPB}{YYYYMMDD}{uniqueID}, exactly 32 characters. A 5xx answered after the payment was recorded names it in errors[] (location body.endToEndId): the Pix may have reached BACEN, so read it with getPayment before sending again; under a 503 SPI-1001 it never left for BACEN and was closed as failed. Every 5xx after the request reached the payment, and every answer whose idempotency receipt could not be stored (a 201 included), carries the X-Idempotency-Fenced response header: true means a resend under the X-Idempotency key is refused with 422 (code SPI-3009) for the key lifetime; false means that refusal was not stored. Once no fence holds the key (it lapsed, or was never stored), a resend of the same request from the same caller (member order and whitespace do not count) answers that payment as it stands now, with X-Idempotency-Replayed: true, and sends nothing; another request under the key is refused with 422. A 503 answered before the payment ran, because the idempotency store was down, carries no such header. A client that got no answer at all resends with the SAME X-Idempotency key: a new key is a new payment. The key belongs to the caller that sent it: the same key from another application or user is a new payment." operationId: createPayment parameters: - description: Idempotency key, max 255 characters, unique per payment; a recorded payment keeps its key for good in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters, unique per payment; a recorded payment keeps its key for good type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreatePaymentRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" description: Created headers: X-Idempotency-Replayed: schema: description: "true when the key already holds a payment and nothing new was sent: the stored answer while the replay window (IDEMPOTENCY_RETRY_WINDOW_SEC) holds the key, the payment as it stands now after it." type: string links: prerequisite: description: "Onboarding prerequisite: a passing connectivity test (createConnectivityTest) confirms the rail is reachable before a payment submit." operationId: createConnectivityTest "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create payment tags: - Payments - onboarding x-mint: href: /pt/reference/rails/spi/spi/create-payment /api/v1/spi/payments/{endToEndID}: get: description: Retrieves a single payment by its EndToEndID, including event history when available. operationId: getPayment parameters: - description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) in: path name: endToEndID required: true schema: description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get payment tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/get-payment /api/v1/spi/payments/{endToEndID}/history: get: description: Retrieves the full event history for a payment, ordered chronologically. operationId: getPaymentHistory parameters: - description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) in: path name: endToEndID required: true schema: description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentHistoryResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get payment history tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/get-payment-history /api/v1/spi/payments/{endToEndID}/returns: post: description: "Prerequisite: the parent payment must be COMPLETED (settled) before a return — read its state via getPayment (GET /api/v1/spi/payments/{endToEndID}); the {endToEndID} path segment structurally ties the return to its parent. Sends a pacs.004 carrying the requested reason. amount below the original is a partial return (the payment stays settled; the sum of all returns must not exceed the original), equal or absent is the full return. A repeat with the same reason, amount and devolucaoId replays the existing devolução; FR01 also emits spi.payment.med_return_requested. Read the result with getDevolucao." operationId: initiatePaymentReturn parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) in: path name: endToEndID required: true schema: description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InitiatePaymentReturnRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/DevolucaoResponse" description: Created links: prerequisite: description: "Lifecycle prerequisite: the parent payment read by getPayment must be COMPLETED (settled) before a return is accepted." operationId: getPayment "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Initiate payment return tags: - Payments - lifecycle x-mint: href: /pt/reference/rails/spi/spi/initiate-payment-return /api/v1/spi/payments/{endToEndID}/returns/status: get: description: Alias of Get payment for clients polling return state. operationId: getPaymentReturnStatus parameters: - description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) in: path name: endToEndID required: true schema: description: EndToEndID in E{ISPB}{YYYYMMDD}{uniqueID} format (32 characters) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get payment return status tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/get-payment-return-status /api/v1/spi/pix: post: description: Returns the BACEN PixConsultados envelope of received Pix (those settled to this FI as creditor) within the inicio/fim window, each projected with its devoluções. cpf and cnpj are mutually exclusive and are accepted only in the authenticated JSON body so they never enter URLs or access logs. operationId: listReceivedPix parameters: - description: Window start, RFC 3339 (required). explode: false in: query name: inicio required: true schema: description: Window start, RFC 3339 (required). format: date-time type: string - description: Window end, RFC 3339 (required). explode: false in: query name: fim required: true schema: description: Window end, RFC 3339 (required). format: date-time type: string - description: Optional txid filter ([a-zA-Z0-9]{1,35}). explode: false in: query name: txid schema: description: Optional txid filter ([a-zA-Z0-9]{1,35}). pattern: ^[a-zA-Z0-9]{1,35}$ type: string - description: Optional tri-state filter on whether the Pix carries a txid (true/false; absent = no filter). explode: false in: query name: txIdPresente schema: description: Optional tri-state filter on whether the Pix carries a txid (true/false; absent = no filter). enum: - "true" - "false" type: string - description: Optional tri-state filter on whether the Pix has returns (true/false; absent = no filter). explode: false in: query name: devolucaoPresente schema: description: Optional tri-state filter on whether the Pix has returns (true/false; absent = no filter). enum: - "true" - "false" type: string - description: 0-based page number per BACEN (default 0). explode: false in: query name: paginacao.paginaAtual schema: default: 0 description: 0-based page number per BACEN (default 0). format: int64 minimum: 0 type: integer - description: Page size per BACEN (default 100, max 1000). explode: false in: query name: paginacao.itensPorPagina schema: default: 100 description: Page size per BACEN (default 100, max 1000). format: int64 maximum: 1000 minimum: 1 type: integer requestBody: content: application/json: schema: $ref: "#/components/schemas/ReceivedPixPIIFilters" description: Optional payer-document filters, carried in the body so CPF/CNPJ never enter URLs or access logs. required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PixConsultadosResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Consultar Pix recebidos tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/list-received-pix /api/v1/spi/pix/awaiting-funding: get: description: "Returns the arriving Pix this rail received from BACEN and parked awaiting the funding decision only the client's own system can make. Each item carries the endToEndId that processInboundMessage (POST /api/v1/spi/messages/inbound/process) is addressed by, plus the amount that arrived. This is an operational rail read, not a BACEN API-Pix conformant endpoint: a Pix listed here has NOT settled." operationId: listPixAwaitingFunding parameters: - description: Page size (default 100, max 1000). explode: false in: query name: limit schema: default: 100 description: Page size (default 100, max 1000). format: int64 maximum: 1000 minimum: 1 type: integer - description: Number of rows to skip (default 0). explode: false in: query name: offset schema: default: 0 description: Number of rows to skip (default 0). format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/PixAwaitingFundingResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List arriving Pix awaiting a funding decision tags: - Payments - lifecycle x-mint: href: /pt/reference/rails/spi/spi/list-pix-awaiting-funding /api/v1/spi/pix/{e2eid}/devolucao/{id}: get: description: Returns the devolução recorded under the original Pix's EndToEndId and the DevolucaoId, whichever surface requested it (requestDevolucao or initiatePaymentReturn). The status is EM_PROCESSAMENTO until BACEN answers, then DEVOLVIDO or NAO_REALIZADO. When a refused attempt was retried under the same DevolucaoId, the latest attempt answers. operationId: getDevolucao parameters: - description: EndToEndId of the original Pix (E{ISPB}{YYYYMMDD}{uniqueID}, 32 characters). in: path name: e2eid required: true schema: description: EndToEndId of the original Pix (E{ISPB}{YYYYMMDD}{uniqueID}, 32 characters). type: string - description: DevolucaoId the return was requested under. in: path name: id required: true schema: description: DevolucaoId the return was requested under. pattern: ^[a-zA-Z0-9]{1,35}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/DevolucaoResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Consultar devolução tags: - Payments x-mint: href: /pt/reference/rails/spi/spi/get-devolucao put: description: "Prerequisite: the parent payment must be COMPLETED (settled) before a return — read its state via getPayment (GET /api/v1/spi/payments/{endToEndID}). Requests a (possibly partial) Pix return identified by the client-generated DevolucaoId {id}; the sum of all returns must not exceed the original Pix value. A repeat PUT with the same {id} replays the existing devolução. Emits a pacs.004 (reason MD06 for ORIGINAL, SL02 for RETIRADA)." operationId: requestDevolucao parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: EndToEndId of the original Pix (E{ISPB}{YYYYMMDD}{uniqueID}, 32 characters). in: path name: e2eid required: true schema: description: EndToEndId of the original Pix (E{ISPB}{YYYYMMDD}{uniqueID}, 32 characters). type: string - description: Client-generated DevolucaoId ([a-zA-Z0-9]{1,35}); idempotency key for this return. in: path name: id required: true schema: description: Client-generated DevolucaoId ([a-zA-Z0-9]{1,35}); idempotency key for this return. pattern: ^[a-zA-Z0-9]{1,35}$ type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DevolucaoSolicitadaRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/DevolucaoResponse" description: Created links: prerequisite: description: "Lifecycle prerequisite: the parent payment read by getPayment must be COMPLETED (settled) before a return is accepted." operationId: getPayment "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Solicitar devolução tags: - Payments - lifecycle x-mint: href: /pt/reference/rails/spi/spi/request-devolucao /api/v1/spi/regulatory-archive/{itemId}: get: description: "Returns one item of the regulatory archive (Manual de Segurança do SFN, Vol. II, v6.00, cap. 7): an ICOM envelope sent or received with its PI-ResourceId and headers, a DICT request or answer with its headers, or a certificate used to sign or verify them. The body comes back byte for byte, so a signature can be verified again. This is the ONLY route that returns archived content: it requires a human caller, and every read is audited — who read which item and when, never the content — before the content is fetched; a read that cannot be audited answers nothing." operationId: getRegulatoryArchiveItem parameters: - description: The archived item's index id. in: path name: itemId required: true schema: description: The archived item's index id. format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegulatoryArchiveItemWire" description: OK headers: Cache-Control: schema: type: string "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Read one regulatory archive item tags: - Regulatory archive x-mint: href: /pt/reference/rails/spi/spi/read-one-regulatory-archive-item /api/v1/spi/reports/balances: get: description: Lists the spi_account_balance snapshots (camt.053 saldo) received in a mandatory date window (max 92 days), projected verbatim. The amount is the BACEN-supplied figure projected as-is — never recomputed, never summed. operationId: getSPIReportBalances parameters: - description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. explode: false in: query name: fromDate required: true schema: description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. examples: - "2026-06-01" type: string - description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. explode: false in: query name: toDate required: true schema: description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. examples: - "2026-06-30" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SPIBalancesResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Conta-PI balance-window report tags: - Reports x-mint: href: /pt/reference/rails/spi/spi/get-spi-report-balances /api/v1/spi/reports/extracts: get: description: Lists the spi_account_extract rows (camt.052/RCO) received in a mandatory date window (max 92 days) with their report_kind and integrity (verified) + COUNT-recon (countsMatch) flags. The RCO entries stay opaque and are not inlined; no arithmetic is performed over balances. operationId: getSPIReportExtracts parameters: - description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. explode: false in: query name: fromDate required: true schema: description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. examples: - "2026-06-01" type: string - description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. explode: false in: query name: toDate required: true schema: description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. examples: - "2026-06-30" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SPIExtractsResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Conta-PI extract-list report tags: - Reports x-mint: href: /pt/reference/rails/spi/spi/get-spi-report-extracts /api/v1/spi/reports/rejected: get: description: Returns the COUNT and a paginated list of payments in a terminal-rejected state (REJECTED / FAILED / RETURN_PENDING) over a mandatory date window (max 92 days). The detailed reject reason is not retained — only status + EndToEndID are returned, and the absence is labelled honestly. operationId: getSPIReportRejected parameters: - description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. explode: false in: query name: fromDate required: true schema: description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. examples: - "2026-06-01" type: string - description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. explode: false in: query name: toDate required: true schema: description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. examples: - "2026-06-30" type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Opaque pagination cursor. explode: false in: query name: cursor schema: description: Opaque pagination cursor. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SPIRejectedResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: SPI rejected-payments report tags: - Reports x-mint: href: /pt/reference/rails/spi/spi/get-spi-report-rejected /api/v1/spi/reports/volumetria: get: description: "Returns COUNT(*) buckets grouped by message type, status, or participant over a mandatory date window (max 92 days). COUNT-only: the SPI payments record persists no amount, so there is no monetary sum on the SPI side." operationId: getSPIReportVolumetria parameters: - description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. explode: false in: query name: fromDate required: true schema: description: Inclusive start of the report window (YYYY-MM-DD UTC). Required. examples: - "2026-06-01" type: string - description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. explode: false in: query name: toDate required: true schema: description: Inclusive end of the report window (YYYY-MM-DD UTC). Required. The window may not exceed 92 days. examples: - "2026-06-30" type: string - description: "Grouping axis: messageType (over spi_message_correlations), status, or participant (the +indireto originator breakdown over payments)." explode: false in: query name: groupBy schema: default: messageType description: "Grouping axis: messageType (over spi_message_correlations), status, or participant (the +indireto originator breakdown over payments)." enum: - messageType - status - participant type: string - description: Optional originating participant ISPB filter, 8 digits or uppercase letters (payments axes only). explode: false in: query name: originatorIspb schema: description: Optional originating participant ISPB filter, 8 digits or uppercase letters (payments axes only). type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SPIVolumetriaResponse" description: OK "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: SPI volumetria report (COUNT-only) tags: - Reports x-mint: href: /pt/reference/rails/spi/spi/get-spi-report-volumetria /api/v1/spi/responsibles: get: description: Returns the last-known Conta-PI responsibles snapshot (CONTATOPSP contact, DIRETORPSP director, palavra-chave) of the installation's direct participant, the only one reda.022 registers, plus its source (SUBMITTED / COMP_CONFIRMED) and recorded-at. reda.022 is fire-to-BACEN; this read-model is written on submit-success and refreshed on the inbound reda.016 COMP advice. Structured fields only — never signed bytes. The palavra-chave is a regulatory identifier returned verbatim; it is masked on display. operationId: getResponsibles responses: "200": content: application/json: schema: $ref: "#/components/schemas/ResponsiblesWire" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get the installation's last-known Conta-PI responsibles tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/get-responsibles post: description: Builds the reda.022 four-block envelope (CONTATOPSP contact, DIRETORPSP director, palavra-chave, CPFDIRETOR), records a PARTICIPANT_ADMINISTRATION operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface. operationId: registerResponsibles parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterResponsiblesRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RegisterResponsiblesResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Register Conta PI responsible contacts tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/register-responsibles /api/v1/spi/scheduled-payments: get: description: INTERNAL operator read. Returns a page of the platform's SCHEDULED_PAYMENT_INSTRUCTION operations with their schedule lifecycle state and side, optionally filtered by status and side. Projects stored operation facts verbatim — no monetary value or position is returned or computed. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint. operationId: listSchedules parameters: - description: Optional schedule lifecycle state filter (pain_lifecycle_state), e.g. SCHEDULED, CONFIRMED, CANCELLED. explode: false in: query name: status schema: description: Optional schedule lifecycle state filter (pain_lifecycle_state), e.g. SCHEDULED, CONFIRMED, CANCELLED. type: string - description: "Optional side filter (pain_schedule_side): PAYER lists the schedules whose pain.013 this installation received, RECEIVER the ones it sent; absent lists both." explode: false in: query name: side schema: description: "Optional side filter (pain_schedule_side): PAYER lists the schedules whose pain.013 this installation received, RECEIVER the ones it sent; absent lists both." enum: - PAYER - RECEIVER type: string - description: Page size (default 50, max 200). explode: false in: query name: limit schema: default: 50 description: Page size (default 50, max 200). format: int64 maximum: 200 minimum: 1 type: integer - description: Number of rows to skip (offset pagination). explode: false in: query name: offset schema: default: 0 description: Number of rows to skip (offset pagination). format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleListResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List recorded Pix Automático schedule operations (internal operator read) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/list-schedules post: description: Builds a pain.013 scheduled payment instruction, enforces the ACTIVE-mandate precondition, records the SCHEDULED_PAYMENT_INSTRUCTION operation, and submits the signed payload to BACEN. operationId: createScheduledPayment parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateScheduledPayment" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ScheduleEmissionResponse" description: Created "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Schedule a Pix Automático payment instruction (pain.013) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-scheduled-payment /api/v1/spi/scheduled-payments/cancellations: post: description: Builds a camt.055 cancellation request for a schedule the platform tracks, validates the schedule state machine, and submits the signed payload to BACEN. operationId: createScheduleCancellation parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateScheduleCancellation" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CancellationEmissionResponse" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Request cancellation of a Pix Automático schedule (camt.055) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-schedule-cancellation /api/v1/spi/scheduled-payments/cancellations/resolutions: post: description: Builds a camt.029 resolution (ACCR/RJCR) for a camt.055 the platform actually RECEIVED, echoing that camt.055's participants, cancellation id, schedule id and EndToEndId; unknown correlations are rejected with 404. operationId: createScheduleCancellationResolution parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateScheduleCancellationResolution" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CancellationEmissionResponse" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Resolve a received cancellation request (camt.029) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-schedule-cancellation-resolution /api/v1/spi/scheduled-payments/resolutions: post: description: "Builds a pain.014 status report (ACSP/RJCT) for a schedule whose pain.013 this installation received, validates the schedule state machine, and submits the signed payload to BACEN. A schedule whose pain.013 this installation sent is refused with 422: only the payer's PSP answers a pain.013." operationId: createScheduledPaymentResolution parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateScheduledPaymentResolution" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ScheduleEmissionResponse" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Accept or reject a Pix Automático scheduled payment (pain.014) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-scheduled-payment-resolution /api/v1/spi/scheduled-payments/{scheduleId}: get: description: INTERNAL operator read. Returns the recorded SCHEDULED_PAYMENT_INSTRUCTION operation for the schedule id, with its lifecycle state. Unknown schedule ids return 404 so existence is non-enumerable. Projects stored facts verbatim — no monetary value or position. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint. operationId: getSchedule parameters: - description: Schedule (agendamento) identifier to inspect. in: path name: scheduleId required: true schema: description: Schedule (agendamento) identifier to inspect. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleReadModelResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unknown schedule id. "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Inspect a recorded Pix Automático schedule operation (internal operator read) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/get-schedule /api/v1/spi/settlement-reports: post: description: Builds a trck.002 internal-settlement report, records a TRACKING_REPORT operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface. operationId: createSettlementReport parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateSettlementReportRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/SettlementReportResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Report internally settled Pix transactions (MED 2.0) tags: - Operations x-mint: href: /pt/reference/rails/spi/spi/create-settlement-report servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. tags: - description: Pix payment orders, returns (MED), and payment history. name: Payments - description: "SPI operations: connectivity tests, account reports, Conta PI responsibles, settlement reports, Pix Automático mandates/schedules, and structured operation recovery." name: Operations - description: Inbound ISO 20022 message validation and processing. name: Messages - description: Approval requests and decisions for operations requiring manual authorization. name: Approvals - description: Operation evidence export jobs and their status. name: Evidence - description: "Synchronous reports over Lerian SPI's own record: volumetria (COUNT-only), rejected payments, and Conta-PI balance/extract windows projected verbatim." name: Reports - description: "Pix-side certificate lifecycle: list/upload/detail/deactivate of PIC/PIA/QR-code/CERTPIC/signing certificates. Structured public metadata + SHA-256 fingerprint only; key material is never exposed and an uploaded private key is rejected fail-closed." name: Certificates - description: "Flow (mandatory order): certificate → readiness → connectivity-test → submit. Activate a certificate, confirm the rail reports ready, pass a connectivity test, then submit an operation. Each step is its own resource; a submit must not be attempted before readiness passes." name: onboarding - description: "Flow (mandatory order): parent operation SETTLED → return/cancel. A return or cancellation is a sub-resource of a settled parent operation; the {operationId}/{endToEndID} path segment enforces the parent structurally." name: lifecycle - description: "Flow (mandatory order): camt.060 request → camt.05x result read. An account-report result read is meaningful only after the camt.060 account-report request has been correlated; the query is initiated first, the result read back." name: account-reporting