components: schemas: AbandonDICTFeedRecordRequest: additionalProperties: false properties: bacenRecordId: description: "The record to abandon, exactly as GET /api/v1/dict/discovery-feeds reports it in heldBacenRecordIds. Two shapes appear there: a BACEN resource UUID this deployment permanently refuses, and the raw identifier BACEN sent for an entry whose id is not a UUID at all. Both are accepted verbatim; neither is interpreted." type: string reason: description: Why this regulated record is being given up. It is recorded in the audit trail under the caller's identity and is the only durable answer to 'why does this deployment not hold that record'. Operator prose only — never a tax id, a Pix key, an account or a holder name. maxLength: 384 minLength: 8 type: string required: - bacenRecordId - reason type: object AbandonDICTFeedRecordResponse: additionalProperties: false properties: abandonedRecords: description: How many records are now permanently abandoned on this feed. examples: - 1 format: int64 type: integer alreadyAbandoned: description: True when this record had already been abandoned. The call is then a no-op on the ledger, still audited under the caller's identity — re-sending the same request is safe. type: boolean bacenRecordId: description: The record, as supplied. type: string feed: description: The feed the record was abandoned on. examples: - dict_infraction_discovery type: string stillHeldBacenRecordIds: description: The records this feed was still stuck on when this call read the list, minus the one just abandoned. Empty means the next tick can move — unless the feed also carries a durable blocked marker, which is cleared separately on POST .../{feed}/unblock. A walk tick running alongside this call may already have found more; GET /api/v1/dict/discovery-feeds is always the current list. items: type: string type: array warning: description: States plainly that the record is now permanently absent from this deployment. type: string required: - feed - bacenRecordId - abandonedRecords - warning type: object AbandonUnregisteredClaimRequest: additionalProperties: false properties: reason: description: Why this claim is being abandoned. It is recorded in the audit trail under the caller's identity. Operator prose only — never a tax id, a Pix key, an account or a holder name. maxLength: 384 minLength: 8 type: string required: - reason type: object AbandonUnregisteredClaimResponse: additionalProperties: false properties: alreadyAbandoned: description: True when the claim had already been abandoned. The call then changed nothing and emitted nothing, and it is still audited under the caller's identity — re-sending the same request is safe. type: boolean claim: $ref: "#/components/schemas/ClaimResponse" description: "The claim after the call: CANCELLED with resolution NOT_REGISTERED_AT_BACEN." warning: description: States plainly what the abandonment did. type: string required: - claim - warning type: object BACENEnvelopeResponse: additionalProperties: false properties: correlationId: description: BACEN's own correlation identifier for its most recent interaction on this record — the wire value, distinct from any request-scoped echo. examples: - a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 type: string lastModified: description: BACEN's own LastModified for this resource (RFC 3339, UTC) — the version this response reflects; present only on the MED resources (infraction, refund, fraud marker, funds recovery). examples: - "2026-06-14T12:00:00Z" type: string responseTime: description: Instant BACEN answered its most recent interaction on this record, RFC 3339 (UTC); omitted when BACEN's response carried no parseable instant. examples: - "2026-06-14T12:00:00Z" type: string required: - correlationId type: object CancelClaimHumaBody: additionalProperties: false properties: reason: description: Cancellation reason; validity depends on claim type, cancelling side, and current status per the BACEN DICT cancelClaim matrix. COURT_ORDER is cancel-only, is claimer-issued at OPEN or WAITING_RESOLUTION, and is recorded verbatim on the claim; the cancellation IS sent to BACEN, carrying USER_REQUESTED, because the DICT in production (2.12.1) has no such enum value. It travels as COURT_ORDER once the DICT reaches 2.13, which adds it to the ClaimOperationReason domain. enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - COURT_ORDER examples: - USER_REQUESTED type: string required: - reason type: object CheckKeyResult: additionalProperties: false properties: hasEntry: description: Whether the key has a DICT entry. examples: - true type: boolean key: description: The submitted PIX key value. examples: - "12345678901" type: string required: - key - hasEntry type: object CheckKeysRequest: additionalProperties: false properties: keys: description: PIX key values to probe for existence (1..200 per batch). Each entry must be a non-blank key of at most 77 characters; a blank entry is refused rather than silently probed. items: maxLength: 77 minLength: 1 type: string maxItems: 200 minItems: 1 type: - array - "null" required: - keys type: object CheckKeysResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for the probe this call made — one per call, not per key. Omitted when the call reached no probe, or when BACEN's answer carried no correlation id. results: description: One existence result per submitted key, in submission order. items: $ref: "#/components/schemas/CheckKeyResult" type: array required: - results type: object CidEntryAccountResponse: additionalProperties: false properties: accountNumber: description: Account number. examples: - "0007654321" type: string accountType: description: Account type, verbatim (CACC, SVGS, TRAN, SLRY, OTHR). examples: - CACC type: string branch: description: Account branch; omitted when BACEN sent none. examples: - "0001" type: string openingDate: description: Account opening date, RFC 3339 (UTC); omitted when BACEN sent none. examples: - "2020-01-15T00:00:00Z" format: date-time type: string participant: description: ISPB of the participant holding the account. examples: - "12345678" type: string required: - participant - accountNumber - accountType type: object CidEntryBindingResponse: additionalProperties: false properties: account: $ref: "#/components/schemas/CidEntryAccountResponse" description: Account the key is bound to. creationDate: description: When BACEN created the binding, BACEN's wire value. examples: - "2025-03-07T14:30:00.000Z" format: date-time type: string key: description: Pix key value. examples: - "11122233396" type: string keyOwnershipDate: description: When the owner's uninterrupted possession of the key began, BACEN's wire value. examples: - "2025-03-07T14:30:00.000Z" format: date-time type: string keyType: description: Key type, verbatim. examples: - CPF type: string owner: $ref: "#/components/schemas/CidEntryOwnerResponse" description: Owner of the key. required: - key - keyType - account - owner type: object CidEntryOwnerResponse: additionalProperties: false properties: name: description: Owner name. examples: - Maria Souza type: string taxIdNumber: description: Owner CPF (11 digits) or CNPJ (14 characters). examples: - "11122233396" type: string tradeName: description: Owner trade name; legal persons only, omitted when absent. examples: - Souza Comercio type: string type: description: "BACEN's person type, verbatim: NATURAL_PERSON or LEGAL_PERSON." examples: - NATURAL_PERSON type: string required: - type - taxIdNumber - name type: object CidEntryResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's operational envelope for this call; omitted when BACEN sent no correlation id. cid: description: The CID that was resolved. examples: - 28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88 type: string entry: $ref: "#/components/schemas/CidEntryBindingResponse" description: The key binding the CID identifies. requestId: description: BACEN's RequestId of the operation that created this binding, from which the CID was computed. Not a request-scoped echo. examples: - 4b6c1e0e-7f7a-4c1e-9d59-3f2a8c1b5e21 type: string required: - cid - entry - requestId type: object CidSetEventResponse: additionalProperties: false properties: cid: description: CID added to or removed from the set. examples: - 28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88 type: string timestamp: description: When the event happened, BACEN's wire value. examples: - "2026-09-28T10:15:30.123Z" type: string type: description: "BACEN's event type, verbatim: ADDED or REMOVED." examples: - ADDED type: string required: - type - cid - timestamp type: object CidSetEventsResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's operational envelope for this call; omitted when BACEN sent no correlation id. cidSetEvents: description: The events, ordered by timestamp; empty when BACEN lists none. items: $ref: "#/components/schemas/CidSetEventResponse" type: array endTime: description: Timestamp of the last event in the page, BACEN's wire value. examples: - "2026-09-28T23:59:59.999Z" type: string hasMoreElements: description: True when BACEN holds more events after this page; ask again from endTime. examples: - false type: boolean keyType: description: Key type of the CID set. examples: - CPF type: string participant: description: ISPB whose CID set the events belong to. examples: - "12345678" type: string startTime: description: Timestamp of the first event in the page, BACEN's wire value. examples: - "2026-09-28T00:00:00.000Z" type: string syncVerifierEnd: description: BACEN's sync verifier of the set after the last event. examples: - cb4f8a1d9e3b27c05f6a4d8e2b1c7f90a3e5d6b8c2f4a1e7d9b3c5f8a2e4d6b1 type: string syncVerifierStart: description: BACEN's sync verifier of the set before the first event. examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string required: - participant - keyType - startTime - endTime - syncVerifierStart - syncVerifierEnd - hasMoreElements - cidSetEvents type: object CidSetFileResponse: additionalProperties: false properties: bytes: description: Size of the file in bytes, as BACEN reported it; omitted until AVAILABLE. examples: - 3200000 format: int64 type: integer creationTime: description: When BACEN generated the file; omitted until it did. examples: - "2026-09-29T12:01:10.5Z" format: date-time type: string id: description: BACEN's id for the file. examples: - "4521" type: string keyType: description: Key type of the CID set. examples: - EMAIL type: string participant: description: ISPB whose CID set the file holds. examples: - "12345678" type: string requestTime: description: When BACEN received the request. examples: - "2026-09-29T12:00:00.123Z" format: date-time type: string sha256: description: SHA-256 of the file, as BACEN reported it; omitted until AVAILABLE. examples: - f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b type: string status: description: "The last status BACEN reported, verbatim: REQUESTED, PROCESSING, AVAILABLE, UNAVAILABLE or ERROR." examples: - AVAILABLE type: string required: - id - status - participant - keyType - requestTime type: object ClaimDecisionHumaBody: additionalProperties: false type: object ClaimListResponse: additionalProperties: false properties: items: description: Claim records for the requested limit/offset window. items: $ref: "#/components/schemas/ClaimResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object ClaimResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this claim; omitted when no BACEN interaction has ever landed on it. bacenClaimId: description: "The id BACEN itself assigned to this claim on createClaim (ExtendedClaim.Id) — the address every BACEN-facing verb and both claim-recovery feeds use internally. Read-only, surfaced so an operator can correlate a BACEN support case or a DICT-side rejection back to this claim. Omitted until BACEN's createClaim response has landed: a locally initiated claim whose initiation outbox handler has not yet processed BACEN's reply carries no value here yet." examples: - 550e8400-e29b-41d4-a716-446655440111 type: string cancelReason: description: "Matches BACEN's ExtendedClaim.CancelReason vocabulary plus COURT_ORDER: the reason the claim was cancelled, once cancelled. On a claim we cancel ourselves (our own cancel verb) this is the reason our own operator submitted; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim. COURT_ORDER is the one value BACEN does not define at the pinned DICT 2.12.1: it is recorded locally on a court-ordered cancellation, and that cancellation reaches BACEN carrying USER_REQUESTED until the DICT reaches 2.13, which adds the value to ClaimOperationReason" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - PARTICIPANT_EXCLUSION - COURT_ORDER type: string cancelledBy: description: "Matches BACEN's ExtendedClaim.CancelledBy vocabulary: the side that cancelled the claim, once cancelled. On a claim we cancel ourselves this is the side derived from the authenticated caller; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim" enum: - DONOR - CLAIMER type: string claimType: description: "Claim kind: OWNERSHIP or PORTABILITY" examples: - OWNERSHIP type: string claimerAccountNumber: description: Number of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountNumber). Answered on every claim projection, the list included examples: - "9988776" type: string claimerAccountType: description: Type of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountType). Answered on every claim projection, the list included enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string claimerBranch: description: Branch of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.Branch); optional at BACEN, so empty when the claimer lodged none. Answered on every claim projection, the list included examples: - "0001" type: string claimerISPB: description: ISPB (8 digits or uppercase letters) of the participant initiating the claim examples: - "12345678" type: string claimerName: description: Name of the claiming key owner (ExtendedClaim.Claimer.Name). Answered on every claim projection, the list included; not carried on a claim streaming fact examples: - João Silva type: string claimerOpeningDate: description: Opening date of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.OpeningDate, RFC 3339 UTC). Answered on every claim projection, the list included examples: - "2020-01-15T00:00:00Z" type: string claimerTaxId: description: CPF/CNPJ of the claiming key owner (ExtendedClaim.Claimer.TaxIdNumber). Answered on every claim projection, the list included; not carried on a claim streaming fact examples: - "11122233300" type: string claimerTradeName: description: Trade name of the claiming key owner (ExtendedClaim.Claimer.TradeName); legal-entity claimers only, empty for a natural person. Answered on every claim projection, the list included examples: - Silva ME type: string claimerType: description: "BACEN's Person discriminator for the claiming key owner (ExtendedClaim.Claimer.Type). DERIVED from the tax id's length, never stored: 11 characters is the CPF branch, 14 the CNPJ branch — the same rule BACEN's own oneOf keys on. Empty when the tax id is absent or has no branch. Answered on every claim projection, the list included" enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string completionPeriodEnd: description: BACEN's own completion-window end for a possession claim (ExtendedClaim.CompletionPeriodEnd, RFC 3339 UTC); BACEN publishes it for OWNERSHIP claims only and omits it for PORTABILITY. Also omitted whenever BACEN has not published this claim yet. examples: - "2025-03-21T14:30:00Z" type: string confirmReason: description: "Matches BACEN's ExtendedClaim.ConfirmReason vocabulary: the reason the donor confirmed with, once confirmed — unlike resolution this is NOT terminal-gated and is never cleared by a later transition. On a claim we confirm ourselves (our own respond verb) this is the reason our own operator submitted; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - PARTICIPANT_EXCLUSION type: string deadline: description: Donor-response deadline (RFC 3339, UTC). For a claim BACEN's own record backs (discovered or adopted), this IS BACEN's ExtendedClaim.ResolutionPeriodEnd, same value as resolutionPeriodEnd below. For a locally-initiated claim, this is always a local seven-day-from-initiation estimate that drives the deadline sweep — see resolutionPeriodEnd for BACEN's own authoritative value, populated once the initiation outbox handler decodes BACEN's createClaim response. examples: - "2025-03-14T14:30:00Z" type: string donorISPB: description: "ISPB (8 digits or uppercase letters) of the current key owner (donor). It is the DICT that resolves the donor, not this rail: a claim lodged on a key held at another institution — the canonical portability case — carries NO donor until BACEN's createClaim response names one (ExtendedClaim.DonorParticipant), so this field is omitted while the donor is pending. A donor-side claim discovered from BACEN's directory always carries it." examples: - "87654321" type: string id: description: Server-assigned claim UUID examples: - 550e8400-e29b-41d4-a716-446655440000 type: string keyType: description: "PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP" examples: - PHONE type: string keyValue: description: PIX key value under claim examples: - "+5511999999999" type: string lastModified: description: BACEN's own last-transition instant for this claim (ExtendedClaim.LastModified, RFC 3339 UTC) — the version discriminator BACEN publishes, distinct from requestedAt (when WE lodged it) and from resolvedAt (when it ended). Present once BACEN's own record for this claim exists; omitted before that. examples: - "2025-03-07T14:30:00Z" type: string requestedAt: description: Claim initiation timestamp (RFC 3339, UTC); omitted for a donor-side claim projected from BACEN, whose ExtendedClaim carries no creation time examples: - "2025-03-07T14:30:00Z" type: string resolution: description: Terminal resolution reason (e.g. CANCELLED_BY_CLAIMER, CANCELLED_BY_CLAIMER_FRAUD, CANCELLED_BY_DONOR, CANCELLED_BY_DONOR_FRAUD, DEADLINE_EXPIRED, AUTO_COMPLETED, TRANSFER_COMPLETED, NOT_REGISTERED_AT_BACEN); empty until the claim resolves — CONFIRMED is not terminal and never sets this field examples: - "" type: string resolutionPeriodEnd: description: BACEN's own resolution-window end for this claim (ExtendedClaim.ResolutionPeriodEnd, RFC 3339 UTC); present once BACEN's own record for this claim exists — discovered, adopted, or a locally-initiated claim whose createClaim response the initiation outbox handler has processed — omitted before that examples: - "2025-03-14T14:30:00Z" type: string resolvedAt: description: Resolution timestamp (RFC 3339, UTC); omitted while the claim is unresolved examples: - "" type: string status: description: "Claim lifecycle state: OPEN, WAITING_RESOLUTION, CONFIRMED, CANCELLED, or COMPLETED" examples: - OPEN type: string required: - id - claimType - keyValue - keyType - claimerISPB - status - deadline type: object CloseInfractionRequest: additionalProperties: false properties: analysisDetails: description: Optional free-text analysis details type: string analysisResult: description: "Infraction analysis outcome: AGREED (BACEN creates the fraud marker) or DISAGREED" enum: - AGREED - DISAGREED examples: - AGREED type: string fraudType: description: BACEN fraud classification; mandatory when analysisResult is AGREED, omit when DISAGREED enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER examples: - APPLICATION_FRAUD type: string required: - analysisResult type: object CloseRefundRequest: additionalProperties: false properties: analysisDetails: description: Free-text analysis details; optional except when rejecting with INVALID_REQUEST, where DICT 8.4 §17 makes it mandatory. type: string analysisResult: description: "Refund analysis outcome: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, or REJECTED" enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string effectiveRefundedAmount: description: Effective refunded amount as an exact decimal; required on a close bound to a funds recovery, validated against the refund amount when present type: number refundTransactionId: description: Identifier of the devolucao this closure executed. Mandatory when analysisResult is TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED, and must be the opposite message type from the contested transaction (a pacs.008 is refunded by a pacs.004 and vice-versa). Omit on a rejection. examples: - D1234567820260220123456789012345 type: string rejectionReason: description: BACEN rejection reason; mandatory when analysisResult is REJECTED, omit when accepted. INVALID_REQUEST is admissible only when the refund's own reason is OPERATIONAL_FLAW (DICT 8.4 §17). enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER examples: - NO_BALANCE type: string required: - analysisResult type: object CompleteClaimHumaBody: additionalProperties: false properties: requestId: description: "Idempotency key for this completion, a version 4 UUID, sent verbatim to BACEN as completeClaim's RequestId. Required — never invented here. Must be version 4: every other version derives from a clock, a node id or a hashed name, so two different completions can collide by construction. Distinct from the X-Idempotency header, which is this rail's own de-duplication and never reaches BACEN." examples: - b2696bf1-0a51-48b0-ab4a-8af2dff440af format: uuid type: string required: - requestId type: object ConfirmClaimHumaBody: additionalProperties: false properties: reason: description: Confirmation reason reported to BACEN; defaults to USER_REQUESTED. enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION examples: - USER_REQUESTED type: string type: object ContactInformationResponse: additionalProperties: false properties: email: description: Regulator-facing contact email examples: - compliance@participant.example type: string phone: description: Regulator-facing contact phone examples: - "+5511999999999" type: string required: - email - phone type: object CreateCidSetFileRequest: additionalProperties: false properties: keyType: description: Key type whose CID set file BACEN builds. enum: - CPF - CNPJ - EMAIL - PHONE - EVP examples: - EMAIL type: string required: - keyType type: object CreateFraudMarkerRequest: additionalProperties: false properties: fraudType: description: "BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN" enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER - UNKNOWN examples: - MULE_ACCOUNT type: string keyValue: description: Optional plaintext Pix key of the fraudster, informed when known so the key also receives the fraud mark; a blank value is treated as absent. The clear key travels in the signed BACEN body, the operation request_body, the BACEN snapshot, the MED snapshot facts and the fraud-marker responses; the row column holds its HMAC hash. At most 77 characters, the ceiling BACEN publishes on a DICT key. examples: - usuario@example.com maxLength: 77 type: string ownerTaxId: description: "Plaintext owner tax ID (CPF/CNPJ) the marker is associated with, shaped as the SPI wire type PICpfCnpj: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ. BACEN requires it in the clear and its pattern rejects a hash, so it is sent verbatim inside the signed body. The clear value is also kept in the operation request_body, the BACEN snapshot, the MED snapshot facts and the responses." examples: - "52998224725" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string participantISPB: description: ISPB (8 digits or uppercase letters) of the participant raising the fraud marker examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string required: - ownerTaxId - participantISPB - fraudType type: object CreateFraudMarkerResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this fraud marker, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this fraud marker (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string fraudType: description: "BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN" examples: - MULE_ACCOUNT type: string id: description: BACEN-assigned fraud-marker resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440002 type: string keyValue: description: Clear Pix key value the caller informed or BACEN echoed (ExtendedFraudMarker.Key); omitted when no key is known examples: - usuario@example.com type: string keyValueHash: description: HMAC hash of the marked Pix key value (hex); empty when no key was given examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string operationId: description: Durable MED operation-intent id of the create that produced this marker; always present. examples: - 01930000-0000-7000-8000-000000000000 type: string operationStatus: description: Durable operation-intent status. COMPLETED on an ordinary create; any other value means the marker was reconciled from BACEN inline (or a replay served the row an earlier attempt wrote) and the operation is still the reconciliation's to complete (the sweep, or an operator for MANUAL_REVIEW). enum: - COMPLETED - UNKNOWN_OUTCOME - MANUAL_REVIEW - SYNC_PENDING - RESERVED - SUBMITTED - CONFIRMED examples: - COMPLETED type: string originInfractionReportId: description: BACEN-assigned infraction that originated this marker (ExtendedFraudMarker.InfractionReport.Id); omitted when there is none examples: - 550e8400-e29b-41d4-a716-446655440005 type: string originInfractionReporterISPB: description: Reporter ISPB of the originating infraction (ExtendedFraudMarker.InfractionReport.ReporterParticipant); omitted when there is none examples: - "12345678" type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string ownerTaxId: description: BACEN-observed clear owner tax ID (CPF/CNPJ) — ExtendedFraudMarker.TaxIdNumber; omitted when BACEN has never echoed one back examples: - "52998224725" type: string participantISPB: description: ISPB (8 digits or uppercase letters) of the participant that raised the fraud marker examples: - "12345678" type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string status: description: "Local fraud-marker state: ACTIVE (counts toward fraud stats) or INACTIVE (retained for audit only)" examples: - ACTIVE type: string updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - keyValueHash - participantISPB - fraudType - status - reportStatus - createdAt - updatedAt type: object CreateFundsRecoveryRequest: additionalProperties: false properties: participantISPB: description: ISPB (8 digits or uppercase letters) of the participant reporting the funds recovery; gated to the calling direct's scope examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string reportDetails: description: Details helping the counterparty PSP analyse the case; mandatory when situationType is OTHER, optional otherwise (max 2000 characters). The regulator contact travels with it, read from the participant registry. maxLength: 2000 type: string rootTransactionId: description: "Identifier of the transaction being contested: the EndToEndID of the originating fraudulent payment (pacs.008, E-prefixed), or the RtrId of the return operation being contested (pacs.004, D-prefixed — DICT 8.4 §20.1.9, contestação de transação de devolução, where the contested return becomes the root transaction). Shaped as BACEN's InstrId2Type, message-type letter upper case. BACEN dedups a recovery per RootTransactionId" examples: - E12345678202607101200B3C4D5E6F7A pattern: ^[ED][0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string situationType: description: "MED 2.0 situation classification: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, or UNKNOWN" enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string userComplaintAt: description: "The instant the paying user's complaint was registered in your service channel (Manual de Tempos do Pix v7.0 §4.2.2.7: at most 1,800 s at P95 until this opening). RFC 3339. Required. It is never sent to BACEN; it is stored with the recovery and measured against the opening. Refused with 422 when later than the instant this rail opens the recovery." examples: - "2026-07-10T11:45:00.000Z" format: date-time type: string required: - rootTransactionId - situationType - participantISPB - userComplaintAt type: object CreateRefundRequest: additionalProperties: false properties: amount: description: Refund amount as an exact decimal number; must be greater than zero examples: - 1500 exclusiveMinimum: 0 type: number endToEndId: description: "Identifier of the transaction to refund: the EndToEndID of the payment (pacs.008, E-prefixed), or the RtrId of the return operation being contested (pacs.004, D-prefixed — DICT 8.4 §20.1.9). BACEN's field overloads both message types; the prefix discriminates, and the shape is BACEN's InstrId2Type. The message-type letter must be upper case; the 11-character tail is case-insensitive. The date and minute components are additionally parsed as a real instant by the service." examples: - E12345678202607101200D3E4F5A6B7C pattern: ^[ED][0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string reason: description: BACEN refund reason. FRAUD, OPERATIONAL_FLAW or PIX_AUTOMATICO; the spec's fourth value is retired and is not accepted. enum: - FRAUD - OPERATIONAL_FLAW - PIX_AUTOMATICO examples: - FRAUD type: string refundDetails: description: Short description of why the refund is requested; mandatory when reason is OPERATIONAL_FLAW, optional otherwise (max 2000 characters). maxLength: 2000 type: string requestedByISPB: description: ISPB (8 digits or uppercase letters) of the participant requesting the refund; gated to the calling direct's scope (JRN-151) examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string required: - endToEndId - requestedByISPB - amount - reason type: object CreateSyncVerificationRequest: additionalProperties: false properties: keyType: description: Key type whose CID set is verified. enum: - CPF - CNPJ - EMAIL - PHONE - EVP examples: - CPF type: string participantSyncVerifier: description: "The participant's own sync verifier: the XOR of every active CID of this key type, 64 hex characters." examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 pattern: ^[0-9a-fA-F]{64}$ type: string required: - keyType - participantSyncVerifier type: object CreatedCidSetFileResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's operational envelope for this call; omitted when BACEN sent no correlation id. id: description: BACEN's id for the file; read it with GET cids/files/{id}. examples: - "4521" type: string keyType: description: Key type of the CID set. examples: - EMAIL type: string participant: description: ISPB whose CID set the file holds. examples: - "12345678" type: string requestTime: description: When BACEN received the request, BACEN's wire value. examples: - "2026-09-29T12:00:00.123Z" type: string status: description: "BACEN's file status, verbatim: REQUESTED, PROCESSING, AVAILABLE, UNAVAILABLE or ERROR." examples: - REQUESTED type: string required: - id - status - participant - keyType - requestTime type: object DICTClaimSummaryBucket: additionalProperties: false properties: claimType: description: Claim type (OWNERSHIP/PORTABILITY). examples: - OWNERSHIP type: string claimerISPB: description: Claiming participant ISPB for this bucket; present only when groupByParticipant=true. examples: - "12345678" type: string count: description: Record COUNT for this bucket. examples: - 5 format: int64 type: integer status: description: Claim status (OPEN/WAITING_RESOLUTION/CONFIRMED/CANCELLED/COMPLETED). examples: - OPEN type: string required: - claimType - status - count type: object DICTClaimsSummaryResponse: additionalProperties: false properties: asOf: description: The instant the open-claims-past-deadline COUNT was evaluated (RFC 3339 UTC). examples: - "2026-06-21T12:00:00Z" type: string buckets: description: COUNT(*) buckets grouped by (claimType, status) over claims requested in the window. items: $ref: "#/components/schemas/DICTClaimSummaryBucket" type: array countOnly: description: Always true — DICT summaries are COUNT-only (no monetary field). examples: - true type: boolean openClaimsPastDeadline: description: COUNT of currently-open claims whose 7-day deadline has passed (a count, never a position). Current-state, not window-filtered. examples: - 3 format: int64 type: integer window: $ref: "#/components/schemas/DICTReportWindowResponse" description: Echo of the resolved report window. required: - countOnly - buckets - openClaimsPastDeadline - asOf - window type: object DICTDiscoveryFeedListResponse: additionalProperties: false properties: abandonedCount: description: How many regulated records named operators have abandoned across all listed feeds. Permanent. examples: - 0 format: int64 type: integer blockedCount: description: How many of the listed feeds are currently frozen. examples: - 0 format: int64 type: integer heldCount: description: How many of the listed feeds are running but not covering everything — pinned on a record this deployment permanently refuses, on an entry whose BACEN resource id could not be read, or (the fraud-marker sweep) on a window left edge that stopped advancing. Each one names what it is stuck on in heldBacenRecordIds. examples: - 0 format: int64 type: integer items: description: Every DICT poll feed that can freeze, blocked or not. items: $ref: "#/components/schemas/DICTDiscoveryFeedResponse" type: array steppedOverCount: description: How many of the listed feeds carry BACEN records they permanently stepped over and never stored, awaiting replay. examples: - 0 format: int64 type: integer required: - items - blockedCount - heldCount - steppedOverCount - abandonedCount type: object DICTDiscoveryFeedResponse: additionalProperties: false properties: abandonedBacenRecordIds: description: "The abandoned records, oldest first. Permanent: nothing in this service removes an entry, so an abandonment stays visible long after the log line that recorded it is gone. Who abandoned each one, and why, is in the audit trail." items: type: string type: - array - "null" abandonedRecords: description: How many regulated records a named operator has permanently abandoned on this feed. The walk moves past exactly these records and no others; this deployment will never hold them. examples: - 1 format: int64 type: integer abandonedRecordsLimit: description: "How many records may ever be written off on one feed. Fixed, and deliberately not raised to make a refusal go away: reaching it means a human personally gave up on this many regulated records on this one feed, which is a systemic refusal rather than that many accidents." examples: - 500 format: int64 type: integer abandonedRecordsRemaining: description: "How many more records may be written off on this feed before POST /api/v1/dict/discovery-feeds/{feed}/abandon-record refuses. Zero means a record this feed is held on has no in-band ending left: it stays held and stays listed, the feed stays pinned on it, and the way out is to resolve what makes those records unstorable or to raise them with BACEN. The gauge brspi_dict_feed_abandoned_records_remaining carries the same number for alerting. It is a budget for the write-off, not a promise that this feed's current hold can use one: a feed held under window_left_edge_held or participant_not_served lists no record, so there is nothing to spend it on however many remain. Always 500 on dict_funds_recovery_events, which steps records over instead of holding them and has no write-off at all." examples: - 500 format: int64 type: integer abandonedSince: description: When the abandoned list last grew (RFC 3339, UTC); absent when it is empty. examples: - "2026-08-14T09:00:00Z" type: string blocked: description: True while the feed is frozen on its durable blocked marker. A frozen feed discovers nothing and does not clear on restart; readiness deliberately stays up so this deployment's operator routes remain reachable. examples: - false type: boolean blockedSince: description: When the freeze started (RFC 3339, UTC); absent when the feed is running. examples: - "2026-08-13T12:00:00Z" type: string feed: description: Feed name — the same string as the feed's blocked gauge, refusal counters and operational events, so every operator surface names a feed identically. It matches the feed's /readyz check name for the MED discovery and fraud-marker feeds; the two claim feeds share one readiness leg (dict_claim_feed_pagination) and so do not. examples: - dict_infraction_discovery type: string held: description: "True while the feed's window is pinned and it is not covering everything: it sits on a record this deployment permanently refuses (record_quarantined), or on an entry whose BACEN resource id could not be read at all (malformed_entry_unreadable), or the fraud-marker sweep closed a cycle without covering it so its window's left edge stays where it is (window_left_edge_held), or BACEN served entries no participant this deployment serves is party to (participant_not_served), or the donor's receipt of an OPEN claim could not be sent and the window is pinned until it lands (claim_receipt_deferred). Distinct from blocked: a hold on its own freezes nothing, and the unblock route does not apply to it because there is no durable blocked marker to clear. A hold that survives the tolerated ticks becomes a block, and then both are true. Whether an operator has anything to abandon depends on WHICH hold it is, so read heldReason before reaching for the write-off: record_quarantined and malformed_entry_unreadable name their records in heldBacenRecordIds and the write-off is their sanctioned ending; window_left_edge_held, participant_not_served and claim_receipt_deferred name none and the write-off does not apply to them at all." examples: - false type: boolean heldBacenRecordIds: description: "The records this feed is currently stuck on, oldest first: a BACEN resource id this deployment permanently refuses, the raw identifier BACEN sent for an entry whose id is not a UUID, or an 'unreadable-' handle standing in for an identifier too long or too strange to list verbatim. Anything listed here can be abandoned with POST /api/v1/dict/discovery-feeds/{feed}/abandon-record, and nothing else can. Three holds list nothing at all and have no write-off: claim_receipt_deferred, whose next tick retries the receipt for free; window_left_edge_held, which is stuck on a watched document that is kept off this list and whose only lever is resetModifiedAfter on the unblock route once the hold has escalated to a block; and participant_not_served, which clears by itself as this deployment's participant registry catches up with BACEN and must never be written off. Otherwise capped per feed, so it can be shorter than heldEntries." items: type: string type: - array - "null" heldEntries: description: "How many entries the feed is stuck on. For a record this deployment permanently refuses it is how many such records are named in heldBacenRecordIds. For an entry whose BACEN resource id could not be read it is how many the feed could not read — the last tick, for the walks that stop at the first such page; the current CYCLE, for the fraud-marker sweep, whose cycle spans several sweeps of the book: it rises as those sweeps land and settles when the cycle closes. A document a run bound cut mid-walk counts on the sweep that finishes it, never on both. A book meeting the same unreadable entry cycle after cycle keeps reporting that one entry, and heldSince keeps answering how long it has been that way. Or, for that sweep's window hold, how many documents its last dirty cycle could not cover." examples: - 1 format: int64 type: integer heldReason: description: Closed-vocabulary reason the feed is pinned; absent when it is not. examples: - malformed_entry_unreadable type: string heldSince: description: When the held count last CHANGED (RFC 3339, UTC) — a tick that finds the same count does not re-stamp it, so this reads as how long the feed has been stuck on this many entries. Absent when the window is not pinned. examples: - "2026-08-13T12:00:00Z" type: string reason: description: Closed-vocabulary reason the feed froze; absent when the feed is running. examples: - inclusive_modified_after_no_progress type: string steppedOverBacenResourceIds: description: The BACEN resource ids awaiting replay, oldest first. Replay them with POST /api/v1/dict/funds-recoveries/intake, which runs the identical pipeline; attesting on that request clears both this list and the block it raised. items: type: string type: - array - "null" steppedOverEntries: description: How many BACEN records this feed permanently stepped over and never stored, awaiting replay. examples: - 2 format: int64 type: integer steppedOverSince: description: When the replay list last grew (RFC 3339, UTC); absent when it is empty. examples: - "2026-08-13T12:00:00Z" type: string steppedOverUnlisted: description: How many stepped-over records this feed cannot name — BACEN's entity id was not a resource id, or the replay list was full when they arrived. They are missing exactly as the listed ones are, but cannot be replayed by id; raise them with BACEN. The intake attestation clears this count together with the list. examples: - 1 format: int64 type: integer required: - feed - blocked - held - abandonedRecordsLimit - abandonedRecordsRemaining type: object DICTKeySummaryBucket: additionalProperties: false properties: count: description: Record COUNT for this bucket. examples: - 128 format: int64 type: integer keyType: description: PIX key type (CPF/CNPJ/EMAIL/PHONE/EVP). examples: - CPF type: string participantISPB: description: Indirect participant ISPB for this bucket; present only when groupByParticipant=true. examples: - "12345678" type: string status: description: Key status (ACTIVE/PENDING_CLAIM). examples: - ACTIVE type: string required: - keyType - status - count type: object DICTKeysSummaryResponse: additionalProperties: false properties: buckets: description: COUNT(*) buckets grouped by (keyType, status) over keys registered in the window. items: $ref: "#/components/schemas/DICTKeySummaryBucket" type: array countOnly: description: Always true — DICT summaries are COUNT-only (no monetary field). examples: - true type: boolean window: $ref: "#/components/schemas/DICTReportWindowResponse" description: Echo of the resolved report window. required: - countOnly - buckets - window type: object DICTPolicyBucketResponse: additionalProperties: false properties: availableTokens: description: Fichas left in the bucket at the instant BACEN answered. Not a live counter — re-read it. examples: - 49985 format: int64 type: integer capacity: description: The bucket's total size. examples: - 50000 format: int64 type: integer name: description: BACEN's own policy name, verbatim. examples: - ENTRIES_READ_PARTICIPANT_ANTISCAN type: string refillPeriodSec: description: The refill period, in seconds. examples: - 60 format: int64 type: integer refillTokens: description: Fichas BACEN puts back each refillPeriodSec. examples: - 25000 format: int64 type: integer required: - name - availableTokens - capacity - refillTokens - refillPeriodSec type: object DICTPolicyBucketsResponse: additionalProperties: false properties: category: description: The request-limiting category the BCB assigned this participant (A→H), which fixes the size and refill of the key-query bucket. The BCB assigns it and communicates changes; a letter outside A→H is reported verbatim rather than hidden, and is logged as an anomaly. examples: - A type: string correlationId: description: BACEN's own correlation identifier for this read, for operational support. examples: - B20220902101925801123456781A6998 type: string policies: description: The buckets BACEN reported — every policy on the unfiltered read, exactly one when a policy name was supplied. items: $ref: "#/components/schemas/DICTPolicyBucketResponse" type: array responseTime: description: When BACEN answered (RFC 3339, UTC) — the instant the reported bucket states were true. examples: - "2026-08-21T13:19:25Z" type: string required: - category - policies type: object DICTQueryBlockRequest: additionalProperties: false properties: justification: description: "Why this end user is being blocked or released — the verified suspicion section 13.2.3 conditions the act on, in the operator's own words. Recorded in the audit trail under the caller's identity. Operator prose only: never a tax id, a Pix key, an account or a holder name." maxLength: 384 minLength: 8 type: string payerId: description: The end user's CPF (digits) or CNPJ (alphanumeric, IN RFB 2.229/2024) — the same identifier their key queries carry in PI-PayerId and the monitor read reports. examples: - "12345678901" pattern: ^([0-9]{11}|[A-Za-z0-9]{12}[0-9]{2})$ type: string required: - payerId - justification type: object DICTQueryBlockResponse: additionalProperties: false properties: actor: description: The operator who placed the block. examples: - user:fred type: string blockedAt: description: When the block was placed (RFC 3339, UTC). examples: - "2026-08-21T13:19:25Z" type: string justification: description: Why the block was placed, in the operator's own words. examples: - read-attack pattern confirmed with the fraud team type: string payerId: description: The blocked end user's CPF or CNPJ (the CNPJ may carry letters). examples: - "12345678901" type: string required: - payerId type: object DICTQueryBlockResultResponse: additionalProperties: false properties: alreadyApplied: description: True when the end user was already on the requested side and nothing changed. The call is a success either way and is still audited under the caller's identity, so re-sending a request whose response was lost is safe. type: boolean blocked: description: Whether this end user's DICT key queries are blocked after the call. examples: - true type: boolean payerId: description: CPF or CNPJ of the end user this call acted on. examples: - "12345678901" type: string required: - payerId - blocked type: object DICTQueryMonitorResponse: additionalProperties: false properties: blocks: description: Blocks currently in force, newest first. Read from the live block list rather than from the audit trail, so it is always the effect actually in place. items: $ref: "#/components/schemas/DICTQueryBlockResponse" type: array participant: $ref: "#/components/schemas/DICTQueryParticipantIndicatorsResponse" description: Both indicators for the PSP as a whole. suspects: description: "End users whose own NOT FOUND ratio breached the per-user threshold over at least the minimum query count, worst first. A listing is an indication to verify, never a verdict: section 13.2.3 requires a human to establish that the behaviour is unjustified before anyone is blocked." items: $ref: "#/components/schemas/DICTQuerySuspectResponse" type: array thresholds: $ref: "#/components/schemas/DICTQueryThresholdsResponse" description: The parameters this deployment judges against. windowFrom: description: Start of the assessed window (RFC 3339, UTC). examples: - "2026-08-20T14:00:00Z" type: string windowTo: description: End of the assessed window (RFC 3339, UTC) — the instant it was read. examples: - "2026-08-21T13:19:25Z" type: string required: - windowFrom - windowTo - thresholds - participant - suspects - blocks type: object DICTQueryParticipantIndicatorsResponse: additionalProperties: false properties: found: description: Key queries the DICT answered FOUND (HTTP 200) in the window. examples: - 9400 format: int64 type: integer noPaymentOrderInWindow: description: True when the window holds key queries and not one payment order, which is what makes the VCD/EOS ratio undefined rather than merely large. examples: - false type: boolean notFound: description: Key queries the DICT answered NOT FOUND (HTTP 404) in the window. examples: - 600 format: int64 type: integer notFoundBasisPoints: description: "NOT FOUND/(NOT FOUND+FOUND) in basis points: 600 is 6%. Footnote 15 treats percentages above 7% for the participant as a good indication of suspicious behaviour." examples: - 600 format: int64 type: integer notFoundBreached: description: True when the ratio exceeded the configured participant threshold over at least the configured minimum query count. examples: - false type: boolean orderRatioBasisPoints: description: "Key queries per payment order (VCD/EOS) in basis points: 12195 is 1.22. Footnote 14 treats values near or above 2 as anomalous. A window holding queries and no payment order at all is undefined and reports an unreachable value." examples: - 12195 format: int64 type: integer orderRatioBreached: description: True when VCD/EOS reached the configured threshold over at least the configured minimum query count. examples: - false type: boolean paymentOrders: description: Payment orders this rail sent to the SPI in the window — the EOS of section 13.2.3. examples: - 8200 format: int64 type: integer queries: description: Total key queries in the window — the VCD of section 13.2.3. examples: - 10000 format: int64 type: integer required: - paymentOrders - notFoundBasisPoints - notFoundBreached - orderRatioBasisPoints - noPaymentOrderInWindow - orderRatioBreached - found - notFound - queries type: object DICTQuerySuspectResponse: additionalProperties: false properties: found: description: Key queries the DICT answered FOUND for this end user in the window. examples: - 60 format: int64 type: integer notFound: description: Key queries the DICT answered NOT FOUND for this end user in the window. examples: - 140 format: int64 type: integer notFoundBasisPoints: description: "This end user's own NOT FOUND ratio in basis points: 7000 is 70%." examples: - 7000 format: int64 type: integer payerId: description: "The end user's CPF or CNPJ (the CNPJ may carry letters), in clear: what identifies the subject to the block verb." examples: - "12345678901" type: string required: - payerId - found - notFound - notFoundBasisPoints type: object DICTQueryThresholdsResponse: additionalProperties: false properties: orderRatioBasisPoints: description: "VCD/EOS threshold in basis points (manual default: 20000, i.e. 2.0)." examples: - 20000 format: int64 type: integer participantMinQueries: description: Queries below which the participant ratio is not judged. The manual states no participant floor — it states one only per user — so this is a parameter section 13.2.3 leaves to the participant. examples: - 100 format: int64 type: integer participantNotFoundBasisPoints: description: "Participant NOT FOUND threshold in basis points (manual default: 700, i.e. 7%)." examples: - 700 format: int64 type: integer payerMinQueries: description: "Footnote 15's own floor, verbatim: an end user is judged only from 100 queries in the last 24 hours. It is a rule, not a rounding — 99 queries are not judged at all." examples: - 100 format: int64 type: integer payerNotFoundBasisPoints: description: "Per-user NOT FOUND threshold in basis points (manual default: 2000, i.e. 20%)." examples: - 2000 format: int64 type: integer windowHours: description: The rolling window both indicators are measured over. examples: - 24 format: int64 type: integer required: - windowHours - participantNotFoundBasisPoints - participantMinQueries - payerNotFoundBasisPoints - payerMinQueries - orderRatioBasisPoints type: object DICTReportWindowResponse: 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 DeleteKeyRequest: additionalProperties: false properties: keyValue: description: PIX key value identifying the key to delete, in its canonical format for the key type. At most 77 characters, the ceiling BACEN publishes on a DICT key. examples: - "12345678901" maxLength: 77 minLength: 1 type: string participantISPB: description: ISPB of the participant the key is bound to. Must be the key's stored owning participant and a participant this deployment is authorized to act for; any other value is rejected. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string reason: description: "Deletion reason reported to BACEN, defaulting to USER_REQUESTED; the enum is the set deleteEntry accepts. FRAUD and RFB_VALIDATION are MANDATED by DICT 8.4 section 4.1 for a removal forced by incompatibility with the Receita Federal registry — FRAUD when the name divergence or the irregular CPF/CNPJ is fraud, RFB_VALIDATION in the other cases. ACCOUNT_CLOSURE, RECONCILIATION, FRAUD and RFB_VALIDATION are participant-initiated (sections 4.4/4.5): no end user asks, so requesterTaxId is not demanded for them." enum: - USER_REQUESTED - ACCOUNT_CLOSURE - RECONCILIATION - FRAUD - RFB_VALIDATION examples: - USER_REQUESTED type: string requesterTaxId: description: "CPF or CNPJ of the END USER asking for the removal. MANDATORY when reason is USER_REQUESTED (the default): DICT 8.4 section 4.2 obliges the PSP to check that the user requesting the exclusão is the user the key is bound to. Omitted for the PSP-initiated reasons — ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, RFB_VALIDATION — where no end user is asking; supplied on any of them it is still compared against the stored owner. A value that does not match the stored owner is refused with the same answer as an unauthorized participant, so this route cannot be used to discover who owns a key." examples: - "12345678901" type: string required: - keyValue - participantISPB 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 EntryStatisticsResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for this call (this surface is a live pass-through with no local row; the envelope reflects THIS request, not a persisted last interaction). key: description: Pix key the statistics belong to examples: - "11122233300" type: string keyStatistics: $ref: "#/components/schemas/StatisticsBlocksResponse" description: Key-scoped statistics (verbatim) ownerStatistics: $ref: "#/components/schemas/StatisticsBlocksResponse" description: Owner-scoped statistics (verbatim) required: - key - ownerStatistics - keyStatistics 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 FraudMarkerListResponse: additionalProperties: false properties: items: description: Minimized fraud markers for the requested limit/offset window. items: $ref: "#/components/schemas/FraudMarkerResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object FraudMarkerMutationResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this fraud marker, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this fraud marker (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string fraudType: description: "BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN" examples: - MULE_ACCOUNT type: string id: description: BACEN-assigned fraud-marker resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440002 type: string keyValue: description: Clear Pix key value the caller informed or BACEN echoed (ExtendedFraudMarker.Key); omitted when no key is known examples: - usuario@example.com type: string keyValueHash: description: HMAC hash of the marked Pix key value (hex); empty when no key was given examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string operationId: description: "Durable MED operation-intent id: the operation that produced this resource's current state. Present on both a synchronous 200/201 and a pending 202." examples: - 01930000-0000-7000-8000-000000000000 type: string operationStatus: description: Durable operation-intent status. Always COMPLETED on a synchronous 200/201; on a pending 202 it is never REJECTED or LOCAL_FAILURE — both are BACEN-final/local-final outcomes mapped to their own HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED examples: - UNKNOWN_OUTCOME type: string originInfractionReportId: description: BACEN-assigned infraction that originated this marker (ExtendedFraudMarker.InfractionReport.Id); omitted when there is none examples: - 550e8400-e29b-41d4-a716-446655440005 type: string originInfractionReporterISPB: description: Reporter ISPB of the originating infraction (ExtendedFraudMarker.InfractionReport.ReporterParticipant); omitted when there is none examples: - "12345678" type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string ownerTaxId: description: BACEN-observed clear owner tax ID (CPF/CNPJ) — ExtendedFraudMarker.TaxIdNumber; omitted when BACEN has never echoed one back examples: - "52998224725" type: string participantISPB: description: ISPB (8 digits or uppercase letters) of the participant that raised the fraud marker examples: - "12345678" type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string status: description: "Local fraud-marker state: ACTIVE (counts toward fraud stats) or INACTIVE (retained for audit only)" examples: - ACTIVE type: string updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - keyValueHash - participantISPB - fraudType - status - reportStatus - createdAt - updatedAt type: object FraudMarkerResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this fraud marker, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this fraud marker (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string fraudType: description: "BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN" examples: - MULE_ACCOUNT type: string id: description: BACEN-assigned fraud-marker resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440002 type: string keyValue: description: Clear Pix key value the caller informed or BACEN echoed (ExtendedFraudMarker.Key); omitted when no key is known examples: - usuario@example.com type: string keyValueHash: description: HMAC hash of the marked Pix key value (hex); empty when no key was given examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string originInfractionReportId: description: BACEN-assigned infraction that originated this marker (ExtendedFraudMarker.InfractionReport.Id); omitted when there is none examples: - 550e8400-e29b-41d4-a716-446655440005 type: string originInfractionReporterISPB: description: Reporter ISPB of the originating infraction (ExtendedFraudMarker.InfractionReport.ReporterParticipant); omitted when there is none examples: - "12345678" type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string ownerTaxId: description: BACEN-observed clear owner tax ID (CPF/CNPJ) — ExtendedFraudMarker.TaxIdNumber; omitted when BACEN has never echoed one back examples: - "52998224725" type: string participantISPB: description: ISPB (8 digits or uppercase letters) of the participant that raised the fraud marker examples: - "12345678" type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string status: description: "Local fraud-marker state: ACTIVE (counts toward fraud stats) or INACTIVE (retained for audit only)" examples: - ACTIVE type: string updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - keyValueHash - participantISPB - fraudType - status - reportStatus - createdAt - updatedAt type: object FraudMarkerSearchResponse: additionalProperties: false properties: hasMore: description: "BACEN's HasMoreElements: more markers match than this page carries." type: boolean items: description: The participant's own fraud markers BACEN answered for the filters, as BACEN projects them. Nothing is stored locally. participantISPB is the searched participant (listFraudMarkers answers only that participant's markers); status uses the local vocabulary (REGISTERED -> ACTIVE, CANCELLED -> INACTIVE); keyValueHash and reportStatus are empty because the markers are not local records; createdAt and updatedAt are BACEN's CreationTime and LastModified. items: $ref: "#/components/schemas/FraudMarkerResponse" type: array requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - hasMore type: object FraudStatsResponse: additionalProperties: false properties: activeMarkers: description: Number of ACTIVE fraud markers contributing to fraud statistics examples: - 8 format: int64 type: integer inactiveMarkers: description: Number of INACTIVE fraud markers retained for audit only examples: - 2 format: int64 type: integer totalMarkers: description: Total number of fraud markers in scope (active plus inactive) examples: - 10 format: int64 type: integer required: - totalMarkers - activeMarkers - inactiveMarkers type: object FundsRecoveryIntakeRequest: additionalProperties: false properties: attestGapRecovered: description: "Set to true to declare that the recoveries this deployment is missing — those lost to a blocked convergence gap, and those on the feed's stepped-over replay list — have now been supplied. It clears the block and empties the replay list in full, including ids this request did not carry. Every id it erases is written to the audit log by name first, along with the size of the whole inventory, so a recovery nobody ever supplied stays nameable after the list is gone. It is an assertion by the caller, recorded under the caller's identity: nothing verifies it, and nothing else lifts the block." type: boolean bacenResourceIds: description: BACEN-assigned funds-recovery UUIDs the client holds from its own records. Each one is fetched from BACEN and applied through the canonical snapshot pipeline. Any age and any status is accepted — this is precisely the inventory the seven-day event-notification window cannot reveal. items: type: string maxItems: 50 minItems: 1 type: - array - "null" required: - bacenResourceIds type: object FundsRecoveryIntakeResponse: additionalProperties: false properties: gapBlockCleared: description: True when this request carried an attestation and the convergence-gap block was cleared. type: boolean results: description: One entry per supplied id, in the order supplied. items: $ref: "#/components/schemas/FundsRecoveryIntakeResult" type: array required: - results type: object FundsRecoveryIntakeResult: additionalProperties: false properties: bacenResourceId: description: The supplied BACEN funds-recovery id. format: uuid type: string outcome: description: "materialized: no local record existed and BACEN's snapshot became this resource's first observation. applied: BACEN's snapshot was newer than the stored one and replaced it. deduped: the stored snapshot is already BACEN's current one — nothing written, no second event. ignored: BACEN served an older snapshot than the stored one. not_found: BACEN does not serve us a recovery with this id. unmaterializable: BACEN's snapshot cannot be stored as a local record. failed: the attempt did not complete (BACEN unreachable or a write failure) — retry the id." enum: - materialized - applied - deduped - ignored - not_found - unmaterializable - failed type: string required: - bacenResourceId - outcome type: object FundsRecoveryListResponse: additionalProperties: false properties: items: description: Local DICT funds-recovery records for the requested limit/offset window. items: $ref: "#/components/schemas/FundsRecoveryResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object FundsRecoveryMutationResponse: additionalProperties: false properties: analysisAcceptedAt: description: "When the analysis step was observed to complete — the instant the 72-hour refund window opens (RFC 3339, UTC). Absent until observed. When no BACEN snapshot stated the transition, this is the DICT's notification-creation instant instead: an upper bound on it, so the window shown here never closes earlier than the one the DICT counts." examples: - "2026-06-14T12:00:00Z" type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this funds recovery, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this funds recovery (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string bacenReporterParticipant: description: BACEN-assigned reporter participant ISPB (ExtendedFundsRecovery.ReporterParticipant); empty until BACEN answers examples: - "12345678" type: string completion: description: "Why a COMPLETED recovery completed: REFUNDED (the refund step was observed to start), REFUND_DEADLINE_LAPSED (no refund step was observed and the DICT concluded it at or after the 72 hours), or UNKNOWN (nothing observed here explains it — the analysis step was never seen, or the DICT concluded it before the deadline, which a refund impossibility, an all-rejected notification set, an unobserved refund and a lapse concluded just inside a window anchored on the DICT's notification-creation instant all explain equally). Absent while the recovery is not COMPLETED." enum: - REFUNDED - REFUND_DEADLINE_LAPSED - UNKNOWN examples: - REFUNDED type: string contactInformation: $ref: "#/components/schemas/ContactInformationResponse" description: BACEN-echoed regulator-facing contact createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string flowType: description: ExtendedFundsRecovery.FlowType, verbatim (BACEN's spec defines only AUTOMATED); not actionable examples: - AUTOMATED type: string id: description: BACEN-assigned funds-recovery resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440003 type: string operationId: description: "Durable MED operation-intent id: the operation that produced this resource's current state. Present on both a synchronous 200/201 and a pending 202." examples: - 01930000-0000-7000-8000-000000000000 type: string operationStatus: description: Durable operation-intent status. Always COMPLETED on a synchronous 200/201; on a pending 202 it is never REJECTED or LOCAL_FAILURE — both are BACEN-final/local-final outcomes mapped to their own HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED examples: - UNKNOWN_OUTCOME type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string refundDeadlineAt: description: When the 72-hour window to start the refund step closes (RFC 3339, UTC); the DICT concludes the recovery itself after it. Absent until the analysis step has been observed. examples: - "2026-06-17T12:00:00Z" type: string reportDetails: description: Details for the counterparty PSP's analysis; present when the situation type carries one type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string reporterParticipant: description: ISPB of the participant that reported this funds recovery — our own configured value, the same one createFundsRecovery sends as Participant. This is a LOCAL value, distinct from bacenReporterParticipant below. examples: - "12345678" type: string rootTransactionId: description: "Identifier of the contested transaction: the originating fraudulent payment's EndToEndID (pacs.008, E-prefixed) or the contested return operation's RtrId (pacs.004, D-prefixed — a contestação de transação de devolução), projected verbatim" examples: - E12345678202607101200B3C4D5E6F7A type: string situationType: description: MED 2.0 situation classification examples: - SCAM type: string status: description: "Local funds-recovery lifecycle state: CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, or CANCELLED. This is a LOCAL view: TRACKED is representable but this rail has no producer for it, so it never appears in practice." examples: - CREATED type: string updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - rootTransactionId - situationType - status - reportStatus - reporterParticipant - createdAt - updatedAt type: object FundsRecoveryResponse: additionalProperties: false properties: analysisAcceptedAt: description: "When the analysis step was observed to complete — the instant the 72-hour refund window opens (RFC 3339, UTC). Absent until observed. When no BACEN snapshot stated the transition, this is the DICT's notification-creation instant instead: an upper bound on it, so the window shown here never closes earlier than the one the DICT counts." examples: - "2026-06-14T12:00:00Z" type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this funds recovery, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this funds recovery (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string bacenReporterParticipant: description: BACEN-assigned reporter participant ISPB (ExtendedFundsRecovery.ReporterParticipant); empty until BACEN answers examples: - "12345678" type: string completion: description: "Why a COMPLETED recovery completed: REFUNDED (the refund step was observed to start), REFUND_DEADLINE_LAPSED (no refund step was observed and the DICT concluded it at or after the 72 hours), or UNKNOWN (nothing observed here explains it — the analysis step was never seen, or the DICT concluded it before the deadline, which a refund impossibility, an all-rejected notification set, an unobserved refund and a lapse concluded just inside a window anchored on the DICT's notification-creation instant all explain equally). Absent while the recovery is not COMPLETED." enum: - REFUNDED - REFUND_DEADLINE_LAPSED - UNKNOWN examples: - REFUNDED type: string contactInformation: $ref: "#/components/schemas/ContactInformationResponse" description: BACEN-echoed regulator-facing contact createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string flowType: description: ExtendedFundsRecovery.FlowType, verbatim (BACEN's spec defines only AUTOMATED); not actionable examples: - AUTOMATED type: string id: description: BACEN-assigned funds-recovery resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440003 type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string refundDeadlineAt: description: When the 72-hour window to start the refund step closes (RFC 3339, UTC); the DICT concludes the recovery itself after it. Absent until the analysis step has been observed. examples: - "2026-06-17T12:00:00Z" type: string reportDetails: description: Details for the counterparty PSP's analysis; present when the situation type carries one type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string reporterParticipant: description: ISPB of the participant that reported this funds recovery — our own configured value, the same one createFundsRecovery sends as Participant. This is a LOCAL value, distinct from bacenReporterParticipant below. examples: - "12345678" type: string rootTransactionId: description: "Identifier of the contested transaction: the originating fraudulent payment's EndToEndID (pacs.008, E-prefixed) or the contested return operation's RtrId (pacs.004, D-prefixed — a contestação de transação de devolução), projected verbatim" examples: - E12345678202607101200B3C4D5E6F7A type: string situationType: description: MED 2.0 situation classification examples: - SCAM type: string status: description: "Local funds-recovery lifecycle state: CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, or CANCELLED. This is a LOCAL view: TRACKED is representable but this rail has no producer for it, so it never appears in practice." examples: - CREATED type: string updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - rootTransactionId - situationType - status - reportStatus - reporterParticipant - createdAt - updatedAt type: object GetPersonStatisticsRequest: additionalProperties: false properties: taxId: description: Subject CPF (11 digits) or CNPJ ([0-9A-Z]{12}[0-9]{2}). pattern: ^(?:[0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string required: - taxId type: object InfractionListResponse: additionalProperties: false properties: items: description: Local DICT infraction records for the requested limit/offset window. items: $ref: "#/components/schemas/InfractionResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object InfractionMutationResponse: additionalProperties: false properties: acknowledgedAt: description: When a human acknowledged the notification (RFC 3339, UTC) — the local evidence that a person, not a scheduler, declared it received. Absent while status is OPEN. examples: - "2026-06-20T10:00:00Z" type: string analysisDeadlineAt: description: When the DICT 8.4 §20.3 seven-day analysis window closes (RFC 3339, UTC), counted from bacenCreationTime. Absent while BACEN's creation instant has not been observed — an unknown anchor is not a deadline, and a local clock would put the deadline later than the one BACEN counts. examples: - "2026-06-21T12:00:00Z" type: string analysisDetails: description: Free-text analysis details accompanying analysisResult; omitted until close (ours or the counterparty's, via refresh) type: string analysisResult: description: "closeInfractionReport analysis outcome: AGREED or DISAGREED; omitted until close (ours or the counterparty's, via refresh)" enum: - AGREED - DISAGREED examples: - AGREED type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this infraction, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this infraction notification (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string contactInformation: $ref: "#/components/schemas/ContactInformationResponse" description: BACEN-echoed regulator-facing contact counterpartyISPB: description: BACEN-assigned counterparty participant ISPB (ExtendedInfractionReport.CounterpartyParticipant) examples: - "87654321" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string discoveredAt: description: When THIS deployment first observed a notification created elsewhere (RFC 3339, UTC). Read against analysisDeadlineAt it separates an operator who did not act on a notification held for six days from a rail that discovered it minutes ago already six days old — a blocked feed or a deployment that was down. Absent for a notification this rail itself reported. examples: - "2026-06-20T09:00:00Z" type: string endToEndId: description: BACEN end-to-end identifier (E2E ID) of the disputed PIX transaction examples: - E12345678202607101200D3E4F5A6B7C type: string fraudMarkerId: description: BACEN-assigned fraud marker id, present only after an AGREED close examples: - 550e8400-e29b-41d4-a716-446655440002 type: string fundsRecoveryId: description: BACEN-assigned funds-recovery id this infraction is linked to (MED 2.0); omitted for a standalone infraction examples: - 550e8400-e29b-41d4-a716-446655440003 type: string id: description: BACEN-assigned infraction resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: BACEN-reported blockable amount, exact decimal (ExtendedInfractionReport.InfractionAmount); absent when BACEN's response omitted it examples: - 1500 type: number operationId: description: "Durable MED operation-intent id: the operation that produced this resource's current state. Present on both a synchronous 200/201 and a pending 202." examples: - 01930000-0000-7000-8000-000000000000 type: string operationStatus: description: Durable operation-intent status. Always COMPLETED on a synchronous 200/201; on a pending 202 it is never REJECTED or LOCAL_FAILURE — both are BACEN-final/local-final outcomes mapped to their own HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED examples: - UNKNOWN_OUTCOME type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string reason: description: "BACEN infraction notification reason: REFUND_REQUEST or REFUND_CANCELLED" examples: - REFUND_REQUEST type: string reportDetails: description: Detail supplied for the counterparty PSP's analysis; present when the situation carries one type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string reportedByISPB: description: ISPB (8 digits or uppercase letters) of the participant that reported the infraction examples: - "12345678" type: string reporterISPB: description: BACEN-assigned reporter (payer) participant ISPB (ExtendedInfractionReport.ReporterParticipant) examples: - "12345678" type: string situationType: description: "Situation that gave rise to the infraction: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, or UNKNOWN" examples: - SCAM type: string status: description: "Local infraction lifecycle state: OPEN, ACKNOWLEDGED, CLOSED, or CANCELLED" examples: - OPEN type: string transactionDepth: description: "MED tracking-graph layer of the disputed transaction (DICT 8.5 TransactionDepth): 1 for the root transaction, 2 for the second layer, and so on. Absent when BACEN has not stated a layer — notably for notifications answered before the 2026-10-26 vigencia." examples: - 1 format: int64 minimum: 1 type: integer updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - endToEndId - reportedByISPB - reason - situationType - status - reportStatus - createdAt - updatedAt type: object InfractionResponse: additionalProperties: false properties: acknowledgedAt: description: When a human acknowledged the notification (RFC 3339, UTC) — the local evidence that a person, not a scheduler, declared it received. Absent while status is OPEN. examples: - "2026-06-20T10:00:00Z" type: string analysisDeadlineAt: description: When the DICT 8.4 §20.3 seven-day analysis window closes (RFC 3339, UTC), counted from bacenCreationTime. Absent while BACEN's creation instant has not been observed — an unknown anchor is not a deadline, and a local clock would put the deadline later than the one BACEN counts. examples: - "2026-06-21T12:00:00Z" type: string analysisDetails: description: Free-text analysis details accompanying analysisResult; omitted until close (ours or the counterparty's, via refresh) type: string analysisResult: description: "closeInfractionReport analysis outcome: AGREED or DISAGREED; omitted until close (ours or the counterparty's, via refresh)" enum: - AGREED - DISAGREED examples: - AGREED type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this infraction, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this infraction notification (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string contactInformation: $ref: "#/components/schemas/ContactInformationResponse" description: BACEN-echoed regulator-facing contact counterpartyISPB: description: BACEN-assigned counterparty participant ISPB (ExtendedInfractionReport.CounterpartyParticipant) examples: - "87654321" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string discoveredAt: description: When THIS deployment first observed a notification created elsewhere (RFC 3339, UTC). Read against analysisDeadlineAt it separates an operator who did not act on a notification held for six days from a rail that discovered it minutes ago already six days old — a blocked feed or a deployment that was down. Absent for a notification this rail itself reported. examples: - "2026-06-20T09:00:00Z" type: string endToEndId: description: BACEN end-to-end identifier (E2E ID) of the disputed PIX transaction examples: - E12345678202607101200D3E4F5A6B7C type: string fraudMarkerId: description: BACEN-assigned fraud marker id, present only after an AGREED close examples: - 550e8400-e29b-41d4-a716-446655440002 type: string fundsRecoveryId: description: BACEN-assigned funds-recovery id this infraction is linked to (MED 2.0); omitted for a standalone infraction examples: - 550e8400-e29b-41d4-a716-446655440003 type: string id: description: BACEN-assigned infraction resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: BACEN-reported blockable amount, exact decimal (ExtendedInfractionReport.InfractionAmount); absent when BACEN's response omitted it examples: - 1500 type: number originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string reason: description: "BACEN infraction notification reason: REFUND_REQUEST or REFUND_CANCELLED" examples: - REFUND_REQUEST type: string reportDetails: description: Detail supplied for the counterparty PSP's analysis; present when the situation carries one type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string reportedByISPB: description: ISPB (8 digits or uppercase letters) of the participant that reported the infraction examples: - "12345678" type: string reporterISPB: description: BACEN-assigned reporter (payer) participant ISPB (ExtendedInfractionReport.ReporterParticipant) examples: - "12345678" type: string situationType: description: "Situation that gave rise to the infraction: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, or UNKNOWN" examples: - SCAM type: string status: description: "Local infraction lifecycle state: OPEN, ACKNOWLEDGED, CLOSED, or CANCELLED" examples: - OPEN type: string transactionDepth: description: "MED tracking-graph layer of the disputed transaction (DICT 8.5 TransactionDepth): 1 for the root transaction, 2 for the second layer, and so on. Absent when BACEN has not stated a layer — notably for notifications answered before the 2026-10-26 vigencia." examples: - 1 format: int64 minimum: 1 type: integer updatedAt: description: Last update timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string required: - id - endToEndId - reportedByISPB - reason - situationType - status - reportStatus - createdAt - updatedAt type: object InitiateClaimRequest: additionalProperties: false properties: claimType: description: "Claim kind: OWNERSHIP (dispute the current owner) or PORTABILITY (move an existing key to this participant)" enum: - OWNERSHIP - PORTABILITY examples: - OWNERSHIP type: string claimerAccountNumber: description: Claimer account number, 1 to 20 digits, the key would be bound to. BACEN admits letters here; this rail does not, and the door states the narrower rule it applies. examples: - "9988776" pattern: ^[0-9]{1,20}$ type: string claimerAccountType: description: "Claimer account type: CACC, SVGS, TRAN, SLRY, or OTHR." enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string claimerBranch: description: Claimer account branch (1..4 digits), optional. examples: - "0001" type: string claimerName: description: Full legal name (CPF) or company name (CNPJ) of the claiming key owner, at most 150 characters (BACEN DICT 2.12.1 Person.Name). examples: - João Silva maxLength: 150 minLength: 1 type: string claimerOpeningDate: description: Claimer account opening date, RFC 3339. examples: - "2020-01-15T00:00:00Z" format: date-time type: string claimerTaxId: description: "Claimer tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024). Its length selects the BACEN person type, and the check digits are verified by the service." examples: - "12345678901" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string claimerTradeName: description: Claimer trade name (legal-entity claimers), optional. examples: - Silva ME type: string keyType: description: "PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP. Not every (claimType, keyType) pair is accepted: OWNERSHIP is claimable on PHONE only; PORTABILITY is claimable on CPF, CNPJ, PHONE, or EMAIL; EVP is claimable on neither." enum: - CPF - CNPJ - EMAIL - PHONE - EVP examples: - PHONE type: string keyValue: description: "PIX key value being claimed (format depends on keyType: CPF, CNPJ, EMAIL, PHONE, or EVP). At most 77 characters, the ceiling BACEN publishes on a DICT key; the per-type shape is applied by the service, since one schema pattern cannot depend on keyType." examples: - "+5511999999999" maxLength: 77 minLength: 1 type: string required: - claimType - keyValue - keyType - claimerName - claimerTaxId - claimerAccountNumber - claimerAccountType - claimerOpeningDate type: object KeyListResponse: additionalProperties: false properties: items: description: PIX keys for the requested limit/offset window. items: $ref: "#/components/schemas/PIXKeyResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object KeyStatsResponse: additionalProperties: false properties: byStatus: additionalProperties: format: int64 type: integer description: Key counts grouped by lifecycle status (ACTIVE, PENDING_CLAIM). type: object byType: additionalProperties: format: int64 type: integer description: Key counts grouped by key type (CPF, CNPJ, EMAIL, PHONE, EVP). type: object generatedAt: description: Timestamp the statistics snapshot was generated, RFC 3339 (UTC). examples: - "2025-03-07T14:30:00Z" type: string total: description: Total number of PIX keys in scope. examples: - 10 format: int64 type: integer required: - total - byType - byStatus - generatedAt type: object LookupKeyRequest: additionalProperties: false properties: endToEndId: description: "EndToEndId the pacs.008 this query feeds will carry (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 it feeds accepts. Required: it is BACEN's own rate-limiting key for the query, and the id under which the ficha this query spends is credited back once the payment order is sent." examples: - E1234567820260220123456789012350 pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$ type: string includeStatistics: description: Opt into BACEN antifraud statistics blocks (ownerStatistics/keyStatistics) inline on the answer. Default false — trades one fewer round-trip on the payment path for a heavier response; has no effect when the key resolves from this deployment's own records, and forces a fresh directory query for a key that does not. examples: - false type: boolean keyValue: description: PIX key value to look up, in its canonical format for the key type. At most 77 characters, the ceiling BACEN publishes on a DICT key. examples: - "12345678901" maxLength: 77 minLength: 1 type: string payerId: description: "CPF (11 digits) or CNPJ (14 alphanumeric characters, any case: upper-cased on receipt) of the end user originating this query — the payer of the payment order it feeds. Required: BACEN bills the query to this user's own request-limiting bucket, and every query by the same end user must carry the same identifier." examples: - "12345678901" pattern: ^([0-9]{11}|[A-Za-z0-9]{12}[0-9]{2})$ type: string requestingParticipant: description: "Who is asking, when it is not this deployment: an indirect participant's own ISPB (DICT 8.4 R079). Must be a participant this deployment is authorized to query for — its own direct, or an active indirect it sponsors; any other value is rejected, because BACEN bills the query and its antiscan debit to whoever this names. Omit and this deployment's own ISPB is sent." examples: - "12345678" pattern: ^[A-Za-z0-9]{8}$ type: string required: - keyValue - payerId - endToEndId type: object PIXKeyLookupResponse: additionalProperties: false properties: accountNumber: description: Account number (1..20 digits), omitted for a tuple-less key. examples: - "9988776" type: string accountType: description: BACEN account type (CACC, SVGS, TRAN, SLRY, OTHR), omitted for a tuple-less key. enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this key. A foreign key resolved live off BACEN carries the envelope of that very call. Omitted only when no BACEN interaction has ever landed on this key. branch: description: Account branch (1..4 digits), omitted when unset. examples: - "0001" type: string createdAt: description: Key creation timestamp, RFC 3339 (UTC) — OUR row's local timestamp, not BACEN's; see creationDate for BACEN's own binding-creation instant. examples: - "2025-03-07T14:30:00Z" type: string creationDate: description: "BACEN's own creation instant for this key/account/owner binding: decoded from this lookup's answer for a foreign key, or stamped from createEntry's answer for a key this deployment registered. Omitted when BACEN never published one." examples: - "2020-01-15T00:00:00Z" format: date-time type: string id: description: Unique PIX key identifier (UUID) assigned by the service. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string keyOwnershipDate: description: Instant from which the owner has held uninterrupted possession of this key per BACEN; may differ from creationDate after a portability. Same availability as creationDate. examples: - "2020-01-15T00:00:00Z" format: date-time type: string keyStatistics: $ref: "#/components/schemas/StatisticsBlocksResponse" description: Key-scoped BACEN antifraud statistics (verbatim), present only when the request opted in via includeStatistics and the lookup resolved live off BACEN DICT. keyType: description: "PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key)." examples: - CPF type: string keyValue: description: PIX key value in its canonical format for the key type. examples: - "12345678901" type: string openClaimCreationDate: description: When the key's current open ownership/portability claim started, per BACEN; omitted when no claim is open at answer time or the lookup did not resolve live off BACEN DICT. examples: - "2026-08-01T00:00:00Z" format: date-time type: string openingDate: description: Account opening date, RFC 3339, omitted for a tuple-less key. examples: - "2020-01-15T00:00:00Z" format: date-time type: string ownerName: description: Full legal name of the key owner. examples: - João Silva type: string ownerStatistics: $ref: "#/components/schemas/StatisticsBlocksResponse" description: Owner-scoped BACEN antifraud statistics (verbatim), present only when the request opted in via includeStatistics and the lookup resolved live off BACEN DICT. ownerTaxId: description: "Owner tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024); returned full and unmasked per BACEN API-DICT." examples: - "12345678901" type: string ownerTradeName: description: Owner trade name (legal-entity owners), omitted when unset. examples: - Silva ME type: string ownerType: description: BACEN's own Person discriminator for the owner, as the DICT published it — never the value a registration declared. Same availability as creationDate. enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string participantISPB: description: Owning participant ISPB, the BACEN institution identifier (8 digits or uppercase letters). examples: - "12345678" type: string status: description: "Key lifecycle status: ACTIVE or PENDING_CLAIM." examples: - ACTIVE type: string updatedAt: description: Timestamp of the last update to the key, RFC 3339 (UTC). examples: - "2025-03-07T14:30:00Z" type: string required: - id - keyType - keyValue - ownerName - ownerTaxId - participantISPB - status - createdAt - updatedAt type: object PIXKeyResponse: additionalProperties: false properties: accountNumber: description: Account number (1..20 digits), omitted for a tuple-less key. examples: - "9988776" type: string accountType: description: BACEN account type (CACC, SVGS, TRAN, SLRY, OTHR), omitted for a tuple-less key. enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this key; omitted when no BACEN interaction has ever landed on it. branch: description: Account branch (1..4 digits), omitted when unset. examples: - "0001" type: string createdAt: description: Key creation timestamp, RFC 3339 (UTC) — OUR row's local timestamp, not BACEN's; see creationDate for the DICT's own binding-creation instant. examples: - "2025-03-07T14:30:00Z" type: string creationDate: description: BACEN's own creation instant for this key/account/owner binding, as the DICT answered it; omitted when BACEN's answer carried none. examples: - "2020-01-15T00:00:00Z" format: date-time type: string id: description: Unique PIX key identifier (UUID) assigned by the service. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string keyOwnershipDate: description: Instant from which the owner has held uninterrupted possession of this key per BACEN; may differ from creationDate after a portability. Omitted when BACEN's answer carried none. examples: - "2020-01-15T00:00:00Z" format: date-time type: string keyType: description: "PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key)." examples: - CPF type: string keyValue: description: PIX key value in its canonical format for the key type. examples: - "12345678901" type: string openingDate: description: Account opening date, RFC 3339, omitted for a tuple-less key. examples: - "2020-01-15T00:00:00Z" format: date-time type: string ownerName: description: Full legal name of the key owner. examples: - João Silva type: string ownerTaxId: description: "Owner tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024)." examples: - "12345678901" type: string ownerTradeName: description: Owner trade name (legal-entity owners), omitted when unset. examples: - Silva ME type: string ownerType: description: BACEN's own Person discriminator for the owner, as the DICT published it — not the value the registration declared, which is refused when the two could disagree. Omitted when BACEN's answer carried none. enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string participantISPB: description: Owning participant ISPB, the BACEN institution identifier (8 digits or uppercase letters). examples: - "12345678" type: string requestId: description: The participant's own identifier for the registration that created this binding, echoed back. It is the value BACEN holds against the vinculo for life, so it is what a DICT support case and a retry are addressed by. Omitted for a key registered before this field existed, which had no caller to state one. examples: - b2696bf1-0a51-48b0-ab4a-8af2dff440af format: uuid type: string status: description: "Key lifecycle status: ACTIVE or PENDING_CLAIM." examples: - ACTIVE type: string updatedAt: description: Timestamp of the last update to the key, RFC 3339 (UTC). examples: - "2025-03-07T14:30:00Z" type: string required: - id - keyType - keyValue - ownerName - ownerTaxId - participantISPB - status - createdAt - updatedAt type: object PersonStatisticsResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for this call (this surface is a live pass-through with no local row; the envelope reflects THIS request, not a persisted last interaction). statistics: $ref: "#/components/schemas/StatisticsBlocksResponse" description: BACEN system-wide person antifraud statistics (verbatim) taxIdNumber: description: Subject tax id (CPF/CNPJ) examples: - "12345678901" type: string required: - taxIdNumber - statistics type: object PersonWatchlistAddRequest: additionalProperties: false properties: taxIdNumber: description: CPF (11 digits) or CNPJ (14 characters — alphanumeric since IN RFB 2.229/2024) to watch. Sent in the body, never in the URL, because it is PII. Re-adding a document already watched returns the existing entry unchanged; re-adding one previously removed resumes watching the same entry, preserving its last observation. type: string required: - taxIdNumber type: object PersonWatchlistEntryResponse: additionalProperties: false properties: consecutiveFailures: description: How many observation attempts have failed back to back. Any success resets it to zero. format: int64 type: integer createdAt: description: When the document was admitted (RFC 3339). type: string id: description: Opaque entry id. Remove addresses this, never the document. format: uuid type: string lastAttemptAt: description: When the poll last TRIED this document, successfully or not. Diverging from lastObservedAt means BACEN is refusing this subject. type: string lastObservedAt: description: When BACEN's counters were last read for this document. Absent until the first observation. type: string lastWatermark: description: BACEN's own freshness marker for the last observation — the composite of the four PersonStatistics block watermarks. This, not the read time, is what changes when the counters change. BACEN's counters are up to 12 hours stale by regulation, so a recent read never means recent data. type: string quarantinedAt: description: When repeated failures parked this document. A parked document is no longer polled and no longer counted by the readiness staleness check — one unreadable subject must not take the rail unready. Removing and re-adding it resumes surveillance. type: string removedAt: description: "When surveillance was stopped, if it was. Removal is a soft stop: observations already emitted are never retracted." type: string taxIdNumber: description: The watched CPF/CNPJ. type: string required: - id - taxIdNumber - createdAt - consecutiveFailures type: object PersonWatchlistListResponse: additionalProperties: false properties: items: description: Watched documents, newest first. items: $ref: "#/components/schemas/PersonWatchlistEntryResponse" type: array required: - items type: object PossessionEvidenceRequest: additionalProperties: false properties: challengeId: description: "The client's own opaque handle on the verification — the SMS challenge, the e-mail confirmation, the onboarding case — so an auditor can find it in the system that performed the check. Opaque token only (letters, digits, . _ : -): never a tax id, a code, a key or a holder name." examples: - chg-8f2a1b maxLength: 128 minLength: 6 type: string method: description: "How possession was verified, per section 2.1: SMS_CODE for a PHONE key and EMAIL_CODE for an EMAIL key (a code sent to the key itself and returned through an authenticated channel), ACCOUNT_OPENING_MATCH for a CPF or CNPJ key (the document offered as the key is the one the account was opened with). A method that cannot verify the key type it is offered for is rejected." enum: - SMS_CODE - EMAIL_CODE - ACCOUNT_OPENING_MATCH examples: - SMS_CODE type: string verifiedAt: description: "When the client completed the verification, RFC 3339. Required: an attestation with no instant cannot be placed against the key's timeline. Never in the future. No method carries a recency ceiling — section 2.1 sets no freshness window — so state the instant the check actually happened, however old it is (an account-opening match is honestly as old as the account), never the present moment." examples: - "2026-08-19T12:00:00Z" format: date-time type: string required: - method - verifiedAt - challengeId type: object RefundAccountResponse: additionalProperties: false properties: accountNumber: description: Destination account number examples: - "987654" type: string accountType: description: "ISO 20022 account type: CACC, SVGS, TRAN, SLRY, or OTHR" examples: - CACC type: string branch: description: Destination account branch (optional) examples: - "0001" type: string participant: description: Destination account-holding participant ISPB examples: - "12345678" type: string taxIdNumber: description: Destination account holder tax id (CPF/CNPJ) examples: - "12345678909" type: string required: - taxIdNumber - participant - accountNumber - accountType type: object RefundListResponse: additionalProperties: false properties: items: description: Local DICT refund request records for the requested limit/offset window. items: $ref: "#/components/schemas/RefundResponse" 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 requestId: description: Request-scoped identifier echoing X-Request-ID, for pivoting from response to trace. This is OUR OWN echo, distinct from any item's bacen.correlationId, which is BACEN's own value. type: string required: - items - limit - offset type: object RefundMutationResponse: additionalProperties: false properties: amount: description: Refund amount as an exact decimal number examples: - 1500 type: number analysisDetails: description: Free-text analysis details accompanying analysisResult; omitted until close (ours or the counterparty's, via refresh) type: string analysisResult: description: "closeRefund analysis outcome: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, or REJECTED; omitted until close" enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this refund, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this refund request (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string contestedISPB: description: BACEN-assigned contested participant ISPB (ExtendedRefund.ContestedParticipant) examples: - "87654321" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string effectiveRefundedAmount: description: "MED 2.0: effective refunded amount recorded on an accepting close (exact decimal, verbatim); omitted until close" examples: - 750 type: number endToEndId: description: BACEN end-to-end identifier (E2E ID) of the refunded PIX transaction examples: - E12345678202607101200D3E4F5A6B7C type: string fundsRecoveryId: description: BACEN-assigned funds-recovery id this refund is bound to (refund-under-recovery); omitted for a standalone refund examples: - 550e8400-e29b-41d4-a716-446655440003 type: string id: description: BACEN-assigned refund resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440001 type: string infractionReportId: description: BACEN-assigned infraction this refund was opened for (ExtendedRefund.InfractionReportId); omitted otherwise examples: - 550e8400-e29b-41d4-a716-446655440004 type: string monitorAccount: description: "MED 2.0: whether the destination account is monitored (ExtendedRefund.MonitorAccount); omitted when BACEN has never echoed a value, explicit true/false once it has" examples: - true type: boolean operationId: description: "Durable MED operation-intent id: the operation that produced this resource's current state. Present on both a synchronous 200/201 and a pending 202." examples: - 01930000-0000-7000-8000-000000000000 type: string operationStatus: description: Durable operation-intent status. Always COMPLETED on a synchronous 200/201; on a pending 202 it is never REJECTED or LOCAL_FAILURE — both are BACEN-final/local-final outcomes mapped to their own HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED examples: - UNKNOWN_OUTCOME type: string originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string reason: description: "BACEN refund reason: FRAUD, OPERATIONAL_FLAW or PIX_AUTOMATICO" examples: - FRAUD type: string refundAccount: $ref: "#/components/schemas/RefundAccountResponse" description: "MED 2.0: destination account of a refund-under-recovery; omitted for a standalone refund" refundDetails: description: Short description of why the refund was requested; present when the reason carries one type: string refundTransactionId: description: BACEN-executed refund transaction id (ExtendedRefund.RefundTransactionId), distinct from endToEndId; empty until a refund transaction exists examples: - E99999010202606141430ZYXWVUTSRQP type: string rejectionReason: description: BACEN rejection reason accompanying a REJECTED analysisResult; omitted otherwise examples: - NO_BALANCE type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string requestedByISPB: description: ISPB (8 digits or uppercase letters) of the participant that requested the refund examples: - "12345678" type: string requestingISPB: description: BACEN-assigned requesting participant ISPB (ExtendedRefund.RequestingParticipant) examples: - "12345678" type: string status: description: "DICT spec refund lifecycle state: OPEN, CLOSED, or CANCELLED. CLOSED alone does not say accept vs reject; see analysisResult." enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string updatedAt: description: "Last update timestamp (RFC 3339 with fractional seconds, UTC): two changes in the same second carry distinct, ordered values" examples: - "2026-06-14T12:00:00.250Z" type: string required: - id - endToEndId - requestedByISPB - amount - reason - status - reportStatus - createdAt - updatedAt type: object RefundResponse: additionalProperties: false properties: amount: description: Refund amount as an exact decimal number examples: - 1500 type: number analysisDetails: description: Free-text analysis details accompanying analysisResult; omitted until close (ours or the counterparty's, via refresh) type: string analysisResult: description: "closeRefund analysis outcome: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, or REJECTED; omitted until close" enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for its most recent interaction on this refund, including its LastModified version; omitted when no BACEN interaction has ever landed on it. bacenCreationTime: description: When BACEN created this refund request (RFC 3339, UTC); distinct from createdAt examples: - "2026-06-14T12:00:00Z" type: string contestedISPB: description: BACEN-assigned contested participant ISPB (ExtendedRefund.ContestedParticipant) examples: - "87654321" type: string createdAt: description: Record creation timestamp (RFC 3339, UTC) examples: - "2026-06-14T12:00:00Z" type: string effectiveRefundedAmount: description: "MED 2.0: effective refunded amount recorded on an accepting close (exact decimal, verbatim); omitted until close" examples: - 750 type: number endToEndId: description: BACEN end-to-end identifier (E2E ID) of the refunded PIX transaction examples: - E12345678202607101200D3E4F5A6B7C type: string fundsRecoveryId: description: BACEN-assigned funds-recovery id this refund is bound to (refund-under-recovery); omitted for a standalone refund examples: - 550e8400-e29b-41d4-a716-446655440003 type: string id: description: BACEN-assigned refund resource UUID — the public, canonical identity of this record examples: - 550e8400-e29b-41d4-a716-446655440001 type: string infractionReportId: description: BACEN-assigned infraction this refund was opened for (ExtendedRefund.InfractionReportId); omitted otherwise examples: - 550e8400-e29b-41d4-a716-446655440004 type: string monitorAccount: description: "MED 2.0: whether the destination account is monitored (ExtendedRefund.MonitorAccount); omitted when BACEN has never echoed a value, explicit true/false once it has" examples: - true type: boolean originOperationId: description: Durable operation-intent id that produced this snapshot's current state, when known examples: - 01930000-0000-7000-8000-000000000000 type: string reason: description: "BACEN refund reason: FRAUD, OPERATIONAL_FLAW or PIX_AUTOMATICO" examples: - FRAUD type: string refundAccount: $ref: "#/components/schemas/RefundAccountResponse" description: "MED 2.0: destination account of a refund-under-recovery; omitted for a standalone refund" refundDetails: description: Short description of why the refund was requested; present when the reason carries one type: string refundTransactionId: description: BACEN-executed refund transaction id (ExtendedRefund.RefundTransactionId), distinct from endToEndId; empty until a refund transaction exists examples: - E99999010202606141430ZYXWVUTSRQP type: string rejectionReason: description: BACEN rejection reason accompanying a REJECTED analysisResult; omitted otherwise examples: - NO_BALANCE type: string reportStatus: description: BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row). examples: - SENT type: string requestedByISPB: description: ISPB (8 digits or uppercase letters) of the participant that requested the refund examples: - "12345678" type: string requestingISPB: description: BACEN-assigned requesting participant ISPB (ExtendedRefund.RequestingParticipant) examples: - "12345678" type: string status: description: "DICT spec refund lifecycle state: OPEN, CLOSED, or CANCELLED. CLOSED alone does not say accept vs reject; see analysisResult." enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string updatedAt: description: "Last update timestamp (RFC 3339 with fractional seconds, UTC): two changes in the same second carry distinct, ordered values" examples: - "2026-06-14T12:00:00.250Z" type: string required: - id - endToEndId - requestedByISPB - amount - reason - status - reportStatus - createdAt - updatedAt type: object RegisterKeyRequest: additionalProperties: false properties: accountNumber: description: Account number, 1 to 20 digits. BACEN admits letters here; this rail does not, and the door states the narrower rule it actually applies. examples: - "9988776" pattern: ^[0-9]{1,20}$ type: string accountType: description: "BACEN account type: CACC (current), SVGS (savings), TRAN (transactional), SLRY (salary), or OTHR (other)." enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string branch: description: Account branch (1..4 digits), optional. examples: - "0001" type: string keyType: description: "PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key)." enum: - CPF - CNPJ - EMAIL - PHONE - EVP examples: - CPF type: string keyValue: description: "PIX key value, formatted according to keyType: 11 digits for CPF, 14 alphanumeric characters for CNPJ, +55 plus an 11-digit mobile number for PHONE, an email address for EMAIL. REQUIRED for those four types and REFUSED for EVP — the chave aleatória is generated by the DICT, and the value it returns is the key." examples: - "12345678901" type: string openingDate: description: Account opening date, RFC 3339 (the FI account's opening date, not the key's creation moment). examples: - "2020-01-15T00:00:00Z" format: date-time type: string ownerName: description: Full legal name of the key owner (at most 150 characters). The accepted character set differs by owner type — letters, apostrophe, hyphen and space for an individual; printable Latin-1 for a company — and is applied by the service, since one schema pattern cannot depend on the tax id's length. examples: - João Silva maxLength: 150 minLength: 1 type: string ownerTaxId: description: "Owner tax identifier: 11 digits for a CPF (individuals), 14 alphanumeric characters for a CNPJ (businesses, IN RFB 2.229/2024). Shaped as the SPI wire type PICpfCnpj. The check digits are verified by the service." examples: - "12345678901" pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$ type: string ownerTradeName: description: Owner trade name (legal-entity / CNPJ owners), optional. examples: - Silva ME type: string ownerType: description: "BACEN's Person discriminator for the key owner, sent verbatim on createEntry. Optional: omitted, it is resolved from ownerTaxId (11 characters natural, 14 legal). Supplied, it binds — a value contradicting ownerTaxId is refused, never honoured." enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string participantISPB: description: Owning participant ISPB, the BACEN institution identifier (8 digits or uppercase letters). examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string possessionEvidence: $ref: "#/components/schemas/PossessionEvidenceRequest" description: Attestation that key possession was verified, as DICT 8.4 section 2.1 requires. Optional for CPF, CNPJ, EMAIL and PHONE keys; refused for EVP, where nothing is possessed. Omitting it does not refuse the registration — the absence is recorded in the key's audit trail. Supplied, it is validated in full and a malformed attestation is refused. reason: description: "Why this key is being registered, sent verbatim to BACEN as createEntry's Reason. USER_REQUESTED when an end user asked for the key, RECONCILIATION when restoring a binding this PSP already holds after a divergence. Required: only the participant holds the fact that decides it, so there is no default." enum: - USER_REQUESTED - RECONCILIATION examples: - USER_REQUESTED type: string requestId: description: "Idempotency key for this registration, a version 4 UUID, sent verbatim to BACEN as createEntry's RequestId. Required — never invented here. BACEN binds it to the vinculo for life and refuses a reuse under different binding parameters, so send a fresh value per registration. This rail does not refuse a reused value locally: the rule is BACEN's, enforced there and relayed. Must be version 4: every other version derives from a clock, a node id or a hashed name, so two different registrations can collide by construction. Distinct from the X-Idempotency header, which is this rail's own de-duplication and never reaches BACEN." examples: - b2696bf1-0a51-48b0-ab4a-8af2dff440af format: uuid type: string required: - keyType - ownerName - ownerTaxId - participantISPB - accountNumber - accountType - openingDate - requestId - reason type: object RegulatoryOperationListResponse: additionalProperties: false properties: items: description: Durable MED operation-intent statuses for the requested filter/page window — the SAME projection GET /operations/{id} returns per item. items: $ref: "#/components/schemas/RegulatoryOperationResponse" type: array limit: description: Effective page size applied to this response. format: int64 type: integer nextCursor: description: Opaque continuation token for the next page; absent when no further page remains. type: string required: - items - limit type: object RegulatoryOperationResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own sanitized operational envelope for the last interaction this operation recorded (correlation id + response time only, never payload); omitted when no BACEN interaction has landed yet. bacenResourceId: description: BACEN-assigned resource UUID, once known; absent while a create's outcome is still unresolved. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string createdAt: description: Operation reservation timestamp (RFC 3339, UTC). examples: - "2026-06-14T12:00:00Z" type: string kind: description: MED resource kind this operation concerns. enum: - infraction - refund - fraud_marker - funds_recovery examples: - infraction type: string operationId: description: This attempt's own identity; never the business resource's id. examples: - 01930000-0000-7000-8000-000000000000 type: string requestFingerprint: description: Lowercase-hex SHA-256 of this operation's own canonical request — never the request body itself. Required as the digest field of a MANUAL_REVIEW resolution decision (ATTACH_BACEN_RESOURCE or CONFIRM_NOT_APPLIED) so the resolution callback can authenticate it is targeting the right operation. examples: - 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae type: string status: description: Durable operation-intent lifecycle state — OUR attempt's status, distinct from the business resource's own BACEN-reported status. LOCAL_FAILURE means the attempt never reached BACEN (a local dependency fault, e.g. the DICT signer) — never BACEN's own verdict. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - REJECTED - UNKNOWN_OUTCOME - MANUAL_REVIEW - ABANDONED - COMPLETED - LOCAL_FAILURE examples: - UNKNOWN_OUTCOME type: string updatedAt: description: Last status-transition timestamp (RFC 3339, UTC). examples: - "2026-06-14T12:00:00Z" type: string verb: description: BACEN verb this operation reserved. enum: - create - update - acknowledge - close - cancel - refund examples: - create type: string required: - operationId - kind - verb - status - requestFingerprint - createdAt - updatedAt type: object ResolveRegulatoryOperationRequest: additionalProperties: false properties: action: description: The human checker's four-eyes decision, relayed unopened from the approval that produced it. enum: - ATTACH_BACEN_RESOURCE - CONFIRM_NOT_APPLIED examples: - ATTACH_BACEN_RESOURCE type: string bacenResourceId: description: BACEN-assigned resource UUID the maker located by other means (e.g. an operator console). Required for ATTACH_BACEN_RESOURCE; must be absent for CONFIRM_NOT_APPLIED. format: uuid type: string digest: description: Lowercase-hex SHA-256 that must equal this operation's own requestFingerprint (GET /api/v1/dict/operations/{operationId}) — the callback's authenticity gate against a decision aimed at the wrong operation. examples: - 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae type: string required: - action - digest type: object SearchFraudMarkersRequest: additionalProperties: false properties: key: description: Optional Pix key the markers are associated with; BACEN requires it to belong to taxIdNumber's owner. A blank value is treated as absent. examples: - usuario@example.com maxLength: 77 type: string limit: description: Optional maximum number of markers BACEN returns (1 to 200). Omitted leaves BACEN's default of 20. examples: - 20 format: int64 maximum: 200 minimum: 1 type: integer modifiedAfter: description: "Optional lower bound (RFC 3339): markers modified at or after this instant." examples: - "2026-09-01T00:00:00Z" format: date-time type: string modifiedBefore: description: "Optional upper bound (RFC 3339): markers modified at or before this instant. Must not be earlier than modifiedAfter." examples: - "2026-09-30T23:59:59Z" format: date-time type: string participantISPB: description: ISPB (8 digits or uppercase letters) of the participant whose own fraud markers are searched; gated to the calling direct's scope (the direct itself or an indirect it sponsors) and sent to BACEN as Participant. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string status: description: "Optional BACEN FraudMarkerStatus filter: REGISTERED (active) or CANCELLED. Omitted returns both." enum: - REGISTERED - CANCELLED examples: - REGISTERED type: string taxIdNumber: description: CPF (11 digits) or CNPJ (14 alphanumeric characters) the markers are associated with. Required by BACEN's listFraudMarkers. examples: - "52998224725" pattern: ^(?:[0-9]{11}|[A-Za-z0-9]{12}[0-9]{2})$ type: string required: - participantISPB - taxIdNumber type: object StatWindowResponse: additionalProperties: false properties: d90: description: Last 89 days including today (BACEN wire value, verbatim) examples: - "0" type: string m12: description: Last 12 calendar months excluding current month (BACEN wire value, verbatim) examples: - "0" type: string m60: description: Last 60 calendar months excluding current month (BACEN wire value, verbatim) examples: - "0" type: string required: - d90 - m12 - m60 type: object StatisticsBlocksResponse: additionalProperties: false properties: entries: $ref: "#/components/schemas/StatisticsBlocksResponseEntriesStruct" description: Entry statistics fraudMarkers: $ref: "#/components/schemas/StatisticsBlocksResponseFraudMarkersStruct" description: Fraud-marker statistics infractionReports: $ref: "#/components/schemas/StatisticsBlocksResponseInfractionReportsStruct" description: Infraction-report statistics spi: $ref: "#/components/schemas/StatisticsBlocksResponseSpiStruct" description: SPI settlement statistics required: - spi - fraudMarkers - infractionReports - entries type: object StatisticsBlocksResponseEntriesStruct: additionalProperties: false properties: distinctAccounts: $ref: "#/components/schemas/StatWindowResponse" description: "Key-scope: distinct accounts (windowed; omitted in owner block). A pointer so omitempty drops it for owner-scope (a plain struct would still serialize {})" registeredAccounts: description: "Owner-scope: registered accounts (scalar; omitted in key block)" examples: - "0" type: string watermark: description: Entries block watermark (RFC 3339) examples: - "2023-01-01T10:00:00.000Z" type: string required: - watermark type: object StatisticsBlocksResponseFraudMarkersStruct: additionalProperties: false properties: applicationFrauds: $ref: "#/components/schemas/StatWindowResponse" distinctFraudReporters: $ref: "#/components/schemas/StatWindowResponse" muleAccounts: $ref: "#/components/schemas/StatWindowResponse" otherFrauds: $ref: "#/components/schemas/StatWindowResponse" scammerAccounts: $ref: "#/components/schemas/StatWindowResponse" totalFraudTransactionAmount: $ref: "#/components/schemas/StatWindowResponse" description: Total fraud transaction amount (BACEN wire value, verbatim) unknownFrauds: $ref: "#/components/schemas/StatWindowResponse" watermark: description: FraudMarkers block watermark (RFC 3339) examples: - "2023-01-01T10:00:00.000Z" type: string required: - watermark - applicationFrauds - muleAccounts - scammerAccounts - otherFrauds - unknownFrauds - totalFraudTransactionAmount - distinctFraudReporters type: object StatisticsBlocksResponseInfractionReportsStruct: additionalProperties: false properties: openReports: description: Open infraction reports (scalar, not windowed) examples: - "0" type: string openReportsDistinctReporters: description: Distinct reporters of open reports (scalar, not windowed) examples: - "0" type: string rejectedReports: $ref: "#/components/schemas/StatWindowResponse" watermark: description: InfractionReports block watermark (RFC 3339) examples: - "2023-01-01T10:00:00.000Z" type: string required: - watermark - openReports - openReportsDistinctReporters - rejectedReports type: object StatisticsBlocksResponseSpiStruct: additionalProperties: false properties: settlements: $ref: "#/components/schemas/StatWindowResponse" description: SPI settlement counters watermark: description: SPI block watermark (RFC 3339) examples: - "2023-01-01T10:00:00.000Z" type: string required: - watermark - settlements type: object SyncVerificationResponse: additionalProperties: false properties: bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's operational envelope for this call; omitted when BACEN sent no correlation id. id: description: BACEN's own id for this sync verification. examples: - "4521" type: string keyType: description: Key type that was verified. examples: - CPF type: string participant: description: ISPB the verification was run for, resolved from X-ISPB. examples: - "12345678" type: string participantSyncVerifier: description: The sync verifier that was sent to BACEN. examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 type: string result: description: "BACEN's verdict, verbatim: OK when the CID sets match, NOK when they diverge." examples: - NOK type: string required: - participant - keyType - participantSyncVerifier - id - result type: object TrackingGraphAccountResponse: additionalProperties: false properties: id: description: Graph-local node id (NOT a real account identifier) examples: - 1 format: int64 type: integer openingDate: description: Account opening date (RFC 3339), when present examples: - "2010-01-10T03:00:00Z" type: string ownerId: description: Graph-local person node id that owns this account examples: - 1 format: int64 type: integer participant: description: Account-holding participant ISPB examples: - "99999010" type: string required: - id - ownerId - participant type: object TrackingGraphParametersResponse: additionalProperties: false properties: hopWindow: description: Time window (ISO 8601 duration) between a transaction entering and leaving an account for both to be linked examples: - PT24H type: string maxHops: description: Maximum graph depth examples: - 5 format: int64 type: integer maxTransactions: description: Maximum number of transactions included in the graph examples: - 500 format: int64 type: integer minTransactionAmount: description: Minimum transaction amount included in the graph (BACEN wire value, projected verbatim) examples: - "200.00" type: string required: - minTransactionAmount - maxTransactions - hopWindow - maxHops type: object TrackingGraphPersonResponse: additionalProperties: false properties: entityCreationDate: description: Legal-person entity creation date (RFC 3339), when present examples: - "2010-01-10T03:00:00Z" type: string id: description: Graph-local node id (NOT a real person identifier) examples: - 1 format: int64 type: integer type: description: "Person type: NATURAL_PERSON or LEGAL_PERSON" examples: - NATURAL_PERSON type: string required: - id - type type: object TrackingGraphResponse: additionalProperties: false properties: accounts: description: Graph account nodes items: $ref: "#/components/schemas/TrackingGraphAccountResponse" type: array bacen: $ref: "#/components/schemas/BACENEnvelopeResponse" description: BACEN's own operational envelope for this call (this surface is a live pass-through with no local row; the envelope reflects THIS request, not a persisted last interaction). creationTime: description: Timestamp the graph was created at BACEN (RFC 3339), when present examples: - "2020-01-17T10:00:00.000Z" type: string fundsRecoveryId: description: BACEN-assigned funds-recovery id the graph belongs to examples: - ca1b9c01-ff9e-4a58-90ab-d31512e15ce0 type: string parameters: $ref: "#/components/schemas/TrackingGraphParametersResponse" description: Graph-building thresholds BACEN applied persons: description: Graph person nodes (anonymised) items: $ref: "#/components/schemas/TrackingGraphPersonResponse" type: array rootTransactionId: description: "Contested transaction identifier the graph was built from: a payment's EndToEndID (E-prefixed) or a contested return operation's RtrId (D-prefixed)" examples: - E99999010202607100915F5E4D3C2B1A type: string transactions: description: Graph transaction edges items: $ref: "#/components/schemas/TrackingGraphTransactionResponse" type: array required: - fundsRecoveryId - rootTransactionId - parameters - persons - accounts - transactions type: object TrackingGraphTransactionResponse: additionalProperties: false properties: amount: description: Transaction amount (BACEN wire value, projected verbatim) examples: - "1000.20" type: string creditorAccountId: description: Graph-local destination account node id examples: - 2 format: int64 type: integer debtorAccountId: description: Graph-local source account node id examples: - 1 format: int64 type: integer id: description: Transaction end-to-end id (edge identifier) examples: - E99999010202607100930A1B2C3D4E5F type: string refundableAmount: description: Refundable amount (BACEN wire value, projected verbatim) examples: - "900.10" type: string settlementTime: description: Settlement timestamp, when present examples: - "2024-10-01T10:00:00.000Z" type: string required: - id - debtorAccountId - creditorAccountId - amount - refundableAmount type: object UnblockDICTDiscoveryFeedRequest: additionalProperties: false properties: allowSkipForward: description: Required to be true when resetModifiedAfter is LATER than the window the feed currently holds. Such a reset abandons every record BACEN would have served in between, so it must be asked for rather than typed by accident. Irrelevant when the persisted watermark cannot be parsed at all, which is the corruption this route exists to repair. type: boolean resetModifiedAfter: description: "Optional replacement for the feed's ModifiedAfter window watermark, as an RFC 3339 instant in the past. Supply it ONLY when the feed froze on an unusable watermark: it moves a regulatory discovery window by hand, so anything BACEN would have served between the feed's real position and this instant is not walked. Refused for a feed whose continuation is BACEN's own opaque cursor rather than a timestamp, and refused for a feed that is not actually frozen." format: date-time type: string type: object UnblockDICTDiscoveryFeedResponse: additionalProperties: false properties: clearedReason: description: The closed-vocabulary reason the feed had been frozen with; absent when it was already running. examples: - invalid_watermark type: string feed: description: The feed that was unblocked. examples: - dict_infraction_discovery type: string previousWindow: description: The window watermark this request replaced, verbatim — including an unparseable value, which is the very condition that froze the feed. Absent when no reset was requested. type: string restoredWindow: description: The window watermark now in force. Absent when no reset was requested. examples: - "2026-08-10T00:00:00Z" type: string resumeWarning: description: "Present when clearing the marker does not by itself resolve what froze the feed — a hold on a BACEN entry this deployment could not store, or, on the fraud-marker inventory sweep, a document whose markers the domain refuses or that BACEN will not serve at all. The feed resumes at the SAME position it froze on and freezes again after the same tolerance unless that condition has changed, and the sentence names the exit that actually exists for THIS feed: the per-record write-off for a feed held on a record it can name, the window correction in this same call for the sweep, whose held subject is a document and so is never listed as a record. Absent when a window correction moved the position in the same call." type: string rotationRestarted: description: True when the reset also discarded an open sweep rotation, which would otherwise have applied the corrected window to only the tail of the cycle in progress. type: boolean skipWarning: description: "Present only on a reset: states that the interval jumped over is not walked." type: string wasBlocked: description: False when the feed was already running — the call is then a no-op on the marker, still audited under the caller's identity. examples: - true type: boolean watermarkReset: description: True when this request replaced the feed's window watermark. examples: - false type: boolean required: - feed - wasBlocked - watermarkReset type: object UpdateFundsRecoveryRequest: additionalProperties: false properties: reportDetails: description: Corrected details for the counterparty PSP; mandatory when situationType is OTHER (max 2000 characters). maxLength: 2000 type: string situationType: description: "Corrected MED 2.0 situation classification: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, or UNKNOWN" enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string required: - situationType type: object UpdateKeyRequest: additionalProperties: false properties: accountNumber: description: New account number (account mutable field). examples: - "9988776" type: string accountType: description: New account type (account mutable field). examples: - CACC type: string branch: description: New account branch (account mutable field). examples: - "0001" type: string keyType: description: "Immutable: supplying a value differing from the stored keyType is rejected." examples: - CPF type: string openingDate: description: Account opening date, RFC 3339. Used only for a key this service does not hold, where it is required with accountNumber and accountType when the account moves; a held key always sends its stored opening date. examples: - "2020-01-15T00:00:00Z" format: date-time type: string ownerName: description: New owner legal name (owner mutable field). examples: - João Silva type: string ownerTaxId: description: "Immutable: supplying a value differing from the stored ownerTaxId is rejected." examples: - "12345678901" type: string ownerTradeName: description: New owner trade name (owner mutable field). examples: - Silva ME type: string reason: description: "Update reason: USER_REQUESTED (not for EVP keys), BRANCH_TRANSFER, RECONCILIATION, or RFB_VALIDATION. This is the subset BACEN's updateEntry accepts; the wider EntryOperationReason set is not valid on an update." enum: - USER_REQUESTED - BRANCH_TRANSFER - RECONCILIATION - RFB_VALIDATION examples: - BRANCH_TRANSFER type: string required: - reason 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 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 3.1 surface for the DICT (Diretório de Identificadores de Contas Transacionais) capability of Lerian SPI, the direct integration between the institution and the Brazilian Instant Payment System (SPI/Pix). It covers the PIX key lifecycle, portability and ownership claims, the MED 2.0 dispute surface (infraction reports, refunds, fraud markers, and funds recoveries), antifraud statistics, synchronous DICT reports, and the internal operations that keep the key directory consistent. license: name: Lerian Studio General License title: Lerian SPI — DICT API version: 1.0.0 openapi: 3.1.0 paths: /api/v1/dict/cids/entries/{cid}: get: description: Reads the key binding a CID identifies from BACEN's getEntryByCid, sent with X-ISPB as PI-RequestingParticipant, and projects it verbatim. A CID BACEN no longer binds answers 404 SPI-0012. operationId: getDICTCidEntry parameters: - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: CID to resolve, 64 hex characters. in: path name: cid required: true schema: description: CID to resolve, 64 hex characters. examples: - 28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88 pattern: ^[0-9a-fA-F]{64}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CidEntryResponse" 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 "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 "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: Resolve a CID at BACEN tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/resolve-a-cid-at-bacen /api/v1/dict/cids/events: get: description: "Reads one page of BACEN's listCidSetEvents for the X-ISPB participant and one key type: the CIDs added to and removed from its set, ordered by timestamp, with BACEN's sync verifiers before and after the page. Page with startTime while hasMoreElements is true." operationId: listDICTCidSetEvents parameters: - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: Key type of the CID set. explode: false in: query name: keyType required: true schema: description: Key type of the CID set. enum: - CPF - CNPJ - EMAIL - PHONE - EVP examples: - CPF type: string - description: Inclusive lower bound on the event timestamp; omit to start at the oldest event BACEN holds. explode: false in: query name: startTime schema: description: Inclusive lower bound on the event timestamp; omit to start at the oldest event BACEN holds. examples: - "2026-09-28T00:00:00Z" format: date-time type: string - description: Inclusive upper bound on the event timestamp; omit for no upper bound. explode: false in: query name: endTime schema: description: Inclusive upper bound on the event timestamp; omit for no upper bound. examples: - "2026-09-28T23:59:59Z" format: date-time type: string - description: Maximum events per page (1..200, default 100). explode: false in: query name: limit schema: default: 100 description: Maximum events per page (1..200, default 100). examples: - 100 format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CidSetEventsResponse" 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 "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 "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 CID set events at BACEN tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/list-cid-set-events-at-bacen /api/v1/dict/cids/files: post: description: Asks BACEN's createCidSetFile to build the X-ISPB participant's full CID set of one key type and returns BACEN's answer verbatim. Lerian SPI records the request and polls BACEN until the file reaches AVAILABLE, UNAVAILABLE or ERROR, then publishes the dict_cid_set_file fact. Read the request with GET cids/files/{id} and the file with GET cids/files/{id}/content. operationId: createDICTCidSetFile parameters: - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateCidSetFileRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreatedCidSetFileResponse" description: Created "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 "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 "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: Request a CID set file from BACEN tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/request-a-cid-set-file-from-bacen /api/v1/dict/cids/files/{id}: get: description: Reads a CID set file request as Lerian SPI last recorded it from BACEN, without asking BACEN. The download url is never served. A request of another participant answers 404 SPI-0013. operationId: getDICTCidSetFile parameters: - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: BACEN's id for the file, as POST cids/files returned it. in: path name: id required: true schema: description: BACEN's id for the file, as POST cids/files returned it. examples: - "4521" pattern: ^[0-9]{1,19}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CidSetFileResponse" 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 "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 a CID set file request tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/read-a-cid-set-file-request /api/v1/dict/cids/files/{id}/content: get: description: Streams the file of an AVAILABLE request from BACEN as text/plain, one CID per line. Content-Length and X-Content-Sha256 are BACEN's reported size and SHA-256; a body that does not match them is cut before it completes, so a complete response is always BACEN's file. A request not yet AVAILABLE answers 409 SPI-0014; one of another participant 404 SPI-0013. operationId: getDICTCidSetFileContent parameters: - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: BACEN's id for the file, as POST cids/files returned it. in: path name: id required: true schema: description: BACEN's id for the file, as POST cids/files returned it. examples: - "4521" pattern: ^[0-9]{1,19}$ type: string responses: "200": content: text/plain: schema: type: string description: The CID set file, one 64-hex CID per line. headers: Content-Length: description: Size of the file in bytes, as BACEN reported it. schema: format: int64 type: integer X-Content-Sha256: description: SHA-256 of the file, lowercase hex, as BACEN reported it. schema: pattern: ^[0-9a-fA-F]{64}$ type: string "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 "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: Stream a CID set file tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/stream-a-cid-set-file /api/v1/dict/claims: get: description: Returns a paginated list of claims. Scoped server-side to the participants this deployment serves — its own direct and the indirects it sponsors — so a claim neither side of which we serve is never listed. The page carries the whole claim entity, the claimer block included. operationId: listClaims parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer - description: "Optional facet: narrow the page to claims whose claimer participant matches this ISPB (8 digits or uppercase letters). It narrows WITHIN the server-derived scope and can never widen it." explode: false in: query name: claimerISPB schema: description: "Optional facet: narrow the page to claims whose claimer participant matches this ISPB (8 digits or uppercase letters). It narrows WITHIN the server-derived scope and can never widen it." type: string - description: "Optional facet: narrow the page to claims whose donor participant matches this ISPB (8 digits or uppercase letters). It narrows WITHIN the server-derived scope and can never widen it." explode: false in: query name: donorISPB schema: description: "Optional facet: narrow the page to claims whose donor participant matches this ISPB (8 digits or uppercase letters). It narrows WITHIN the server-derived scope and can never widen it." type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimListResponse" description: OK "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 "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 claims tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/list-claims /api/v1/dict/claims/{claimID}: get: description: "Retrieves a single claim by its UUID. Local-first: a claim this participant lodged is answered from its own record; a DONOR-side claim another PSP opened against one of this participant's keys has no local record and is projected verbatim from BACEN's getClaim. Answers the whole claim entity, the claimer block included, the same shape every claim endpoint answers; a claim streaming fact carries the claim id, the claimed key and the two institutions, never the claimer." operationId: getClaim parameters: - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/get-claim /api/v1/dict/claims/{claimID}/abandon: post: description: "Ends a claim this deployment initiated that BACEN never registered. Such a claim is OPEN with no BACEN id because its createClaim gave up without an answer: every claim verb refuses it with 409, the deadline sweep cannot read it at BACEN, and the claimed key stays taken by it. The claim becomes CANCELLED with resolution NOT_REGISTERED_AT_BACEN, nothing is sent to BACEN, the key is free for a new claim, and dict.claim.cancelled is emitted in the same transaction. It is refused with 409 for a claim that carries a BACEN id (cancel it instead), for a claim that is not OPEN, and while its createClaim is still pending, being sent or waiting for a retry: only an intent that exhausted its retries leaves a claim BACEN will not register. A claim BACEN did register while its answer was lost is not abandonable either: the claimer feed adopts BACEN's id within its next tick, so check GET /api/v1/dict/discovery-feeds for a held or blocked claimer feed before abandoning. It is refused for a caller with no identifiable principal and for a claimer this deployment does not serve, requires a reason, and writes audit rows naming who, which claim and why. Idempotent — re-sending it for an abandoned claim changes nothing and is still audited." operationId: abandonUnregisteredClaim parameters: - description: The claim's own id, as the create call answered it. in: path name: claimID required: true schema: description: The claim's own id, as the create call answered it. type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AbandonUnregisteredClaimRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/AbandonUnregisteredClaimResponse" 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 "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 "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: Abandon a claim BACEN never registered tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/abandon-a-claim-bacen-never-registered /api/v1/dict/claims/{claimID}/acknowledge: post: description: Donor acknowledges the claim, transitioning it from OPEN to WAITING_RESOLUTION. operationId: acknowledgeClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimDecisionHumaBody" description: Optional empty body; the decision is determined by the operation path (confirm/reject/acknowledge/complete) required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 "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: Acknowledge claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/acknowledge-claim /api/v1/dict/claims/{claimID}/cancel: post: description: Cancels a claim. The cancelling side is derived from the authenticated participant; the reason is validated against the claim type, side, and current status per the BACEN DICT cancelClaim matrix. operationId: cancelClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelClaimHumaBody" description: Cancellation reason. The cancelling side is derived from the authenticated participant, not this body. required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 "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: Cancel claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/cancel-claim /api/v1/dict/claims/{claimID}/complete: post: description: Completes a confirmed claim, finalizing the key transfer. operationId: completeClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CompleteClaimHumaBody" description: Completion request identifier. The completing claimer is derived from the authenticated participant, not this body. required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 "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: Complete claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/complete-claim /api/v1/dict/claims/{claimID}/confirm: post: description: Donor confirms the claim, allowing the key transfer to proceed. operationId: confirmClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfirmClaimHumaBody" description: Confirmation reason. The confirming donor is derived from the authenticated participant, not this body. required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 "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: Confirm claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/confirm-claim /api/v1/dict/claims/{claimID}/reject: post: description: Declines a claim. BACEN DICT has no reject verb; this is a USER_REQUESTED cancellation that aborts the key transfer while keeping the existing key link unchanged. The cancelling side is derived from the authenticated participant; the reason×type matrix then constrains the cell (a donor declining an OWNERSHIP claim via USER_REQUESTED is rejected — the donor's ownership lever is FRAUD). operationId: rejectClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimDecisionHumaBody" description: Optional empty body; the decision is determined by the operation path (confirm/reject/acknowledge/complete) required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines description: OK "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 "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: Reject claim (decline) tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/reject-claim /api/v1/dict/discovery-feeds: get: description: "Reports which DICT poll feeds (claim discovery, MED infraction/refund discovery, the fraud-marker inventory sweep, funds-recovery event notifications) are frozen on a durable blocked marker, with the closed-vocabulary reason and the instant the freeze started. It also reports the funds-recovery feed's replay list: BACEN records it permanently stepped over and never stored, named by BACEN resource id, which are replayed through POST /api/v1/dict/funds-recoveries/intake. It also names the records a feed is currently stuck on and the ones a named operator has permanently abandoned: a held record listed here is the id an operator supplies to POST /api/v1/dict/discovery-feeds/{feed}/abandon-record, which is how a walk pinned on a record this deployment can never store is made to move on. A frozen feed deliberately does NOT degrade readiness — this rail also serves Pix keys, entries and claims, and the routes an operator needs to resolve a freeze are served by the same replicas — so this route, the brspi_dict_feed_blocked gauge and the operational event are the alarm." operationId: listDICTDiscoveryFeeds responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTDiscoveryFeedListResponse" description: State of every DICT poll feed that can freeze. description: OK "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 DICT poll feed states tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/list-dict-discovery-feeds /api/v1/dict/discovery-feeds/{feed}/abandon-record: post: description: "Permanently gives up on ONE record BACEN serves that this deployment cannot read or store, so the feed can move past it. A DICT poll feed holds its position on such a record rather than passing it by silently, which is correct and has no other ending: clearing the feed's blocked marker resumes the walk at the same position and it stops again on the same record. This route is the human decision that ends that loop, and it is deliberately not the unblock route with a flag — unblocking says try again, this says give up on this one. It is refused for a caller with no identifiable principal, requires a reason, and writes an audit row naming who, which record and why. The record then stays listed on GET /api/v1/dict/discovery-feeds forever: an abandonment that ages out of a log is exactly the silent loss this verb exists to avoid. Only the named record is passed; every other held record still holds the feed. Idempotent — re-sending the same record is a no-op that is still audited. The write-off list is bounded per feed and is never trimmed to make room: at the limit this route refuses with 409 and says so plainly, because that many records given up on one feed is a systemic refusal rather than that many accidents. GET /api/v1/dict/discovery-feeds reports abandonedRecordsRemaining on every feed, and the brspi_dict_feed_abandoned_records_remaining gauge carries the same number, so the limit is visible long before it is met." operationId: abandonDICTDiscoveryFeedRecord parameters: - description: Feed name exactly as GET /api/v1/dict/discovery-feeds reports it. in: path name: feed required: true schema: description: Feed name exactly as GET /api/v1/dict/discovery-feeds reports it. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AbandonDICTFeedRecordRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/AbandonDICTFeedRecordResponse" description: OK "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: Abandon one unreadable record on a DICT poll feed tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/abandon-dict-discovery-feed-record /api/v1/dict/discovery-feeds/{feed}/unblock: post: description: "Clears a DICT poll feed's durable blocked marker so the next tick runs. A frozen feed discovers nothing and does not thaw on restart, and every walk refuses to start while its marker is set — without this route the only recovery is a hand-written UPDATE on the watermark table of a regulated deployment. When the feed froze on an unusable window watermark (local corruption, not a BACEN anomaly), a replacement instant may be supplied in the same call, because nothing else ever rewrites that value. When the feed instead froze holding a BACEN entry it could not store, clearing the marker moves nothing else: the walk resumes at the same position and freezes again after the same tolerance unless that entry has become storable, and the response says so — on the two refund walks, whose position is BACEN's own opaque cursor, that is the only outcome available today. The funds-recovery notification feed is deliberately NOT unblockable here: its block means notifications are gone from BACEN's seven-day window for good, and lifting it is an attestation taken on the funds-recovery intake route, where the missing ids are supplied. Every call is recorded in the audit trail under the caller's identity, including the old and new watermark values." operationId: unblockDICTDiscoveryFeed parameters: - description: Feed name exactly as GET /api/v1/dict/discovery-feeds reports it. in: path name: feed required: true schema: description: Feed name exactly as GET /api/v1/dict/discovery-feeds reports it. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UnblockDICTDiscoveryFeedRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/UnblockDICTDiscoveryFeedResponse" 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: Unblock a frozen DICT poll feed tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/unblock-dict-discovery-feed /api/v1/dict/entries/{key}/statistics: get: description: Fetches BACEN's system-wide key-level antifraud statistics (owner + key blocks) by Pix key and projects them verbatim, with no local aggregation. A key BACEN DICT does not hold answers 404 with code SPI-1015; any other BACEN DICT refusal answers 422 with code SPI-1011. operationId: getEntryStatistics parameters: - description: Pix key value; statistics are fetched from BACEN by this key in: path name: key required: true schema: description: Pix key value; statistics are fetched from BACEN by this key type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryStatisticsResponse" description: BACEN-served entry antifraud statistics, projected verbatim 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 "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 "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: Get BACEN entry antifraud statistics tags: - Statistics x-mint: href: /pt/reference/rails/spi/dict/get-entry-statistics /api/v1/dict/fraud-markers: get: description: Returns paginated minimized fraud markers. operationId: listFraudMarkers parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerListResponse" 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 fraud markers tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/list-fraud-markers post: description: "Reports the fraud marker to BACEN (createFraudMarker, idempotent on a RequestId derived from X-Idempotency) and persists it once BACEN confirms. Always synchronous: an ambiguous outcome or a replay is reconciled inline — when this request's operation already carries BACEN's id, the marker BACEN serves under it (checked against the request's document, key and fraud type) is persisted and answered with 201. With no id known yet the answer is 503 SPI-1010, retry with the same X-Idempotency: when BACEN never answered, the reconciliation sweep resends the create with the same RequestId (which BACEN dedups) and records the id, after which the retry is answered 201; when BACEN confirmed without an id, the operation goes to manual review and the retry is answered once an operator resolves it. 422 when BACEN refuses the marker." operationId: createFraudMarker parameters: - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateFraudMarkerRequest" description: Fraud marker reported to BACEN first; only a CONFIRMED report is persisted locally, minimized — a rejection or ambiguous outcome creates no local row. Tracked by report_status=SENT + the durable operation intent (operationId) that created it. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateFraudMarkerResponse" description: Persisted minimized fraud marker and the operation that created it. 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 "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 "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: Create fraud marker tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/create-fraud-marker /api/v1/dict/fraud-markers/search: post: description: "Reads BACEN's listFraudMarkers for one document and answers the page verbatim: the fraud markers the participant itself made, narrowed by the optional key, status and modification window. A read sent as POST so the CPF/CNPJ travels in the JSON body, never in a URL; it stores nothing locally (GET /api/v1/dict/fraud-markers stays the local registry). An empty list when BACEN holds none. 403 for a participant outside the caller's scope; 422 for an invalid body or when BACEN rejects the query; 429 with Retry-After when throttled; 503 when BACEN cannot be reached." operationId: searchFraudMarkers requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchFraudMarkersRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerSearchResponse" 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 "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 "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: Search the participant's fraud markers at BACEN tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/search-the-participants-fraud-markers-at-bacen /api/v1/dict/fraud-markers/stats: get: description: Returns fraud-marker counts. operationId: fraudMarkerStats responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudStatsResponse" description: Aggregate fraud-marker counts description: OK "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: Fraud marker statistics tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/fraud-marker-stats /api/v1/dict/fraud-markers/{id}: get: description: Retrieves a fraud marker by its BACEN-assigned resource UUID, projecting the full ExtendedFraudMarker snapshot including TaxIdNumber in the clear. A marker not held locally — for example one BACEN created itself when an infraction this participant closed AGREED — is read from BACEN (getFraudMarker) and returned; it is persisted only when the participant's own listFraudMarkers returns it, otherwise it is answered as BACEN's projection with no local owner (participantISPB and reportStatus empty) and nothing is stored. A held marker is always served locally; POST /api/v1/dict/fraud-markers/{id}/refresh re-reads BACEN. 404 when BACEN does not know the marker either; 503 when BACEN cannot be reached. operationId: getFraudMarker parameters: - description: BACEN-assigned fraud-marker resource UUID (the public, canonical identity; a local record UUID never resolves here) in: path name: id required: true schema: description: BACEN-assigned fraud-marker resource UUID (the public, canonical identity; a local record UUID never resolves here) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerResponse" description: Persisted minimized fraud marker 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 "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 "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: Get fraud marker tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/get-fraud-marker /api/v1/dict/fraud-markers/{id}/cancel: post: description: Transitions a fraud marker ACTIVE→INACTIVE and reports the transition to BACEN. operationId: cancelFraudMarker parameters: - description: BACEN-assigned fraud-marker resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned fraud-marker resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerMutationResponse" description: Persisted minimized fraud marker, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Cancel fraud marker tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/cancel-fraud-marker /api/v1/dict/fraud-markers/{id}/refresh: post: description: "Re-reads a locally held fraud marker from BACEN (getFraudMarker) and converges the local copy through the snapshot compare-and-swap, writing an audit event with it. No scheduler runs this — the operator triggers it explicitly. 404 when the marker is not held locally (GET /api/v1/dict/fraud-markers/{id} is what lands one) or BACEN does not know it; a BACEN failure leaves the local copy untouched." operationId: refreshFraudMarker parameters: - description: BACEN-assigned fraud-marker resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned fraud-marker resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerResponse" description: Persisted minimized fraud marker 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 "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 "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: Refresh DICT fraud marker from BACEN tags: - Fraud Markers x-mint: href: /pt/reference/rails/spi/dict/refresh-dict-fraud-marker-from-bacen /api/v1/dict/funds-recoveries: get: description: Returns paginated local DICT funds-recovery records. operationId: listFundsRecoveries parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer - description: Narrows the page to the DICT 8.4 §20.1.6 open refund work whose 72-hour deadline (refundDeadlineAt) falls at or before this instant — still ANALYSED, refund step never observed — ordered most-overdue-first instead of newest-first. Pass the current instant for the recoveries already expired. Omit both deadline bounds for the unfiltered newest-first page. explode: false in: query name: refundDeadlineBefore schema: description: Narrows the page to the DICT 8.4 §20.1.6 open refund work whose 72-hour deadline (refundDeadlineAt) falls at or before this instant — still ANALYSED, refund step never observed — ordered most-overdue-first instead of newest-first. Pass the current instant for the recoveries already expired. Omit both deadline bounds for the unfiltered newest-first page. examples: - "2026-06-17T12:00:00Z" format: date-time type: string - description: "Lower bound of the same §20.1.6 refund-deadline window: drops recoveries whose deadline is at or before this instant. Combine with refundDeadlineBefore to page exactly one alarm gauge's rows — refundDeadlineAfter=&refundDeadlineBefore= is the due-soon set alone, where an upper bound by itself returns every already-expired recovery first and can push the actionable rows off the page." explode: false in: query name: refundDeadlineAfter schema: description: "Lower bound of the same §20.1.6 refund-deadline window: drops recoveries whose deadline is at or before this instant. Combine with refundDeadlineBefore to page exactly one alarm gauge's rows — refundDeadlineAfter=&refundDeadlineBefore= is the due-soon set alone, where an upper bound by itself returns every already-expired recovery first and can push the actionable rows off the page." examples: - "2026-06-17T12:00:00Z" format: date-time type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryListResponse" 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 DICT funds recoveries tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/list-funds-recoveries post: description: Creates a local DICT MED 2.0 funds-recovery record and reports it to BACEN (createFundsRecovery). The root transaction is either the contested payment's EndToEndID (pacs.008) or the contested return operation's RtrId (pacs.004), which BACEN reads as a contestação de transação de devolução. BACEN dedups a recovery per RootTransactionId. operationId: createFundsRecovery parameters: - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateFundsRecoveryRequest" description: DICT MED 2.0 funds-recovery (createFundsRecovery) reported to BACEN first; only a CONFIRMED report is persisted locally — a rejection or ambiguous outcome creates no local row. Tracked by a durable operation intent (operationId) while pending. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryMutationResponse" description: Persisted local DICT funds-recovery record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: Created headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Create DICT funds recovery tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/create-funds-recovery /api/v1/dict/funds-recoveries/intake: post: description: "Accepts an inventory of BACEN funds-recovery ids the client already holds and runs each one through the canonical snapshot pipeline: authoritative GET at BACEN, then apply through the same compare-and-set seam every other path uses. This is the only way a recovery older than BACEN's seven-day event-notification window — or one whose notification was lost — becomes visible here; the window is not an inventory. Idempotent by construction: an id already at BACEN's current version is a no-op that emits no second event, so the same batch may be re-sent safely. Each id is answered independently; a batch is capped at 50 ids per request." operationId: intakeFundsRecoveries requestBody: content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryIntakeRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryIntakeResponse" 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 "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 "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: Take in client-supplied funds-recovery ids tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/intake-funds-recoveries /api/v1/dict/funds-recoveries/{id}: get: description: Retrieves a funds recovery by its BACEN-assigned resource UUID, projecting the full ExtendedFundsRecovery snapshot. operationId: getFundsRecovery parameters: - description: BACEN-assigned funds-recovery resource UUID (the public, canonical identity; a local record UUID never resolves here) in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID (the public, canonical identity; a local record UUID never resolves here) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryResponse" description: Persisted local DICT funds-recovery record 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 DICT funds recovery tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/get-funds-recovery put: description: Corrects the situation type and report details of a funds recovery still awaiting analysis, and re-pushes the participant's registered regulator contact (updateFundsRecovery). Without it a wrong contact can only be fixed by cancelling and reopening the recovery. operationId: updateFundsRecovery parameters: - description: BACEN-assigned funds-recovery resource UUID to correct in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID to correct format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateFundsRecoveryRequest" description: "updateFundsRecovery body: corrected situation type and report details. The regulator contact is re-read from the participant registry." required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryMutationResponse" description: Persisted local DICT funds-recovery record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Correct an open funds recovery tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/update-funds-recovery /api/v1/dict/funds-recoveries/{id}/cancel: post: description: Transitions a funds recovery →CANCELLED (before REFUNDING) and reports the cancellation to BACEN. operationId: cancelFundsRecovery parameters: - description: BACEN-assigned funds-recovery resource UUID in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryMutationResponse" description: Persisted local DICT funds-recovery record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Cancel DICT funds recovery tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/cancel-funds-recovery /api/v1/dict/funds-recoveries/{id}/infraction-reports: get: description: Lists the local DICT infraction reports cross-linked to a funds recovery (local read of our persisted reports, not a BACEN fetch). operationId: listFundsRecoveryInfractionReports parameters: - description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); filters the linked infractions/refunds by their own BACEN-projected FundsRecoveryId in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); filters the linked infractions/refunds by their own BACEN-projected FundsRecoveryId format: uuid type: string - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionListResponse" 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 a funds recovery's infraction reports tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/list-funds-recovery-infraction-reports /api/v1/dict/funds-recoveries/{id}/refund: post: description: Asks BACEN to move an ANALYSED funds recovery into its refunding phase (refundFundsRecovery). Only the participant that created the recovery may ask. BACEN derives the transactions and amounts from the recovery's own tracking graph and answers with the recovery, so no refund record is created locally. operationId: requestFundsRecoveryRefund parameters: - description: BACEN-assigned funds-recovery resource UUID to request the refund on in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID to request the refund on format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryMutationResponse" description: Persisted local DICT funds-recovery record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Request the refund of a funds recovery tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/create-funds-recovery-refund /api/v1/dict/funds-recoveries/{id}/refunds: get: description: Lists the local DICT refunds cross-linked to a funds recovery (local read of our persisted refunds, not a BACEN fetch). operationId: listFundsRecoveryRefunds parameters: - description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); filters the linked infractions/refunds by their own BACEN-projected FundsRecoveryId in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); filters the linked infractions/refunds by their own BACEN-projected FundsRecoveryId format: uuid type: string - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundListResponse" 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 a funds recovery's refunds tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/list-funds-recovery-refunds /api/v1/dict/funds-recoveries/{id}/tracking-graph: get: description: Fetches the AUTOMATED-flow fraud-tracking graph from BACEN and projects it verbatim. The manual createTrackingGraph POST is BACEN-deprecated; only this read is current. operationId: getFundsRecoveryTrackingGraph parameters: - description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); the graph is fetched from BACEN by this same id in: path name: id required: true schema: description: BACEN-assigned funds-recovery resource UUID (same public identity as GET .../funds-recoveries/{id}); the graph is fetched from BACEN by this same id format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TrackingGraphResponse" description: BACEN-projected fraud-tracking graph, verbatim, with no local computation 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 "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 "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: Get DICT funds-recovery tracking graph tags: - Funds Recoveries x-mint: href: /pt/reference/rails/spi/dict/get-funds-recovery-tracking-graph /api/v1/dict/infractions: get: description: Returns paginated local DICT infraction records. operationId: listInfractions parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer - description: "Narrows the page to one half of the DICT 8.4 §20.3 seven-day backlog: AWAITING_ACKNOWLEDGMENT (still OPEN, nobody has declared it received) or AWAITING_ANALYSIS_RESULT (acknowledged, analysis result not yet sent). Omit to cover both halves." explode: false in: query name: analysisStage schema: description: "Narrows the page to one half of the DICT 8.4 §20.3 seven-day backlog: AWAITING_ACKNOWLEDGMENT (still OPEN, nobody has declared it received) or AWAITING_ANALYSIS_RESULT (acknowledged, analysis result not yet sent). Omit to cover both halves." enum: - AWAITING_ACKNOWLEDGMENT - AWAITING_ANALYSIS_RESULT examples: - AWAITING_ACKNOWLEDGMENT type: string - description: Narrows the page to notifications whose seven-day analysis deadline falls at or before this instant, ordered most-overdue-first instead of newest-first. The deadline is counted from the moment the DICT made the notification available as OPEN (Manual de Tempos do Pix v7.0 §4.2.1.6). Pass the current instant for the ones already expired. explode: false in: query name: analysisDeadlineBefore schema: description: Narrows the page to notifications whose seven-day analysis deadline falls at or before this instant, ordered most-overdue-first instead of newest-first. The deadline is counted from the moment the DICT made the notification available as OPEN (Manual de Tempos do Pix v7.0 §4.2.1.6). Pass the current instant for the ones already expired. examples: - "2026-06-17T12:00:00Z" format: date-time type: string - description: "Lower bound of the same seven-day window: drops notifications whose deadline is at or before this instant. Combine with analysisDeadlineBefore to page exactly one alarm gauge's rows — analysisDeadlineAfter=&analysisDeadlineBefore= is the due-soon set alone, where an upper bound by itself returns every already-expired notification first and can push the actionable rows off the page." explode: false in: query name: analysisDeadlineAfter schema: description: "Lower bound of the same seven-day window: drops notifications whose deadline is at or before this instant. Combine with analysisDeadlineBefore to page exactly one alarm gauge's rows — analysisDeadlineAfter=&analysisDeadlineBefore= is the due-soon set alone, where an upper bound by itself returns every already-expired notification first and can push the actionable rows off the page." examples: - "2026-06-17T12:00:00Z" format: date-time type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionListResponse" 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 DICT infractions tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/list-infractions /api/v1/dict/infractions/{id}: get: description: Retrieves an infraction by its BACEN-assigned resource UUID, projecting the full ExtendedInfractionReport snapshot. operationId: getInfraction parameters: - description: BACEN-assigned infraction resource UUID (the public, canonical identity; a local record UUID never resolves here) in: path name: id required: true schema: description: BACEN-assigned infraction resource UUID (the public, canonical identity; a local record UUID never resolves here) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionResponse" description: Persisted local DICT infraction record 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 DICT infraction tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/get-infraction /api/v1/dict/infractions/{id}/acknowledge: post: description: Transitions an infraction OPEN→ACKNOWLEDGED and reports the transition to BACEN. operationId: acknowledgeInfraction parameters: - description: "BACEN-assigned infraction resource UUID (a local record UUID never resolves here; every mutation route below resolves by this same identity)" in: path name: id required: true schema: description: "BACEN-assigned infraction resource UUID (a local record UUID never resolves here; every mutation route below resolves by this same identity)" format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionMutationResponse" description: Persisted local DICT infraction record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Acknowledge DICT infraction tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/acknowledge-infraction /api/v1/dict/infractions/{id}/cancel: post: description: Transitions an infraction →CANCELLED and reports the transition to BACEN. operationId: cancelInfraction parameters: - description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionMutationResponse" description: Persisted local DICT infraction record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Cancel DICT infraction tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/cancel-infraction /api/v1/dict/infractions/{id}/close: post: description: Transitions an infraction →CLOSED with an AGREED/DISAGREED analysis and reports it to BACEN; on AGREED, BACEN creates the fraud marker. operationId: closeInfraction parameters: - description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseInfractionRequest" description: closeInfractionReport analysis body required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionMutationResponse" description: Persisted local DICT infraction record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Close DICT infraction tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/close-infraction /api/v1/dict/infractions/{id}/refresh: post: description: "Fetches the infraction's current record from BACEN (getInfractionReport) and projects the counterparty-determined outcome onto the local row verbatim: no computation, no interpretation. No scheduler runs this — the operator triggers it explicitly." operationId: refreshInfraction parameters: - description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned infraction resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionResponse" description: Persisted local DICT infraction record 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 "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 "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: Refresh DICT infraction from BACEN tags: - Infractions x-mint: href: /pt/reference/rails/spi/dict/refresh-infraction /api/v1/dict/internal/policies: get: description: "Projects the DICT's own request-limiting state for this participant, verbatim: available tokens, bucket capacity, refill amount and refill period per policy, plus the category (A→H) the BCB assigned — which is what fixes the size and refill of the key-query bucket. Read live from BACEN on every call (nothing is cached here) and never computed locally, so it is the authoritative answer to 'how much DICT quota do we have left'. Supply ?policy= to read a single bucket. Internal admin endpoint." operationId: readDICTPolicyBuckets parameters: - description: Read a single bucket by BACEN's own policy name instead of the whole list. Absent reads every bucket. A name BACEN does not know is answered by BACEN's own refusal, never by an empty bucket. explode: false in: query name: policy schema: description: Read a single bucket by BACEN's own policy name instead of the whole list. Absent reads every bucket. A name BACEN does not know is answered by BACEN's own refusal, never by an empty bucket. examples: - ENTRIES_READ_PARTICIPANT_ANTISCAN type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTPolicyBucketsResponse" description: This deployment's live DICT request-limiting buckets and category. description: OK "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 "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 DICT request-limiting buckets tags: - Internal x-mint: href: /pt/reference/rails/spi/dict/read-dict-policy-buckets /api/v1/dict/internal/query-blocks: delete: description: "Releases a block once the operator has established that the behaviour was justified, or that the suspicion no longer holds: the end user's key queries are served again, subject to the section 13.1 buckets that never stopped applying. Same posture as placing it — one identified operator, mandatory justification, audited under their identity. Idempotent: an end user carrying no block answers 200 with alreadyApplied." operationId: unblockDICTQueryPayer requestBody: content: application/json: schema: $ref: "#/components/schemas/DICTQueryBlockRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTQueryBlockResultResponse" 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 "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: Release an end user's DICT key queries tags: - Internal x-mint: href: /pt/reference/rails/spi/dict/unblock-dict-query-payer post: description: "Stops serving DICT key queries for one end user: DICT 8.4 section 13.2.3's \"o participante deve bloquear imediatamente o(s) usuario(s) em questao\", which the same sentence conditions on a human having verified fundada suspeita and elevado indicio of misuse. Every later key lookup naming this payer is refused 403 before any read — before the retained directory answer and before this deployment's own registry — because the block is a statement about the person, not about our wire traffic. One identified operator, no second approval, mandatory justification, audited under the caller's identity before and after the effect. Idempotent: an end user already blocked answers 200 with alreadyApplied. Name the end user by the CPF/CNPJ the monitor read reports." operationId: blockDICTQueryPayer requestBody: content: application/json: schema: $ref: "#/components/schemas/DICTQueryBlockRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTQueryBlockResultResponse" 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 "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: Block an end user's DICT key queries tags: - Internal x-mint: href: /pt/reference/rails/spi/dict/block-dict-query-payer /api/v1/dict/internal/query-monitor: get: description: "Reports the two query indicators DICT 8.4 section 13.2.3 obliges every participant to keep: DICT key queries per payment order sent to the SPI (VCD/EOS) and NOT FOUND/(NOT FOUND+FOUND), for the participant as a whole and for each end user, over the configured rolling window. It also lists the end users whose own ratio breached the per-user threshold over at least the minimum query count, and the blocks currently in force. A listing is an indication to verify, not a verdict — the section requires a human to establish that the behaviour is unjustified before anyone is blocked. End users appear by their CPF/CNPJ. Internal admin endpoint." operationId: readDICTQueryMonitor responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTQueryMonitorResponse" description: This deployment's live DICT section 13.2.3 indicators, the end users they name, and the blocks in force. 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 "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 DICT query-monitoring indicators tags: - Internal x-mint: href: /pt/reference/rails/spi/dict/read-dict-query-monitor /api/v1/dict/keys: delete: description: Deletes a PIX key by its value through BACEN DICT (signed deleteEntry), then removes this service's own record of it, if it holds one. A key this service does not hold (for example one rebuilt by the participant's VSync) is still deleted at BACEN. A held key under claim is rejected with 409 SPI-3006 before BACEN is called. When a claim freezes the key while the BACEN deletion is in flight, BACEN has removed the entry but this service keeps its record for the claim flow and answers 409 SPI-3007. A BACEN refusal such as EntryBlocked (judicial block) is relayed with its own token and HTTP status, and nothing local changes. BACEN's own NotFound (the directory holds no entry for the key) is relayed the same way, as 404 with code NotFound; a 404 with code SPI-0010 is a not-found BACEN did not name. operationId: deleteKey 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/DeleteKeyRequest" description: PIX key value to delete; a held key is deletable only while ACTIVE required: true responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "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 "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: Delete PIX key tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/delete-key get: description: Returns a paginated list of PIX keys. Optionally filter by participant ISPB. operationId: listKeys parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer - description: Filter by participant ISPB (8 digits or uppercase letters) explode: false in: query name: participantISPB schema: description: Filter by participant ISPB (8 digits or uppercase letters) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/KeyListResponse" 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 keys tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/list-keys post: description: "Registers a new PIX key after validating the request, enforcing the per-account key limit, and successfully synchronizing with BACEN DICT. Registration fails closed if BACEN DICT is unavailable or rejects the key. A refusal BACEN would give for the same rule is answered locally with BACEN's own token and status 400: EntryLimitExceeded (the account holds its key limit), EntryAlreadyExists (the key is held for the same participant and owner), EntryKeyOwnedByDifferentPerson (held for another owner) or EntryKeyInCustodyOfDifferentParticipant (held for the same owner at another participant of this deployment)." operationId: registerKey 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/RegisterKeyRequest" description: PIX key to register (key type, value, owner identity, and participant ISPB); registration fails closed if BACEN DICT rejects or is unavailable required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PIXKeyResponse" description: Registered PIX key with its assigned status description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "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 "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: Register PIX key tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/register-key /api/v1/dict/keys/check: post: description: "Probes up to 200 PIX key values for existence in one call, backed by the BACEN DICT keys/check (dict-np host). Returns one existence-only result per submitted key, in submission order, plus BACEN's own operational envelope (bacen.correlationId / bacen.responseTime) for the probe this call made — one envelope per call, omitted when every verdict was already retained locally and no probe reached BACEN. This capability requires the dict-np seam: a deployment that does not carry it answers 501 with code SPI-1012 — a PERMANENT refusal, not a retryable one, so a client must stop rather than retry. 503 (SPI-1010) keeps its usual meaning here and only that one: BACEN DICT is reachable in principle but down or failing right now, and the call may be retried." operationId: checkKeys requestBody: content: application/json: schema: $ref: "#/components/schemas/CheckKeysRequest" description: Up to 200 PIX key values to probe for existence in one batch (backed by BACEN dict-np keys/check); response is existence-only required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckKeysResponse" description: One existence result per submitted key, in submission order description: OK "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 "501": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Implemented "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: Batch check PIX key existence tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/check-keys /api/v1/dict/keys/lookup: post: description: Looks up a PIX key by JSON body value. This deployment's own key registry is read FIRST — a retained BACEN answer can never outrank a local row (DICT 8.4 §1.1) — and only a key with no local row falls through to the retained BACEN answer and then to BACEN DICT. Returns ownerTaxId full and unmasked per BACEN API-DICT. A BACEN refusal such as EntryBlocked (judicial block) is relayed with its own token and HTTP status. A BACEN DICT answer this deployment cannot accept — a problem body whose signature does not verify, an entry whose account participant is not an ISPB, an entry whose key type and value do not form a valid key, or an entry naming a different key than requested — answers 502 with code SPI-1013 and none of that answer's data. operationId: lookupKey requestBody: content: application/json: schema: $ref: "#/components/schemas/LookupKeyRequest" description: PIX key value to resolve — against this deployment's own key registry first, then a retained BACEN answer, then BACEN DICT required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PIXKeyLookupResponse" description: Resolved PIX key details, including ownerTaxId full and unmasked per BACEN API-DICT description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "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 "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 default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Lookup PIX key tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/lookup-key /api/v1/dict/keys/search: get: description: Searches PIX keys by optional key type, status, and participant ISPB filters. operationId: searchKeys parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer - description: Filter by PIX key type explode: false in: query name: keyType schema: description: Filter by PIX key type enum: - "" - CPF - CNPJ - PHONE - EMAIL - EVP type: string - description: Filter by key status. explode: false in: query name: status schema: description: Filter by key status. enum: - "" - ACTIVE - PENDING_CLAIM type: string - description: Filter by participant ISPB (8 digits or uppercase letters) explode: false in: query name: participantISPB schema: description: Filter by participant ISPB (8 digits or uppercase letters) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/KeyListResponse" 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: Search PIX keys tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/search-keys /api/v1/dict/keys/stats: get: description: Returns PIX key counts grouped by key type and status. operationId: keyStats responses: "200": content: application/json: schema: $ref: "#/components/schemas/KeyStatsResponse" description: PIX key counts grouped by key type and status description: OK "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: PIX key statistics tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/key-stats /api/v1/dict/keys/{key}: get: description: "Reads one PIX key from this deployment's own key registry and nowhere else: BACEN DICT is never called and no retained BACEN answer is consulted, so the read spends no DICT query token and needs no paying end user. The key is answered in any local status (ACTIVE or PENDING_CLAIM), with the participant's requestId. X-ISPB names the participant asking, authorized like the update verb's: this deployment's own direct participant or an active indirect it sponsors (403 otherwise). A key bound to any other participant answers 404 exactly as a key with no row does, so its existence does not leak. The key travels percent-encoded as a path segment." operationId: getKey parameters: - description: "ISPB of the participant asking: this deployment's own direct participant or an active indirect it sponsors. Only a key bound to exactly this participant is answered." in: header name: X-ISPB required: true schema: description: "ISPB of the participant asking: this deployment's own direct participant or an active indirect it sponsors. Only a key bound to exactly this participant is answered." examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: PIX key value, percent-encoded as a path segment (an e-mail's '@' and '+', a phone's leading '+'); matched in canonical form, as the registry stores it. in: path name: key required: true schema: description: PIX key value, percent-encoded as a path segment (an e-mail's '@' and '+', a phone's leading '+'); matched in canonical form, as the registry stores it. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PIXKeyResponse" description: The PIX key as this deployment's registry holds it, in any local status 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 "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 "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: Get PIX key tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/get-pix-key put: description: "Updates a PIX key's mutable bindings (account branch/number/type and owner name/trade name) and reports the change to BACEN DICT (signed updateEntry). keyType and ownerTaxId are immutable; an attempt to change them is rejected. The body carries no participant: for a held key the wire Participant is its stored owning participant, so this verb can never rebind a key to another participant. A key this service does not hold (for example one rebuilt by the participant's VSync) is updated at BACEN on the binding the caller states — X-ISPB, keyType and ownerTaxId, plus accountNumber, accountType and openingDate when the account moves — and nothing local is written. A BACEN refusal such as EntryBlocked (judicial block) is relayed with its own token and HTTP status." operationId: updateKey parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: ISPB of the participant the key is bound to, authorized like any other participant this deployment acts for. Required for a key this service does not hold (for example one rebuilt by the participant's VSync); for a held key it may only restate the stored participant. in: header name: X-ISPB schema: description: ISPB of the participant the key is bound to, authorized like any other participant this deployment acts for. Required for a key this service does not hold (for example one rebuilt by the participant's VSync); for a held key it may only restate the stored participant. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string - description: PIX key value to update (the immutable identifier). in: path name: key required: true schema: description: PIX key value to update (the immutable identifier). type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateKeyRequest" description: Mutable key fields (account + owner name/trade name) and the update reason; keyType and ownerTaxId are immutable and rejected if changed. required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PIXKeyResponse" description: Updated PIX key with its mutable fields applied description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "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 "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 "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: Update PIX key tags: - Keys x-mint: href: /pt/reference/rails/spi/dict/update-key /api/v1/dict/operations: get: description: "Enumerates durable MED operation-intent statuses — the operator surface: no pending status, including MANUAL_REVIEW, is invisible. Optional status/kind facets; cursor-paginated (the underlying table is actively mutated by the sweep, so an offset page could skip or repeat a row). Same sanitized per-item projection as GET /operations/{id}." operationId: listRegulatoryOperations parameters: - description: "Optional facet: restrict to operations in this status. Omit for any status." explode: false in: query name: status schema: description: "Optional facet: restrict to operations in this status. Omit for any status." enum: - "" - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - REJECTED - UNKNOWN_OUTCOME - MANUAL_REVIEW - ABANDONED - COMPLETED - LOCAL_FAILURE type: string - description: "Optional facet: restrict to operations for this MED resource kind. Omit for any kind." explode: false in: query name: kind schema: description: "Optional facet: restrict to operations for this MED resource kind. Omit for any kind." enum: - "" - infraction - refund - fraud_marker - funds_recovery type: string - description: Page size (default 25, max 100). explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100). format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque continuation token from a prior page's nextCursor; omit for the first page. explode: false in: query name: cursor schema: description: Opaque continuation token from a prior page's nextCursor; omit for the first page. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegulatoryOperationListResponse" description: One page of durable MED operation-intent statuses. 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: List DICT MED operation statuses tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/list-regulatory-operations /api/v1/dict/operations/{id}: get: description: "Retrieves a durable MED operation intent's status by its own id (operationId) — the identity a create/lifecycle-transition backlog route returns or references on every outcome. Status only: kind, verb, status, the BACEN resource id once known, timestamps, and BACEN's sanitized envelope. Never the original request body, tax id, key, account, or analysis details." operationId: getRegulatoryOperation parameters: - description: Durable MED operation-intent id (operationId), returned by a create/lifecycle-transition backlog route on every outcome — synchronous success, a 202 pending outcome, or a rejection. in: path name: id required: true schema: description: Durable MED operation-intent id (operationId), returned by a create/lifecycle-transition backlog route on every outcome — synchronous success, a 202 pending outcome, or a rejection. format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegulatoryOperationResponse" description: Durable MED operation-intent status. 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 DICT MED operation status tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/get-regulatory-operation /api/v1/dict/operations/{operationId}/resolution: post: description: "Relays a four-eyes ATTACH_BACEN_RESOURCE or CONFIRM_NOT_APPLIED decision for a MANUAL_REVIEW durable MED operation intent. ATTACH_BACEN_RESOURCE authoritative-GETs the proposed BACEN resource and validates it against this operation's own reserved business identity BEFORE ever associating it, then applies the snapshot and completes the operation. CONFIRM_NOT_APPLIED declares BACEN never received the attempt, freeing the resource for the client's own retry via its existing X-Idempotency. Idempotent by the request's own X-Idempotency: a replayed delivery of the SAME decision returns the original outcome without repeating any side effect. A failed GET or a business-identity mismatch never transitions anything — the operation stays MANUAL_REVIEW." operationId: resolveRegulatoryOperation parameters: - description: The MANUAL_REVIEW operation's own id (operationId). in: path name: operationId required: true schema: description: The MANUAL_REVIEW operation's own id (operationId). format: uuid type: string - description: The approval's own id — the SAME value on every delivery attempt of this exact decision, so a replayed callback returns the original outcome instead of repeating any side effect. in: header name: X-Idempotency required: true schema: description: The approval's own id — the SAME value on every delivery attempt of this exact decision, so a replayed callback returns the original outcome instead of repeating any side effect. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ResolveRegulatoryOperationRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegulatoryOperationResponse" description: Durable MED operation-intent status. 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 "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 "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: Resolve a MANUAL_REVIEW DICT MED operation tags: - Operations x-mint: href: /pt/reference/rails/spi/dict/resolve-regulatory-operation /api/v1/dict/participants/{participantISPB}/claims: post: description: Initiates a new PIX key ownership or portability claim for the participant identified in the route. Claim deadlines are seven calendar days and claimer/donor ISPB equality is rejected by domain validation. operationId: initiateClaim parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string - description: Claiming participant ISPB (8 digits or uppercase letters) in: path name: participantISPB required: true schema: description: Claiming participant ISPB (8 digits or uppercase letters) type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InitiateClaimRequest" description: PIX key ownership or portability claim to initiate (seven-day deadline; claimer and donor ISPB must differ) required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Claim record with its current status and deadlines 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 "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: Initiate claim tags: - Claims x-mint: href: /pt/reference/rails/spi/dict/initiate-claim /api/v1/dict/persons/statistics: post: description: Fetches BACEN's system-wide person-level antifraud statistics by tax id from the authenticated JSON body and projects them verbatim, with no local aggregation (distinct from local fraud-marker stats). A tax id BACEN DICT does not know answers 404 with code SPI-1014; any other BACEN DICT refusal answers 422 with code SPI-1011. operationId: getPersonStatistics requestBody: content: application/json: schema: $ref: "#/components/schemas/GetPersonStatisticsRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersonStatisticsResponse" description: BACEN-served person antifraud statistics, projected verbatim 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 "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 "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: Get BACEN person antifraud statistics tags: - Statistics x-mint: href: /pt/reference/rails/spi/dict/get-person-statistics /api/v1/dict/persons/watchlist: get: description: Lists the documents under antifraud surveillance with the freshness of each one's last observation. BACEN's counters lag reality by up to 12 hours by regulation, so lastWatermark — BACEN's own marker — is the honest 'as of when', never the read time. operationId: listPersonWatchlist parameters: - description: Include entries whose surveillance was stopped. Default false. explode: false in: query name: includeRemoved schema: description: Include entries whose surveillance was stopped. Default false. type: boolean responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersonWatchlistListResponse" description: OK headers: Cache-Control: schema: type: string "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 watched CPFs/CNPJs tags: - Statistics x-mint: href: /pt/reference/rails/spi/dict/list-person-watchlist post: description: "Admits a document to the antifraud watchlist. Once watched, BACEN's ecosystem-wide antifraud counters for that document (getPersonStatistics) are observed on a configured cadence, and a canonical observation fact is emitted whenever BACEN's own watermark moves. Idempotent: re-adding a watched document changes nothing; re-adding a removed one resumes it with its dedupe baseline intact. Rejected with 422 once the participant's document cap is reached, because every watched document is a recurring call against a shared BACEN budget." operationId: addPersonWatchlistDocument requestBody: content: application/json: schema: $ref: "#/components/schemas/PersonWatchlistAddRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PersonWatchlistEntryResponse" description: Created "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: Watch a CPF/CNPJ for antifraud signal tags: - Statistics x-mint: href: /pt/reference/rails/spi/dict/add-person-watchlist-document /api/v1/dict/persons/watchlist/{id}: delete: description: "Stops observing a document. This is a soft stop: polling ceases immediately, and every observation fact already emitted stays emitted — nothing is retracted or deleted. Re-adding the same document later resumes the same entry." operationId: removePersonWatchlistDocument parameters: - description: Entry id returned by add/list. in: path name: id required: true schema: description: Entry id returned by add/list. format: uuid type: string responses: "204": description: No Content "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: Stop watching a CPF/CNPJ tags: - Statistics x-mint: href: /pt/reference/rails/spi/dict/remove-person-watchlist-document /api/v1/dict/refunds: get: description: Returns paginated local DICT refund records. operationId: listRefunds parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundListResponse" 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 DICT refunds tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/list-refunds post: description: Persists a DICT refund request locally and submits the corresponding BACEN refund synchronously-after-persist, tracked by request_id; report_status is SENT at rest. operationId: createRefund parameters: - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateRefundRequest" description: DICT refund request reported to BACEN first; only a CONFIRMED report is persisted locally — a rejection or ambiguous outcome creates no local row. Tracked by report_status=SENT + a durable operation intent (operationId) while pending. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RefundMutationResponse" description: Persisted local DICT refund request record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: Created headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Create DICT refund tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/create-refund /api/v1/dict/refunds/{id}: get: description: Retrieves a refund by its BACEN-assigned resource UUID, projecting the full ExtendedRefund snapshot. operationId: getRefund parameters: - description: BACEN-assigned refund resource UUID (the public, canonical identity; a local record UUID never resolves here) in: path name: id required: true schema: description: BACEN-assigned refund resource UUID (the public, canonical identity; a local record UUID never resolves here) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundResponse" description: Persisted local DICT refund request record 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 DICT refund tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/get-refund /api/v1/dict/refunds/{id}/cancel: post: description: Transitions a refund OPEN→CANCELLED (payer side, while still open) and reports it to BACEN. operationId: cancelRefund parameters: - description: BACEN-assigned refund resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned refund resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundMutationResponse" description: Persisted local DICT refund request record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Cancel DICT refund tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/cancel-refund /api/v1/dict/refunds/{id}/close: post: description: Transitions a refund OPEN→CLOSED with an analysisResult (TOTALLY_ACCEPTED|PARTIALLY_ACCEPTED|REJECTED) and reports it to BACEN. operationId: closeRefund parameters: - description: BACEN-assigned refund resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned refund resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseRefundRequest" description: closeRefund analysis body required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundMutationResponse" description: Persisted local DICT refund request record, or {operationId, operationStatus} while BACEN's outcome is pending (202). description: OK headers: Location: schema: description: GET /api/v1/dict/operations/{operationId}; present only on a 202 response. type: string "202": content: application/json: schema: properties: operationId: description: Durable MED operation-intent id; present only while the outcome is pending (202). format: uuid type: string operationStatus: description: Durable operation-intent status; present only while the outcome is pending (202). Never REJECTED or LOCAL_FAILURE — each maps to its own terminal HTTP status instead of a 202. enum: - RESERVED - SUBMITTED - CONFIRMED - SYNC_PENDING - UNKNOWN_OUTCOME - MANUAL_REVIEW - COMPLETED type: string required: - operationId - operationStatus type: object description: "BACEN's outcome for this mutation is not yet resolved into a persisted resource: an ambiguous BACEN answer (reconciliation pending) or a BACEN-confirmed write whose own local persistence failed (MANUAL_REVIEW). Poll GET /api/v1/dict/operations/{operationId} — this response's own Location header — for the eventual resolution." headers: Location: description: GET /api/v1/dict/operations/{operationId} for the eventual resolution. schema: format: uri-reference type: string "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 "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: Close DICT refund tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/close-refund /api/v1/dict/refunds/{id}/refresh: post: description: "Fetches the refund's current record from BACEN (getRefund) and projects the counterparty-determined outcome onto the local row verbatim: no computation, no interpretation. No scheduler runs this — the operator triggers it explicitly." operationId: refreshRefund parameters: - description: BACEN-assigned refund resource UUID; a local record UUID never resolves here in: path name: id required: true schema: description: BACEN-assigned refund resource UUID; a local record UUID never resolves here format: uuid type: string - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundResponse" description: Persisted local DICT refund request record 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 "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 "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: Refresh DICT refund from BACEN tags: - Refunds x-mint: href: /pt/reference/rails/spi/dict/refresh-refund /api/v1/dict/reports/claims-summary: get: description: Returns COUNT(*) buckets grouped by (claimType, status) over claims requested in a mandatory date window (max 92 days), plus the COUNT of currently-open claims past their 7-day deadline. COUNT-only. Infraction summaries are out of scope. operationId: getDICTReportClaimsSummary 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: "Optional: when true, adds the per-indirect-participant dimension to the COUNT(*) GROUP BY. COUNT-only either way." explode: false in: query name: groupByParticipant schema: description: "Optional: when true, adds the per-indirect-participant dimension to the COUNT(*) GROUP BY. COUNT-only either way." examples: - false type: boolean responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTClaimsSummaryResponse" 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: DICT claims-summary report (COUNT-only) tags: - Reports x-mint: href: /pt/reference/rails/spi/dict/get-dict-report-claims-summary /api/v1/dict/reports/keys-summary: get: description: Returns COUNT(*) buckets grouped by (keyType, status) over PIX keys registered in a mandatory date window (max 92 days). COUNT-only — DICT holds no money. Raw key values are never returned. operationId: getDICTReportKeysSummary 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: "Optional: when true, adds the per-indirect-participant dimension to the COUNT(*) GROUP BY. COUNT-only either way." explode: false in: query name: groupByParticipant schema: description: "Optional: when true, adds the per-indirect-participant dimension to the COUNT(*) GROUP BY. COUNT-only either way." examples: - false type: boolean responses: "200": content: application/json: schema: $ref: "#/components/schemas/DICTKeysSummaryResponse" 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: DICT keys-summary report (COUNT-only) tags: - Reports x-mint: href: /pt/reference/rails/spi/dict/get-dict-report-keys-summary /api/v1/dict/sync-verifications: post: description: Sends the participant's sync verifier (the XOR of its active CIDs of one key type) to BACEN's createSyncVerification and returns BACEN's OK/NOK verdict verbatim. NOK means the CID sets diverge; resolve it with the CID set file and GET cids/entries/{cid}. The participant comes from X-ISPB. operationId: createDICTSyncVerification parameters: - description: Required key used to prevent replaying the mutation. in: header name: X-Idempotency required: true schema: description: Required key used to prevent replaying the mutation. type: string - description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. in: header name: X-ISPB required: true schema: description: ISPB of the participant the call acts for. It must be this deployment's direct participant or an indirect it sponsors; the body never carries it. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateSyncVerificationRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/SyncVerificationResponse" description: Created "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 "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 "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: Verify a CID set against BACEN tags: - VSync x-mint: href: /pt/reference/rails/spi/dict/verify-a-cid-set-against-bacen servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. tags: - description: "PIX key lifecycle: register, list, search, lookup, delete, and statistics." name: Keys - description: PIX key portability and ownership claims through their full lifecycle (initiate, confirm, reject, cancel, acknowledge, complete). name: Claims - description: "DICT infraction reports: list and retrieve." name: Infractions - description: "DICT refund requests: create, list, and retrieve." name: Refunds - description: "PIX fraud markers: create, list, and statistics." name: Fraud Markers - description: "Durable MED operation-intent status: the operationId every create/lifecycle-transition backlog route returns or references on every outcome, queryable independently of the business resource." name: Operations - description: "Synchronous reports over Lerian SPI's own DICT record: COUNT(*) summaries of keys (by type/status) and claims (by type/status + open-past-deadline). COUNT-only — DICT holds no money." name: Reports - description: "Internal DICT operations: claim deadline processing." name: Internal - description: "DICT synchronism checks transported to BACEN for the participant named in X-ISPB: sync verification, CID resolution and CID set events, projected verbatim." name: VSync