openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for Pix keys, claims, fraud markers, infraction reports, and MED funds recovery. license: name: Lerian Studio General License title: Pix Lerian — DICT version: 1.1.0 servers: - url: https://api.example.com/dict-hub/v1 description: Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Manage ownership and portability claims for Pix keys. name: Claims - description: Register, retrieve, list, update, and remove Pix keys. name: Entries - description: Create, query, list, and cancel DICT fraud markers. name: Fraud Markers - description: Manage participant-scoped MED 2.0 funds recoveries. name: Funds Recoveries - description: Manage MED 2.0 infraction reports for the authenticated organization. name: Infraction Reports - description: Look up Pix keys and check whether keys exist in the DICT directory. name: Keys - description: Create, query, cancel, and settle MED 2.0 refunds. name: Refunds paths: /claims: get: description: 'Returns a paginated list of Pix claims for the tenant. X-Account-Id is optional: when provided the listing is scoped to that account (as claimer or donor); when omitted it spans the tenant''s full organization-scoped claim set. The role/status/type/key_type filters are repeatable and case-insensitive (OR within a filter, AND across filters). List items omit the per-claim events[]; use get-by-id for the full event history.' operationId: listClaims x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-claims parameters: - description: Account UUID (optional). When omitted, lists all of the tenant's claims; when provided, scopes the listing to that account. in: header name: X-Account-Id schema: description: Account UUID (optional). When omitted, lists all of the tenant's claims; when provided, scopes the listing to that account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: 'Filter by the account''s role in the claim (repeatable, case-insensitive): CLAIMER, DONOR' explode: true in: query name: role schema: description: 'Filter by the account''s role in the claim (repeatable, case-insensitive): CLAIMER, DONOR' examples: - - CLAIMER items: type: string type: - array - 'null' - description: 'Filter by claim status (repeatable, case-insensitive): OPEN, WAITING_RESOLUTION, CONFIRMED, COMPLETED, CANCELLED' explode: true in: query name: status schema: description: 'Filter by claim status (repeatable, case-insensitive): OPEN, WAITING_RESOLUTION, CONFIRMED, COMPLETED, CANCELLED' examples: - - OPEN items: type: string type: - array - 'null' - description: 'Filter by claim type (repeatable, case-insensitive): PORTABILITY, OWNERSHIP' explode: true in: query name: type schema: description: 'Filter by claim type (repeatable, case-insensitive): PORTABILITY, OWNERSHIP' examples: - - OWNERSHIP items: type: string type: - array - 'null' - description: 'Filter by key type (repeatable, case-insensitive): CPF, CNPJ, EMAIL, PHONE, EVP' explode: true in: query name: key_type schema: description: 'Filter by key type (repeatable, case-insensitive): CPF, CNPJ, EMAIL, PHONE, EVP' examples: - - EMAIL items: type: string type: - array - 'null' - description: Filter claims created on or after this date (YYYY-MM-DD) explode: false in: query name: start_date schema: description: Filter claims created on or after this date (YYYY-MM-DD) examples: - '2026-05-01' type: string - description: Filter claims created on or before this date (YYYY-MM-DD) explode: false in: query name: end_date schema: description: Filter claims created on or before this date (YYYY-MM-DD) examples: - '2026-05-31' type: string - description: Page number (1-based, default 1) explode: false in: query name: page schema: description: Page number (1-based, default 1) examples: - '1' type: string - description: Rows per page (default 20, max 100) explode: false in: query name: limit schema: description: Rows per page (default 20, max 100) examples: - '20' type: string - description: Sort direction by createdAt (default desc, case-insensitive) explode: false in: query name: sort_order schema: description: Sort direction by createdAt (default desc, case-insensitive) examples: - desc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListClaimsOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' description: Service Unavailable (PIX-0164). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List Pix key claims tags: - Claims post: description: Opens a Pix key claim of type PORTABILITY or OWNERSHIP on behalf of the claimant account identified by X-Account-Id. The request body contains only the key and claim type; keyType is derived from the key format. A claimant salary account (SLRY) cannot take a new key binding, so the claim is refused with 422 PIX-0176. operationId: createClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/create-claim parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Claimer CRM account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Claimer CRM account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateClaimBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateClaimOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116, PIX-0176). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0032 title: Idempotency Unavailable message: The request was not processed because the idempotency store is unavailable. Please retry. reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0169 title: Claim Mutations Temporarily Blocked message: "Claim mutations are temporarily blocked: reconciliation in progress." application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' description: Service Unavailable (PIX-0164). An active VSync reconciliation for the organization, under any key type, blocks claim mutations, so the request was refused before it ran; retry after the reconciliation ends (PIX-0169). Legacy {code,title,message} envelope, NOT problem+json. Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Open a Pix key claim tags: - Claims /claims/{claim_id}: get: description: Retrieves a Pix claim by its identifier, including events[] in ascending createdAt order. The claim must belong to the account identified by X-Account-Id. A claim outside that scope returns the same not-found response as an unknown claim. operationId: getClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-claim parameters: - description: Claim ID (UUID format) in: path name: claim_id required: true schema: description: Claim ID (UUID format) examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetClaimOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' description: Service Unavailable (PIX-0164). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a Pix key claim tags: - Claims /claims/{claim_id}/acknowledge: post: description: Acknowledges an OPEN donor-side Pix key claim when the automatic acknowledgement needs to be retried. The caller must be the donor participant. The operation has no request body. operationId: acknowledgeClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/acknowledge-claim parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - in: path name: claim_id required: true schema: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string responses: '202': content: application/json: schema: $ref: '#/components/schemas/AcknowledgeClaimResponse' description: Accepted '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116, PIX-0182). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' application/json: examples: reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0169 title: Claim Mutations Temporarily Blocked message: "Claim mutations are temporarily blocked: reconciliation in progress." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Service Unavailable (PIX-0164). An active VSync reconciliation for the organization, under any key type, blocks claim mutations, so the request was refused before it ran; retry after the reconciliation ends (PIX-0169). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Acknowledge a Pix key claim tags: - Claims /claims/{claim_id}/cancel: post: description: 'Cancels an in-progress claim at the request of either party: withdrawal by the claimant or refusal by the donor. The endpoint takes no request body and determines whether the account acts as CLAIMER or DONOR. Cancellation remains available while claim data is being reconciled.' operationId: cancelClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/cancel-claim parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - in: path name: claim_id required: true schema: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - in: header name: X-Account-Id schema: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Reason for the cancellation. The enum lists the canonical uppercase spelling; the server also accepts other casing and normalizes it, but clients SHOULD send the canonical form. in: header name: X-Reason required: true schema: description: Reason for the cancellation. The enum lists the canonical uppercase spelling; the server also accepts other casing and normalizes it, but clients SHOULD send the canonical form. enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - COURT_ORDER examples: - USER_REQUESTED maxLength: 64 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CancelClaimOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116, PIX-0182). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' description: Service Unavailable (PIX-0164). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Cancel a Pix key claim tags: - Claims /claims/{claim_id}/complete: post: description: Completes the claim after directory confirmation and finalizes the Pix key binding to the claimant. This operation is available only to the claimant, takes no request body, and does not use X-Reason. operationId: completeClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/complete-claim parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - in: path name: claim_id required: true schema: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - in: header name: X-Account-Id schema: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompleteClaimOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116, PIX-0182). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' application/json: examples: reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0169 title: Claim Mutations Temporarily Blocked message: "Claim mutations are temporarily blocked: reconciliation in progress." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Service Unavailable (PIX-0164). An active VSync reconciliation for the organization, under any key type, blocks claim mutations, so the request was refused before it ran; retry after the reconciliation ends (PIX-0169). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Complete a Pix key claim tags: - Claims /claims/{claim_id}/confirm: post: description: Confirms an in-progress claim on behalf of the donor. The endpoint takes no request body; the reason is supplied in the X-Reason header. The account must be the claim donor. Claims outside the account scope return the same not-found response as unknown claims. operationId: confirmClaim x-mint: href: /pt/reference/interfaces/pix-lerian/dict/confirm-claim parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - in: path name: claim_id required: true schema: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - in: header name: X-Account-Id schema: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Reason for the confirmation. The enum lists the canonical uppercase spelling; the server also accepts other casing and normalizes it, but clients SHOULD send the canonical form. in: header name: X-Reason required: true schema: description: Reason for the confirmation. The enum lists the canonical uppercase spelling; the server also accepts other casing and normalizes it, but clients SHOULD send the canonical form. enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION examples: - USER_REQUESTED maxLength: 64 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConfirmClaimOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0142, PIX-0143). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0145 title: Not Found status: 404 detail: No claim was found for the given identifier and account. code: PIX-0145 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0145). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0144 title: Conflict status: 409 detail: The X-Request-Id was already seen with a different request body. code: PIX-0144 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0144). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0146 title: Unprocessable Entity status: 422 detail: The requested claim type and key type combination is not supported. code: PIX-0146 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0146, PIX-0147, PIX-0149, PIX-0163, PIX-0165, PIX-0166, PIX-0167, PIX-0168, PIX-0171, PIX-0172, PIX-0173, PIX-0116, PIX-0182). '429': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0148 title: Too Many Requests status: 429 detail: The rate limit for this claim operation has been exceeded. code: PIX-0148 schema: $ref: '#/components/schemas/Detail' description: Too Many Requests (PIX-0148). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140). '503': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0164 title: Service Unavailable status: 503 detail: internal error code: PIX-0164 schema: $ref: '#/components/schemas/Detail' application/json: examples: reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0169 title: Claim Mutations Temporarily Blocked message: "Claim mutations are temporarily blocked: reconciliation in progress." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Service Unavailable (PIX-0164). An active VSync reconciliation for the organization, under any key type, blocks claim mutations, so the request was refused before it ran; retry after the reconciliation ends (PIX-0169). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Confirm a Pix key claim tags: - Claims /dict/fraud-markers: get: description: 'Returns the fraud markers registered for the required tax_id_number within the participant scope determined by the authenticated tenant. Optional filters are key, status (REGISTERED or CANCELLED), modified_after and modified_before (RFC3339), and limit (1 to 200). limit has no default and is applied only when provided. The listing serves only a numeric CPF or CNPJ: an alphanumeric CNPJ passes validation and is then refused with 400 / PIX-0020. total is the number of markers in this page, not a count of every match; hasMoreElements says whether more markers match.' operationId: listFraudMarkers x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-fraud-markers parameters: - description: CPF or CNPJ (numeric or alphanumeric per IN RFB 2.229/2024) to filter by, checked against BACEN/RFB check digits. Mask, surrounding whitespace, and lowercase are accepted and normalized to the canonical unformatted uppercase form before use. explode: false in: query name: tax_id_number required: true schema: description: CPF or CNPJ (numeric or alphanumeric per IN RFB 2.229/2024) to filter by, checked against BACEN/RFB check digits. Mask, surrounding whitespace, and lowercase are accepted and normalized to the canonical unformatted uppercase form before use. examples: - '12345678901' type: string - description: Optional Pix key filter. Maximum 77 BYTES UTF-8, not characters -- see CreateFraudMarkerBody.Key. explode: false in: query name: key schema: description: Optional Pix key filter. Maximum 77 BYTES UTF-8, not characters -- see CreateFraudMarkerBody.Key. examples: - user@example.com type: string - description: Optional status filter explode: false in: query name: status schema: description: Optional status filter enum: - REGISTERED - CANCELLED examples: - REGISTERED type: string - description: Optional RFC 3339 lower bound on lastModified explode: false in: query name: modified_after schema: description: Optional RFC 3339 lower bound on lastModified examples: - '2026-08-01T00:00:00Z' format: date-time type: string - description: Optional RFC 3339 upper bound on lastModified explode: false in: query name: modified_before schema: description: Optional RFC 3339 upper bound on lastModified examples: - '2026-08-19T23:59:59Z' format: date-time type: string - description: Optional page size, 1..200 explode: false in: query name: limit schema: description: Optional page size, 1..200 examples: - '50' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListDICTFraudMarkersOutput' description: Matching fraud markers (possibly empty). '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Missing or malformed query parameter -- taxIdNumber absent, limit outside 1..200, status outside its domain, or an invalid modifiedAfter/modifiedBefore -- or a query the provider refused, such as an alphanumeric CNPJ, which the live listing does not serve (PIX-0020). '429': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider rate-limited this operation; retry later (PIX-0134). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider adapter call failed outright -- an unreachable adapter or an unclassified upstream failure (PIX-0141). '504': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider call did not complete within its deadline (PIX-0054). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: List fraud markers tags: - Fraud Markers post: description: "Registers a DICT fraud marker for the taxpayer identified by taxIdNumber, optionally linked to a Pix key. requestId is the caller-provided idempotency key. Repeating a requestId with the same payload returns the same marker; repeating it with a different payload is rejected. The participant is determined by the authenticated tenant. When BACEN's outcome is not known yet, the operation answers the retryable 502 / PIX-0141: nothing is registered here, and BACEN may still register the marker. Resend with the same requestId until the answer is not 502 / PIX-0141; a new requestId can register a second marker. A 504 / PIX-0054 leaves the outcome unknown too: resend it the same way." operationId: createFraudMarker x-mint: href: /pt/reference/interfaces/pix-lerian/dict/create-fraud-marker requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateFraudMarkerBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/DICTFraudMarker' description: Fraud marker registered. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Malformed taxIdNumber, fraudType, requestId or key (PIX-0003), or requestId already used with a different payload (PIX-0132). '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The requesting participant is not authorized to perform this operation at the provider (PIX-0133). '429': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider rate-limited this operation; retry later (PIX-0134). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider adapter call failed outright -- an unreachable adapter, an unclassified upstream failure, or a BACEN outcome the provider could not state yet (PIX-0141). Resend with the same requestId. '504': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider call did not complete within its deadline (PIX-0054), so whether BACEN registered the marker is unknown. Resend with the same requestId. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The provider answered a state conflict (PIX-0131). "422": content: application/problem+json: example: title: Unprocessable Entity status: 422 detail: validation failed errors: - message: "json: cannot unmarshal number into Go struct field CreateFraudMarkerBody.taxIdNumber of type string" location: body schema: $ref: "#/components/schemas/Detail" description: "The request body could not be decoded into this operation's schema -- malformed JSON, or a field of the wrong JSON type. This is the FRAMEWORK's refusal, not one of this service's: it carries no PIX-NNNN code and locates the failure at `body` in `errors`. A body that decodes but fails this operation's own rules is the 400 above instead." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Create a fraud marker tags: - Fraud Markers /dict/fraud-markers/{fraud_marker_id}: get: description: Retrieves a DICT fraud marker by its directory resource ID. This operation is not restricted to markers owned by the requesting participant. Under the Central Bank of Brazil contract, the documented outcomes are 200 and 404; 404 is returned when the resource ID is unknown. operationId: getFraudMarker x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-fraud-marker parameters: - description: Directory fraud-marker id (UUID) in: path name: fraud_marker_id required: true schema: description: Directory fraud-marker id (UUID) examples: - 0b843bcc-7c1a-4a12-9c88-8d3a5d70e6a1 format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DICTFraudMarker' description: The fraud marker. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Malformed fraud_marker_id path parameter -- not a UUID (PIX-0015). '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No fraud marker exists with this id at the provider (PIX-0130). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider adapter call failed outright -- an unreachable adapter or an unclassified upstream failure (PIX-0141). '504': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider call did not complete within its deadline (PIX-0054). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Get a fraud marker tags: - Fraud Markers /dict/fraud-markers/{fraud_marker_id}/cancel: post: description: 'Cancels a DICT fraud marker by its directory resource ID within the scope of the participant determined by the authenticated tenant. The request has no body. Cancelling an already-CANCELLED marker is idempotent and returns 200 without changes. Returns 404 for an unknown resource ID, 403 when the participant is not authorized to cancel the marker, and 409 for another state conflict. When BACEN has not resolved the cancellation yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. A later Get fraud marker shows the change BACEN applies. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation.' operationId: cancelFraudMarker x-mint: href: /pt/reference/interfaces/pix-lerian/dict/cancel-fraud-marker parameters: - description: Directory fraud-marker id (UUID) in: path name: fraud_marker_id required: true schema: description: Directory fraud-marker id (UUID) examples: - 0b843bcc-7c1a-4a12-9c88-8d3a5d70e6a1 format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DICTFraudMarker' description: The cancelled marker (status CANCELLED). Also returned, unchanged, on an idempotent re-cancel of an already-CANCELLED marker. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Malformed fraud_marker_id path parameter -- not a UUID (PIX-0015). '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The requesting participant is not authorized to perform this operation at the provider (PIX-0133). '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No fraud marker exists with this id at the provider (PIX-0130). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider accepted the request but BACEN has not resolved it yet (PIX-0118); errors[] carries operationId and operationStatus when the provider sent valid values. Any other 409 the provider answers is a genuine state conflict unrelated to idempotent re-cancellation (PIX-0131). '429': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider rate-limited this operation; retry later (PIX-0134). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider adapter call failed outright -- an unreachable adapter or an unclassified upstream failure (PIX-0141). '504': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The provider call did not complete within its deadline (PIX-0054). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Cancel a fraud marker tags: - Fraud Markers /dict/funds-recoveries: get: description: Returns a paginated list of funds recoveries owned by the requesting participant, newest first by default. The listing is always scoped to the participant (ISPB) resolved from the authenticated tenant context; account_id is an optional accessory filter, not a tenant boundary. modified_after / modified_before are RFC3339 timestamps filtering updatedAt exclusively; start_date / end_date are YYYY-MM-DD dates filtering createdAt inclusively. status and sort_order are case-insensitive. The response echoes the filtered total, the applied page/limit, and hasMore. operationId: listFundsRecoveries x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-funds-recoveries parameters: - description: "Filter by lifecycle status (case-insensitive): PENDING, CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, CANCELLED" explode: false in: query name: status schema: description: "Filter by lifecycle status (case-insensitive): PENDING, CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, CANCELLED" examples: - CREATED type: string - description: 'Filter by situation type: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN' explode: false in: query name: situation_type schema: description: 'Filter by situation type: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN' examples: - SCAM type: string - description: Filter by the root transaction id explode: false in: query name: root_transaction_id schema: description: Filter by the root transaction id examples: - E12345678202605171530aB3xK9mWq2z type: string - description: Filter by client account UUID within the participant explode: false in: query name: account_id schema: description: Filter by client account UUID within the participant examples: - 550e8400-e29b-41d4-a716-446655440000 type: string - description: Return rows updated strictly after this RFC3339 timestamp explode: false in: query name: modified_after schema: description: Return rows updated strictly after this RFC3339 timestamp examples: - '2026-05-17T13:30:00Z' type: string - description: Return rows updated strictly before this RFC3339 timestamp explode: false in: query name: modified_before schema: description: Return rows updated strictly before this RFC3339 timestamp examples: - '2026-05-18T13:30:00Z' type: string - description: Return rows created on or after this date (YYYY-MM-DD) explode: false in: query name: start_date schema: description: Return rows created on or after this date (YYYY-MM-DD) examples: - '2026-05-01' type: string - description: Return rows created on or before this date (YYYY-MM-DD, inclusive of the whole day) explode: false in: query name: end_date schema: description: Return rows created on or before this date (YYYY-MM-DD, inclusive of the whole day) examples: - '2026-05-31' type: string - description: Return rows whose metadata contains this JSON object explode: false in: query name: metadata schema: description: Return rows whose metadata contains this JSON object examples: - '{"channel":"mobile"}' type: string - description: Page number (1-based, default 1) explode: false in: query name: page schema: description: Page number (1-based, default 1) examples: - '1' type: string - description: Maximum items per page (default 10, max 100) explode: false in: query name: limit schema: description: Maximum items per page (default 10, max 100) examples: - '10' type: string - description: 'Sort direction by created_at (default desc, case-insensitive): asc or desc' explode: false in: query name: sort_order schema: description: 'Sort direction by created_at (default desc, case-insensitive): asc or desc' examples: - desc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListFundsRecoveriesOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List funds recoveries tags: - Funds Recoveries post: description: 'Opens a MED 2.0 funds recovery. A successful creation returns HTTP 201 with status CREATED. When BACEN has not resolved the creation yet, the recovery is stored as PENDING with an empty bacenFundsRecoveryId and returned with HTTP 202: keep its id and use it for every later operation. A PENDING recovery resolves when it is next read or operated on, or when the provider reports on it: it then reads as CREATED with its bacenFundsRecoveryId or, when BACEN never applied the creation, it is withdrawn and reads as 404 / PIX-0110, which frees the root transaction for a new creation. While it is PENDING, cancel, refund, and patch return 409 / PIX-0114, the tracking graph returns 404 / PIX-0110, and the linked lists are empty. Reusing an X-Idempotency header returns the original 201 or 202 response with HTTP 200; a failed creation is not cached, so repeating it runs the creation again. A duplicate recovery is rejected with 409 / PIX-0113. If the timestamp in rootTransactionId is outside the applicable MED contestation window, the request is rejected with 422 / PIX-0117. The window is determined by the funds recovery creation time: pacs.008 uses 80 calendar days; pacs.004 uses 30 calendar days before 2026-09-01T00:00:00Z and 80 calendar days from that instant onward. This timestamp validation does not confirm that the referenced transaction exists. The participant is determined by the authenticated tenant. participantId, reporterParticipant, rootTransactionType, and idempotencyKey are rejected when included in the body. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait.' operationId: createFundsRecovery x-mint: href: /pt/reference/interfaces/pix-lerian/dict/create-funds-recovery parameters: - description: Idempotency key (at most 64 bytes); required on create. Enforced by the replay middleware, not the handler. in: header name: X-Idempotency required: true schema: description: Idempotency key (at most 64 bytes); required on create. Enforced by the replay middleware, not the handler. examples: - a1b2c3d4-0000-0000-0000-000000000001 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateFundsRecoveryBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: 'Idempotent replay: a repeated X-Idempotency header returns the funds recovery created by the first request (cached response body).' '201': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: Created '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0113 title: Conflict status: 409 detail: A funds recovery already exists for this root transaction. code: PIX-0113 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0113, PIX-0114, PIX-0035). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0117). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "202": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryOutput" description: "The provider accepted the create but BACEN has not resolved it yet: the recovery is persisted as PENDING, with an empty bacenFundsRecoveryId, and resolves when it is next read or operated on." summary: Create a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}: get: description: Retrieves a funds recovery by its resource ID (UUID v7), within the scope of the participant determined by the authenticated tenant. Returns 404 when no active recovery with that ID belongs to the participant. A recovery owned by another participant produces the same response as an unknown ID. operationId: getFundsRecovery x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-funds-recovery parameters: - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a funds recovery tags: - Funds Recoveries patch: description: "Applies a JSON merge-patch (Content-Type: application/merge-patch+json) to the mutable fields (contact information and report details) of a funds recovery owned by the authenticated participant. Only the fields present in the body are changed; any other field (metadata, status, participantId, ...) is rejected with 422. Returns 404 when no active recovery with that ID belongs to the participant and 409 when the recovery's current status no longer allows information changes, or when the provider refuses the report-details correction for the recovery's state (PIX-0114). When the provider accepts the request but BACEN has not resolved it yet, the operation answers 409 / PIX-0118, carrying the operationId that identifies the operation at the provider and its operationStatus as field details (errors[].location operationId and operationStatus). Each is present only when the provider sent a valid value, so handle a pending answer without them too. Nothing changes here, and the correction is not reflected on its own when BACEN applies it. Sending the same request again records it only after the provider stops replaying this pending answer for it; until then the resend answers 409 / PIX-0118 again. If the provider is still processing an earlier request for the same operation, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait. The retry answers with the earlier request's outcome, or with the recovery's new state once it has changed." operationId: patchFundsRecovery x-mint: href: /pt/reference/interfaces/pix-lerian/dict/patch-funds-recovery parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string - description: Must be application/merge-patch+json. in: header name: Content-Type schema: description: Must be application/merge-patch+json. examples: - application/merge-patch+json type: string requestBody: content: application/merge-patch+json: schema: contentMediaType: application/octet-stream format: binary type: string required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0113 title: Conflict status: 409 detail: A funds recovery already exists for this root transaction. code: PIX-0113 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0113, PIX-0114, PIX-0118, PIX-0035). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0117). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Update a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}/cancel: post: description: "Cancels a funds recovery within the authenticated participant scope, changing its status to CANCELLED from any non-terminal state from CREATED through REFUNDING. A recovery already in COMPLETED or CANCELLED returns 409. The request has no body and requires the X-Idempotency header. The response omits trackingGraph, trackingGraphParameters, and correlationId. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The resource keeps its current status until BACEN's change arrives. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait." operationId: cancelFundsRecovery x-mint: href: /pt/reference/interfaces/pix-lerian/dict/cancel-funds-recovery parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). examples: - 7c9e6679742540de944be07fc1f90ae7 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CancelFundsRecoveryResponse' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0113 title: Conflict status: 409 detail: A funds recovery already exists for this root transaction. code: PIX-0113 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0113, PIX-0114, PIX-0118, PIX-0035). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0117). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Cancel a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}/infraction-reports: get: description: Returns the infraction reports associated with a funds recovery within the scope of the participant determined by the authenticated tenant. {id} is the funds recovery resource ID. An unknown ID or a recovery owned by another participant returns 404. The BCB does not paginate this list, so the response contains only items and total. operationId: listFundsRecoveryInfractionReports x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-funds-recovery-infraction-reports parameters: - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListInfractionReportsOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List infraction reports for a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}/refund: post: description: "Initiates a refund for a funds recovery in the ANALYSED state, within the scope of the participant determined by the authenticated tenant. The recovery changes to REFUNDING, and the updated recovery is returned with HTTP 200. Returns 404 when no active recovery with that ID belongs to the participant and 409 when its current state does not allow a refund, including when the provider refuses the refund for the recovery's state (PIX-0114). The response is a concise funds recovery representation. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The resource keeps its current status until BACEN's change arrives. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait." operationId: refundFundsRecovery x-mint: href: /pt/reference/interfaces/pix-lerian/dict/refund-funds-recovery parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). examples: - 7c9e6679742540de944be07fc1f90ae7 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundFundsRecoveryResponse' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0113 title: Conflict status: 409 detail: A funds recovery already exists for this root transaction. code: PIX-0113 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0113, PIX-0114, PIX-0118, PIX-0035). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0117). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Initiate a refund for a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}/refunds: get: description: Lists the refunds associated with a funds recovery within the scope of the participant determined by the authenticated tenant. {id} is the funds recovery resource ID. The recovery must belong to the requesting participant. operationId: listFundsRecoveryRefunds x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-funds-recovery-refunds parameters: - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListRefundsOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List refunds linked to a funds recovery tags: - Funds Recoveries /dict/funds-recoveries/{id}/tracking-graph: get: description: Returns the DICT tracking graph for a funds recovery identified by the resource ID returned at creation, within the authenticated participant scope. The response includes correlationId for support. trackingGraph is null when the graph is not yet available. operationId: getFundsRecoveryTrackingGraph x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-funds-recovery-tracking-graph parameters: - description: Funds recovery internal ID (UUID format) in: path name: id required: true schema: description: Funds recovery internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/TrackingGraphOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a funds recovery tracking graph tags: - Funds Recoveries /dict/infraction-reports: get: description: Returns a page of infraction reports for the authenticated organization, newest-updated first by default. Every filter is optional and validated only when present; any invalid value returns 400 PIX-0003. modified_after / modified_before are ISO 8601 UTC timestamps filtering updated_at; when both are present, modified_after must not be after modified_before. operationId: listInfractionReports x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-infraction-reports parameters: - description: Filter by lifecycle status explode: false in: query name: status schema: description: Filter by lifecycle status examples: - OPEN type: string - description: Filter by situation type explode: false in: query name: situation_type schema: description: Filter by situation type examples: - SCAM type: string - description: Filter by the linked funds-recovery BACEN identifier explode: false in: query name: bacen_funds_recovery_id schema: description: Filter by the linked funds-recovery BACEN identifier examples: - FR-2026-000000123 type: string - description: Filter by the contested transaction's end-to-end/RtrId (a transaction may have multiple infraction reports) explode: false in: query name: transaction_id schema: description: Filter by the contested transaction's end-to-end/RtrId (a transaction may have multiple infraction reports) examples: - E12345678202607161000aB3xK9mWq2z type: string - description: Return rows updated strictly after this ISO 8601 UTC timestamp explode: false in: query name: modified_after schema: description: Return rows updated strictly after this ISO 8601 UTC timestamp examples: - '2026-05-17T13:30:00Z' type: string - description: Return rows updated strictly before this ISO 8601 UTC timestamp explode: false in: query name: modified_before schema: description: Return rows updated strictly before this ISO 8601 UTC timestamp examples: - '2026-05-18T13:30:00Z' type: string - description: Filter to reports whose BACEN analysis window (7 days from receipt) has elapsed while not yet closed or cancelled explode: false in: query name: sla_breached schema: description: Filter to reports whose BACEN analysis window (7 days from receipt) has elapsed while not yet closed or cancelled examples: - 'true' type: string - description: Filter to reports within 2 days of the BACEN analysis deadline but not yet past it, while not yet closed or cancelled explode: false in: query name: sla_at_risk schema: description: Filter to reports within 2 days of the BACEN analysis deadline but not yet past it, while not yet closed or cancelled examples: - 'true' type: string - description: 'Page number (default: 1, minimum: 1)' explode: false in: query name: page schema: description: 'Page number (default: 1, minimum: 1)' examples: - '1' type: string - description: 'Maximum number of items per page (default: 20, maximum: 100)' explode: false in: query name: limit schema: description: 'Maximum number of items per page (default: 20, maximum: 100)' examples: - '20' type: string - description: 'Sort direction by updated_at (default: desc)' explode: false in: query name: sort_order schema: description: 'Sort direction by updated_at (default: desc)' examples: - desc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/InfractionReportPageOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List infraction reports tags: - Infraction Reports /dict/infraction-reports/{id}: get: description: Retrieves an infraction report by its resource ID (UUID v7), including its tracked balance blocks, within the authenticated organization scope. Returns 404 when no report with that ID belongs to the organization. A report owned by another organization produces the same response as an unknown ID. operationId: getInfractionReport x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-infraction-report parameters: - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/InfractionReportDetailOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get an infraction report tags: - Infraction Reports /dict/infraction-reports/{id}/acknowledge: post: description: "Acknowledges an OPEN infraction report as the receiving counterparty and changes its status to ACKNOWLEDGED. Acknowledging an already-ACKNOWLEDGED report with a new X-Idempotency header is idempotent and returns its current state with HTTP 200. Reports in CLOSED or CANCELLED return 409. Reusing the original X-Idempotency header returns the first attempt response, which may not reflect the current report state; use a different key to evaluate the current state. The report must belong to the authenticated organization, otherwise 404 is returned. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The report keeps its current status until BACEN's change arrives. The replay gate stores no pending answer, so a retry under the same X-Idempotency runs the operation again: read the report instead." operationId: acknowledgeInfractionReport x-mint: href: /pt/reference/interfaces/pix-lerian/dict/acknowledge-infraction-report parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/InfractionReportDetailOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070, PIX-0072). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Acknowledge an infraction report tags: - Infraction Reports /dict/infraction-reports/{id}/balance-blocks: get: description: 'Returns the balance blocks associated with an infraction report and the aggregate totals: infractionAmount from the parent report and totalBlocked, the effective amount retained across active blocks in PENDING, SETTLING, or SETTLED. The report must belong to the authenticated organization, otherwise 404 is returned.' operationId: listInfractionReportBalanceBlocks x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-infraction-report-balance-blocks parameters: - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListBalanceBlocksOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List balance blocks for an infraction report tags: - Infraction Reports /dict/infraction-reports/{id}/cancel: post: description: "Cancels an infraction report on behalf of its original reporter and changes its status to CANCELLED. Cancellation attempts to release all PENDING balance blocks; failure to release an individual block does not fail the cancellation. Reports in OPEN, ACKNOWLEDGED, or CLOSED can be cancelled. Cancelling an already-CANCELLED report is idempotent. Returns 403 when the participant is not the original reporter, 422 when the report is linked to a funds recovery that must be cancelled through its own operation, and 404 when the report does not belong to the authenticated organization. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The report keeps its current status until BACEN's change arrives. Its PENDING balance blocks stay held while the outcome is pending. The replay gate stores no pending answer, so a retry under the same X-Idempotency runs the operation again: read the report instead." operationId: cancelInfractionReport x-mint: href: /pt/reference/interfaces/pix-lerian/dict/cancel-infraction-report parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/InfractionReportDetailOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '403': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0005 title: Forbidden status: 403 detail: You do not have permission to perform this operation. code: PIX-0005 schema: $ref: '#/components/schemas/Detail' description: Forbidden (PIX-0005). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070, PIX-0072). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Cancel an infraction report tags: - Infraction Reports /dict/infraction-reports/{id}/close: post: description: "Closes an ACKNOWLEDGED infraction report with the reporter verdict (AGREED or DISAGREED) and changes its status to CLOSED. DISAGREED attempts to release all PENDING balance blocks; failure to release an individual block does not fail the close. AGREED leaves the blocks unchanged. fraudType is required when analysisResult is AGREED, and analysisDetails is required when fraudType is OTHER. Any pre-state other than ACKNOWLEDGED returns 409. Reusing the original X-Idempotency header returns the first attempt response instead of re-evaluating the current state. The report must belong to the authenticated organization, otherwise 404 is returned. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The report keeps its current status until BACEN's change arrives. Its PENDING balance blocks stay held while the outcome is pending. The replay gate stores no pending answer, so a retry under the same X-Idempotency runs the operation again: read the report instead. An AGREED close that arrives through the provider carries no fraudType, because BACEN's report does not publish it." operationId: closeInfractionReport x-mint: href: /pt/reference/interfaces/pix-lerian/dict/close-infraction-report parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CloseInfractionReportRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/InfractionReportDetailOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0071 title: Bad Gateway status: 502 detail: internal error code: PIX-0071 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0071, PIX-0070, PIX-0072). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Close an infraction report tags: - Infraction Reports /dict/refunds: get: description: Returns a paginated list of MED 2.0 Refunds (devoluções) owned by the requesting tenant's organization, newest first by default. Filtering is always scoped to the tenant organization resolved from the authenticated context. requesting_participant / contested_participant are optional accessory filters, not tenant boundaries. status, refund_reason, and sort_order are case-insensitive. operationId: listRefunds x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-refunds parameters: - description: Filter by lifecycle status (case-insensitive) explode: false in: query name: status schema: description: Filter by lifecycle status (case-insensitive) examples: - OPEN type: string - description: Filter by refund reason (case-insensitive) explode: false in: query name: refund_reason schema: description: Filter by refund reason (case-insensitive) examples: - FRAUD type: string - description: Filter by the contested transaction end-to-end ID (32 chars) explode: false in: query name: transaction_id schema: description: Filter by the contested transaction end-to-end ID (32 chars) examples: - E12345678202601011200abcdef01234 type: string - description: Filter by the linked infraction report UUID explode: false in: query name: infraction_report_id schema: description: Filter by the linked infraction report UUID examples: - c3d4e5f6-a7b8-4901-abcd-34567890abcd type: string - description: Filter by the requesting participant ISPB (8 characters, uppercase alphanumeric) explode: false in: query name: requesting_participant schema: description: Filter by the requesting participant ISPB (8 characters, uppercase alphanumeric) examples: - '12345678' maxLength: 8 minLength: 8 pattern: ^[A-Z0-9]{8}$ type: string - description: Filter by the contested participant ISPB (8 characters, uppercase alphanumeric) explode: false in: query name: contested_participant schema: description: Filter by the contested participant ISPB (8 characters, uppercase alphanumeric) examples: - '87654321' maxLength: 8 minLength: 8 pattern: ^[A-Z0-9]{8}$ type: string - description: 'Page number (default: 1, minimum: 1)' explode: false in: query name: page schema: description: 'Page number (default: 1, minimum: 1)' examples: - '1' type: string - description: 'Maximum number of items per page (default: 10, max: 100)' explode: false in: query name: limit schema: description: 'Maximum number of items per page (default: 10, max: 100)' examples: - '10' type: string - description: 'Sort direction by last_modified (default: desc, case-insensitive)' explode: false in: query name: sort_order schema: description: 'Sort direction by last_modified (default: desc, case-insensitive)' examples: - desc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListRefundsView' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List refunds tags: - Refunds post: description: 'Opens a MED 2.0 refund for a contested transaction. If an OPEN refund already exists for the same transaction, organization, and requesting participant, a sequential retry returns the existing refund with HTTP 200. The X-Idempotency header is required and deduplicates retries, including concurrent requests. The transaction amount is validated against the SPI; a successful creation returns HTTP 201 with status OPEN. The requesting participant is determined by the authenticated tenant. participant, requestingParticipant, contestedParticipant, and organizationId are rejected when included in the body. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. Nothing is created yet: if BACEN applies the request, the new refund appears later. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation.' operationId: createRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/create-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRefundBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/RefundView' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). '503': content: application/json: example: code: PIX-0032 title: Idempotency Unavailable message: The request was not processed because the idempotency store is unavailable. Please retry. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Create a refund tags: - Refunds /dict/refunds/{id}: get: description: Retrieves a MED 2.0 refund by its resource ID (UUID), within the authenticated tenant organization scope. The response includes the Phase 2 settlement fields, which are null until settlement. Returns 404 when no active refund with that ID belongs to the tenant. A refund owned by another tenant produces the same response as an unknown ID. operationId: getRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-refund parameters: - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundView' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a refund tags: - Refunds /dict/refunds/{id}/blocks/close: post: description: Closes the refund’s pending infraction blocks after the requesting participant completes the devolution outside the automatic flow. The operation requires the external payment End-to-End ID and verifies its amount before marking the blocks as settled. The refund remains OPEN until the infraction report is concluded. operationId: blocksCloseRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/blocks-close-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BlocksCloseRefundBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BlocksCloseRefundView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '403': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0005 title: Forbidden status: 403 detail: You do not have permission to perform this operation. code: PIX-0005 schema: $ref: '#/components/schemas/Detail' description: Forbidden (PIX-0005). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Close refund blocks after a manual devolution tags: - Refunds /dict/refunds/{id}/cancel: post: description: "Cancels a refund opened by the authenticated tenant, changing its status from OPEN to CANCELLED. Only the requesting participant that opened the refund may cancel it; a tenant acting as the contested participant receives 403. Refunds in CLOSED or CANCELLED return 409. Reusing the original X-Idempotency header returns the first attempt response; using a different key evaluates the current state and returns 409 for a terminal refund. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The resource keeps its current status until BACEN's change arrives. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation." operationId: cancelRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/cancel-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '403': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0005 title: Forbidden status: 403 detail: You do not have permission to perform this operation. code: PIX-0005 schema: $ref: '#/components/schemas/Detail' description: Forbidden (PIX-0005). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Cancel a refund tags: - Refunds /dict/refunds/{id}/close: post: description: 'Closes a refund with the contested participant analysis outcome. TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED requires every linked infraction block to be SETTLED. REJECTED requires refundRejectionReason and every linked block to be PENDING; the refund changes to CLOSED and release is attempted for each block. A release failure does not change the HTTP 200 outcome: the refund remains CLOSED and any unreleased block is returned with blocks[].status=PENDING, indicating that its hold remains outstanding. Retrying this endpoint cannot release that block: the original X-Idempotency header returns the first response, while a different key returns 409 because the refund is CLOSED. The affected block can be released with DELETE /v1/dict/infraction-reports/{id}/balance-blocks/{blockId}, using blocks[].lockId as {blockId}, not blocks[].spiBlockId. effectiveRefundedAmount and refundTransactionId must not be sent and return 400 when present. Only the contested participant tenant may close the refund. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The resource keeps its current status until BACEN''s change arrives. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation. A pending rejecting close keeps the refund''s concluding operations blocked (409 PIX-0012) and its balance blocks held.' operationId: closeRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/close-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CloseRefundBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CloseRefundView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '403': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0005 title: Forbidden status: 403 detail: You do not have permission to perform this operation. code: PIX-0005 schema: $ref: '#/components/schemas/Detail' description: Forbidden (PIX-0005). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033, PIX-0118). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Close a refund with the analysis outcome (Phase 3) tags: - Refunds /dict/refunds/{id}/settle: post: description: Initiates exactly one aggregated devolution for all PENDING blocks linked to the refund infraction report and changes those blocks together to SETTLING. Processing is selected automatically from the infraction operation type and contested transaction format. The refund remains OPEN during this phase. The request has no body. A successful SPI response reports SETTLING, or SETTLED for an idempotent replay; rejected or unexpected outcomes return an error. The refund is scoped to the authenticated tenant's organization. operationId: settleRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/settle-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string responses: '202': content: application/json: schema: $ref: '#/components/schemas/SettleRefundView' description: Accepted '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Settle a refund with an aggregated block devolution (Phase 1) tags: - Refunds /dict/refunds/{id}/settle/confirm: post: description: 'Reports or checks the network outcome of the aggregated devolution. When result=SUCCESS, the group blocks change to SETTLED and the response includes the aggregated settlement facts: effective refunded amount, aggregated end-to-end ID, already-settled and surplus amounts, and settlement type and reason. When result=FAILED, the blocks return to PENDING and those facts remain null, except that a group whose surplus was already returned is refused with 409 PIX-0656 and stays SETTLING. Omitting result checks the current group state without changing it. The refund remains OPEN until it is closed separately. result, when provided, must be SUCCESS or FAILED; endToEndId is required for SUCCESS. The refund is scoped to the authenticated tenant''s organization.' operationId: confirmSettleRefund x-mint: href: /pt/reference/interfaces/pix-lerian/dict/confirm-settle-refund parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string - description: Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: Best-effort business correlation id (observability only; never fabricated). type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfirmSettleRefundBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConfirmSettleRefundView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0011). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0012, PIX-0033). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0013). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Confirm the aggregated settlement (liquidation — Phase 2) tags: - Refunds /entries: get: description: Returns a page-based list of Pix entries owned by the account in X-Account-Id. Account-scoped to prevent cross-account PII exposure; key_type and sort_order are case-insensitive. operationId: listEntries x-mint: href: /pt/reference/interfaces/pix-lerian/dict/list-entries parameters: - description: Account UUID. Listing is always scoped to this account. in: header name: X-Account-Id required: true schema: description: Account UUID. Listing is always scoped to this account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Filter by key type (case-insensitive) explode: false in: query name: key_type schema: description: Filter by key type (case-insensitive) examples: - CPF type: string - description: Filter by key value explode: false in: query name: key_value schema: description: Filter by key value examples: - '52998224725' type: string - description: Page number (1-based, default 1) explode: false in: query name: page schema: description: Page number (1-based, default 1) examples: - '1' type: string - description: Rows per page (default 10, max 100) explode: false in: query name: limit schema: description: Rows per page (default 10, max 100) examples: - '10' type: string - description: Sort direction (default asc, case-insensitive) explode: false in: query name: sort_order schema: description: Sort direction (default asc, case-insensitive) examples: - desc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListEntriesOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0105 title: Not Found status: 404 detail: Key entry does not exist. code: PIX-0105 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0105). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List Pix key entries for an account tags: - Entries post: description: "Registers a new Pix key entry in the DICT directory. Assumes Receita Federal validation and MFA ownership authentication were completed by the client before the request. The account resolved from X-Account-Id must accept a new key binding: a salary account (SLRY) is refused with 422 PIX-0176 before any call to the DICT, while keys already bound to a salary account stay valid. After a 502 PIX-0141 or 500 PIX-0000 the outcome is unknown. Repeat the request with the same X-Idempotency and body, only within 30 minutes of the first attempt: the hub resends that attempt's directory request. On the repeat, 201 is the original registration (for an EVP key the returned key is the first attempt's only when the provider had completed that attempt, which the response does not show, so check the account's entries before creating another EVP key). PIX-0102 confirms nothing: the first attempt may still be in progress, or the key is stored but not yet bound to the account (VSync reconciliation); look the key up and, while no entry for the account appears, repeat later with the same X-Idempotency within the window. A classified directory refusal (PIX-0103, PIX-0177, PIX-0178, PIX-0149, PIX-0100 or PIX-0179, below) means the first attempt was refused: fix the cause and use a new X-Idempotency. A repeated 502 PIX-0141 or 500 PIX-0000 is not a refusal: repeat again with the same X-Idempotency within the window, or look the key up. Past the 30 minutes, or under a different X-Idempotency, a repeat is a new directory request, which for an EVP key registers a new key: while the outcome is unknown, check the account's entries instead of creating an EVP key again. An EVP create the hub cannot record for a later repeat is refused with 503 PIX-0032 before any call to the DICT, in a problem+json body (the replay gate's own PIX-0032 uses the legacy envelope): repeat it after a few seconds. The DICT itself can still answer PIX-0102 (the provider already holds or is processing the key; for a key other than EVP repeated after a 502 PIX-0141 or 500 PIX-0000 past the window or under a different X-Idempotency, this usually means that attempt registered it and the entry appears after VSync reconciliation, otherwise look the key up or retry), PIX-0103 (400: its own key limit), PIX-0177 (409: the key belongs to a different person; an OWNERSHIP claim is the usual next step), PIX-0178 (409: the key belongs to the same owner at a different participant; a PORTABILITY claim is the usual next step), PIX-0149 (422: an open claim locks the key), PIX-0100 (422: a CPF/CNPJ key that is not the owner's document) or PIX-0179 (422: a court-order or Pix restriction on the owner or account; do not show its message to end users). PIX-0141 (502) means the adapter call did not complete as a registration: an adapter or provider failure, which may have reached the DICT, or a provider refusal that has no classified code. None of these creates an entry." operationId: createEntry x-mint: href: /pt/reference/interfaces/pix-lerian/dict/create-entry parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: 'Reason for creating the entry: USER_REQUESTED or RECONCILIATION' in: header name: X-Reason required: true schema: description: 'Reason for creating the entry: USER_REQUESTED or RECONCILIATION' examples: - USER_REQUESTED type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEntryBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateEntryOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0103). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0102 title: Conflict status: 409 detail: Key value is already registered. code: PIX-0102 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0102, PIX-0177, PIX-0178). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0176, PIX-0179, PIX-0149, PIX-0116). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140, PIX-0141). '503': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0032 title: Idempotency Unavailable message: The request was not processed because the idempotency store is unavailable. Please retry. reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0119 title: Entry Mutations Temporarily Blocked message: Entry mutations for this key type are temporarily blocked while its scope is reconciled (VSync). Retry later. application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0032 title: Service Unavailable status: 503 detail: internal error code: PIX-0032 schema: $ref: "#/components/schemas/Detail" description: Service Unavailable (PIX-0032). An active VSync reconciliation holds this key type's scope, so the mutation was refused before it ran; retry after the reconciliation ends (PIX-0119). Legacy {code,title,message} envelope, NOT problem+json. Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Create a Pix key entry tags: - Entries /entries/{entry_id}: delete: description: Marks a Pix key entry as DELETED. The entry is no longer active after the operation. operationId: deleteEntry x-mint: href: /pt/reference/interfaces/pix-lerian/dict/delete-entry parameters: - description: Entry ID (UUID format) in: path name: entry_id required: true schema: description: Entry ID (UUID format) examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: 'Reason for deletion: USER_REQUESTED, ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, or RFB_VALIDATION' in: header name: X-Reason required: true schema: description: 'Reason for deletion: USER_REQUESTED, ACCOUNT_CLOSURE, RECONCILIATION, FRAUD, or RFB_VALIDATION' examples: - ACCOUNT_CLOSURE type: string responses: '204': description: No Content '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0108). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0105 title: Not Found status: 404 detail: Key entry does not exist. code: PIX-0105 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0105, PIX-0120). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0106 title: Unprocessable Entity status: 422 detail: Key entry is not in ACTIVE status. code: PIX-0106 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0106). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "503": content: application/json: examples: reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0119 title: Entry Mutations Temporarily Blocked message: Entry mutations for this key type are temporarily blocked while its scope is reconciled (VSync). Retry later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: An active VSync reconciliation holds this key type's scope, so the mutation was refused before it ran; retry after the reconciliation ends (PIX-0119). Legacy {code,title,message} envelope, NOT problem+json. summary: Delete a Pix key entry tags: - Entries get: description: Retrieves a Pix entry by its unique identifier, scoped to the calling account. operationId: getEntry x-mint: href: /pt/reference/interfaces/pix-lerian/dict/get-entry parameters: - description: Entry ID (UUID format) in: path name: entry_id required: true schema: description: Entry ID (UUID format) examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetEntryOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0105 title: Not Found status: 404 detail: Key entry does not exist. code: PIX-0105 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0105). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a Pix key entry tags: - Entries patch: description: "Updates an existing Pix entry (RFC 7386 JSON Merge Patch). Only account information, name, and trade name can be changed. A branch or account number change resolves the new account in the CRM before BACEN is called: no CRM account refuses the update with PIX-0116 (or PIX-0140 when the CRM is unavailable) and BACEN is not called. Moving the key onto a salary account (SLRY), by stating that account type or by a branch or account number change to an account the CRM records as SLRY, is refused with 422 PIX-0176 before BACEN is called; a key already on a salary account stays updatable. BACEN's refusals come back as PIX-0120 (the directory does not hold the key), PIX-0100 (it refused the change) and PIX-0106 (the key is not active)." operationId: updateEntry x-mint: href: /pt/reference/interfaces/pix-lerian/dict/update-entry parameters: - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Entry ID (UUID format) in: path name: entry_id required: true schema: description: Entry ID (UUID format) examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Reason for the update. For an EVP key it MUST be BRANCH_TRANSFER, RECONCILIATION or RFB_VALIDATION; for every other key type any non-empty value is accepted and recorded as the audit reason. in: header name: X-Reason required: true schema: description: Reason for the update. For an EVP key it MUST be BRANCH_TRANSFER, RECONCILIATION or RFB_VALIDATION; for every other key type any non-empty value is accepted and recorded as the audit reason. examples: - USER_REQUESTED type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateEntryBody' responses: '200': content: application/json: schema: $ref: '#/components/schemas/UpdateEntryOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0105 title: Not Found status: 404 detail: Key entry does not exist. code: PIX-0105 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0105, PIX-0120). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity (PIX-0100, PIX-0176, PIX-0106, PIX-0116). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141, PIX-0140). '503': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0032 title: Idempotency Unavailable message: The request was not processed because the idempotency store is unavailable. Please retry. reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0119 title: Entry Mutations Temporarily Blocked message: Entry mutations for this key type are temporarily blocked while its scope is reconciled (VSync). Retry later. description: An active VSync reconciliation holds this key type's scope, so the mutation was refused before it ran; retry after the reconciliation ends (PIX-0119). Legacy {code,title,message} envelope, NOT problem+json. Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Update a Pix key entry tags: - Entries /keys/check: post: description: Verifies whether the provided Pix keys exist in the DICT system. Supports batch verification of multiple keys in a single request. operationId: checkKeysExistence x-mint: href: /pt/reference/interfaces/pix-lerian/dict/check-keys-existence requestBody: content: application/json: schema: $ref: '#/components/schemas/CheckKeysExistenceBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CheckKeysExistenceOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0121, PIX-0122). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Check whether Pix keys exist tags: - Keys /keys/{key}: get: description: Queries the DICT system for Pix key details for payment preparation. The key type is inferred server-side from the value's shape. operationId: lookupKey x-mint: href: /pt/reference/interfaces/pix-lerian/dict/lookup-key parameters: - description: Pix key value (CPF, CNPJ, email, +E.164 phone, or EVP UUID) in: path name: key required: true schema: description: Pix key value (CPF, CNPJ, email, +E.164 phone, or EVP UUID) examples: - '52998224725' type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: End-to-end correlation ID (exactly 32 characters) in: header name: X-End-To-End-Id schema: description: End-to-end correlation ID (exactly 32 characters) examples: - E12345678202401011200abcdef12345 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/LookupKeyOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0120 title: Not Found status: 404 detail: Key does not exist in the DICT directory. code: PIX-0120 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0120). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Retrieve a Pix key tags: - Keys components: schemas: AcknowledgeClaimResponse: additionalProperties: false properties: claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string status: examples: - WAITING_RESOLUTION type: string required: - claimId - status type: object BalanceBlockOutput: additionalProperties: false properties: amount: examples: - '1000.00' type: string attemptNumber: examples: - 1 format: int64 type: integer createdAt: examples: - '2026-06-18T12:00:00Z' format: date-time type: string failureReason: examples: - balance-lock group settle exceeds the settle ceiling type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000002 type: string spiBlockId: examples: - 018f8c1d-5678-7abc-9def-000000000003 type: string status: enum: - PENDING - SETTLING - SETTLED - RELEASED - FAILED examples: - PENDING type: string updatedAt: examples: - '2026-06-18T12:05:00Z' format: date-time type: string required: - id - amount - status - attemptNumber - createdAt - updatedAt type: object BlocksCloseBlockView: additionalProperties: false properties: amount: examples: - '600.00' type: string failureReason: $ref: '#/components/schemas/SettleFailureView' lockId: examples: - b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f type: string settledAmount: examples: - '600.00' type: string spiBlockId: examples: - 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: string status: enum: - SETTLED examples: - SETTLED type: string required: - lockId - spiBlockId - amount - settledAmount - status type: object BlocksCloseRefundBody: additionalProperties: false properties: endToEndId: examples: - D12345678202601011210abcdef01234 type: string explanation: examples: - devolucao conciliada manualmente apos falha do settle type: string required: - endToEndId - explanation type: object BlocksCloseRefundView: additionalProperties: false properties: alreadySettled: examples: - '200.00' type: string blocks: items: $ref: '#/components/schemas/BlocksCloseBlockView' type: - array - 'null' blocksStatus: enum: - SETTLED examples: - SETTLED type: string endToEndId: examples: - D12345678202601011210abcdef01234 type: string originalAmount: examples: - '1000.00' type: string refundId: examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string settledAmount: examples: - '800.00' type: string surplusAmount: examples: - '200.00' type: string required: - refundId - blocksStatus - endToEndId - originalAmount - alreadySettled - settledAmount - surplusAmount - blocks type: object CancelClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object CancelFundsRecoveryResponse: additionalProperties: false properties: accountId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string bacenFundsRecoveryId: examples: - 9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f type: string contactInformation: $ref: '#/components/schemas/ContactInformationOutput' createdAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string metadata: {} participantId: examples: - '12345678' type: string reportDetails: examples: - Victim of a WhatsApp scam type: string reporterParticipant: examples: - '12345678' type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - CANCELLED type: string updatedAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string required: - id - bacenFundsRecoveryId - participantId - accountId - rootTransactionId - situationType - status - reporterParticipant - contactInformation - createdAt - updatedAt type: object CheckKeysExistenceBody: additionalProperties: false properties: keys: items: $ref: '#/components/schemas/KeyCheckItemRequest' type: - array - 'null' required: - keys type: object CheckKeysExistenceOutput: additionalProperties: false properties: keys: items: $ref: '#/components/schemas/KeyCheckResultOutput' type: - array - 'null' required: - keys type: object ClaimClaimerAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '1234567' type: string openingDate: examples: - '2024-03-10' type: string type: examples: - CACC type: string required: - branch - number - type - openingDate type: object ClaimClaimerOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/ClaimClaimerAccountOutput' document: examples: - '52998224725' type: string name: examples: - Maria da Silva type: string participant: examples: - '87654321' type: string personType: examples: - NATURAL_PERSON type: string tradeName: examples: - Silva ME type: string required: - participant type: object ClaimEventOutput: additionalProperties: false properties: actor: examples: - SYSTEM type: string createdAt: examples: - '2026-05-19T14:32:11Z' type: string id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string previousStatus: examples: - OPEN type: - string - 'null' source: examples: - ADAPTER_WEBHOOK type: string status: examples: - WAITING_RESOLUTION type: string required: - id - status - previousStatus - actor - source - createdAt type: object ClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object CloseBlockView: additionalProperties: false properties: lockId: examples: - b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f type: string spiBlockId: examples: - 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: string status: description: 'Post-close state of this block. SETTLED on accept. RELEASED when the reject unlock succeeded. PENDING when the release did not complete: the close is still durably CLOSED and the response is still 200, but this block''s hold is outstanding. Do NOT retry the close (it admits only OPEN refunds); release this block explicitly via DELETE /v1/dict/infraction-reports/{id}/balance-blocks/{blockId}, passing this entry''s lockId as {blockId} (not its spiBlockId).' enum: - SETTLED - RELEASED - PENDING examples: - SETTLED type: string required: - lockId - spiBlockId - status type: object CloseInfractionReportRequest: additionalProperties: false properties: analysisDetails: examples: - Mule account confirmed by anti-fraud analysis. type: string analysisResult: enum: - AGREED - DISAGREED examples: - AGREED type: string fraudType: enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER examples: - MULE_ACCOUNT type: string required: - analysisResult type: object CloseRefundBody: additionalProperties: false properties: analysisDetails: examples: - operational failure confirmed; full refund type: string analysisResult: enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string endToEndId: examples: - D12345678202601011200abcdef01234 type: string refundRejectionReason: enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER examples: - NO_BALANCE type: string required: - analysisResult type: object CloseRefundView: additionalProperties: false properties: alreadySettledAmount: type: string analysisDetails: type: string analysisResult: enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED type: string bacenRefundId: examples: - 3d48532f-1a2b-4422-81c3-b7dc852e262b type: string blocks: items: $ref: '#/components/schemas/CloseBlockView' type: - array - 'null' contestedParticipant: examples: - '87654321' type: string correlationId: examples: - 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f type: string creationTime: examples: - '2026-01-01T12:00:00Z' format: date-time type: string effectiveRefundedAmount: type: string fundsRecoveryId: type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string infractionReportId: type: string lastModified: examples: - '2026-01-01T12:30:00Z' format: date-time type: string monitorAccount: examples: - false type: boolean refundAccount: $ref: '#/components/schemas/RefundAccountView' refundAmount: examples: - '1000.00' type: string refundDetails: examples: - refund due to operational failure type: string refundReason: enum: - FRAUD - OPERATIONAL_FLAW - PIX_AUTOMATICO - REFUND_CANCELLED examples: - OPERATIONAL_FLAW type: string refundRejectionReason: enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER - PARTICIPANT_EXCLUSION type: string refundTransactionId: type: string requestingParticipant: examples: - '12345678' type: string settleReason: type: string settleType: enum: - REFUND - MANUAL type: string status: enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string surplusAmount: type: string transactionId: examples: - E12345678202601011200abcdef01234 type: string required: - blocks - id - transactionId - refundReason - refundAmount - status - requestingParticipant - contestedParticipant - monitorAccount - creationTime - lastModified type: object CompleteClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object ConfirmClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object ConfirmSettleFailureView: additionalProperties: false properties: message: examples: - falha no Midaz ao liberar o bloqueio type: string required: - message type: object ConfirmSettleRefundBody: additionalProperties: false properties: endToEndId: examples: - D12345678202601011200abcdef01234 type: string failureReason: type: string result: enum: - SUCCESS - FAILED examples: - SUCCESS type: string type: object ConfirmSettleRefundView: additionalProperties: false properties: alreadySettled: examples: - '50.00' type: string blocks: items: $ref: '#/components/schemas/SettleBlockView' type: - array - 'null' blocksStatus: enum: - SETTLING - PENDING - SETTLED examples: - SETTLING type: string endToEndId: type: string failureReason: $ref: '#/components/schemas/ConfirmSettleFailureView' operationType: enum: - ROOT - SUBSEQUENT - UNKNOWN examples: - ROOT type: string originalAmount: examples: - '200.00' type: string refundId: examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string settleAmount: examples: - '150.00' type: string settleReason: examples: - FR01 type: string settleType: enum: - REFUND - MANUAL examples: - REFUND type: string settled: examples: - false type: boolean status: enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string surplusAmount: examples: - '50.00' type: string required: - refundId - status - operationType - originalAmount - alreadySettled - blocksStatus type: object ContactInformationOutput: additionalProperties: false properties: email: examples: - user@example.com type: string phone: examples: - '+5511999999999' type: string required: - email - phone type: object CreateClaimBody: additionalProperties: false properties: key: description: The Pix key being claimed examples: - '+5511987654321' type: string type: description: 'Claim type: PORTABILITY or OWNERSHIP' examples: - OWNERSHIP type: string required: - key - type type: object CreateClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object CreateEntryBody: additionalProperties: false properties: keyType: description: Pix key type examples: - CPF type: string keyValue: description: Pix key value examples: - '52998224725' type: string metadata: additionalProperties: {} description: Free-form, single-level key/value pairs persisted with the entry. Keys up to 100 characters, values up to 2000 characters, at most 25 entries; nested objects are rejected. examples: - source: mobile maxProperties: 25 type: object required: - keyType type: object CreateEntryOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string description: CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account. id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - createdAt - updatedAt type: object CreateFraudMarkerBody: additionalProperties: false properties: fraudType: description: BACEN DICT fraud type (UNKNOWN is read-only, never creatable) enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER examples: - APPLICATION_FRAUD type: string key: description: Optional Pix key tied to the marker. Maximum 77 BYTES UTF-8, not characters -- the schema deliberately does not declare maxLength (OpenAPI's maxLength counts characters, which would under-bound a multi-byte key); the byte-length limit is enforced at runtime (the service implementation). examples: - '+5561999998888' type: string requestId: description: Caller-minted create idempotency key, forwarded verbatim to the provider examples: - 3f2f6a52-a5b7-4f1a-9b0f-64d3f4b6c111 format: uuid type: string taxIdNumber: description: CPF or CNPJ (numeric or alphanumeric per IN RFB 2.229/2024) being marked, checked against BACEN/RFB check digits. Mask, surrounding whitespace, and lowercase are accepted and normalized to the canonical unformatted uppercase form before use. examples: - '12345678901' type: string required: - taxIdNumber - fraudType - requestId type: object CreateFundsRecoveryBody: additionalProperties: false properties: accountId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string contactInformation: $ref: '#/components/schemas/CreateFundsRecoveryBodyContactInformationStruct' metadata: {} reportDetails: examples: - Victim of a WhatsApp scam type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string trackingGraphParameters: {} required: - accountId - rootTransactionId - situationType - contactInformation type: object CreateFundsRecoveryBodyContactInformationStruct: additionalProperties: false properties: email: examples: - user@example.com type: string phone: examples: - '+5511999999999' type: string required: - email - phone type: object CreateRefundBody: additionalProperties: false properties: refundAmount: examples: - '1000.00' type: string refundDetails: examples: - refund due to operational failure type: string refundReason: enum: - FRAUD - OPERATIONAL_FLAW - PIX_AUTOMATICO - REFUND_CANCELLED examples: - OPERATIONAL_FLAW type: string transactionId: examples: - E12345678202601011200abcdef01234 type: string required: - transactionId - refundReason - refundAmount type: object DICTFraudMarker: additionalProperties: false properties: creationTime: description: When the marker was registered at the provider (RFC 3339 UTC) examples: - '2026-08-21T10:00:00Z' format: date-time type: string fraudType: enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER - UNKNOWN examples: - APPLICATION_FRAUD type: string id: description: Directory fraud-marker id examples: - 0b843bcc-7c1a-4a12-9c88-8d3a5d70e6a1 format: uuid type: string infractionReport: $ref: '#/components/schemas/DICTFraudMarkerInfractionReport' description: The infraction report the provider created this marker from, when applicable key: description: Pix key linked to the marker, when one was supplied on create examples: - '+5561999998888' type: string lastModified: description: When the marker was last modified at the provider (RFC 3339 UTC) examples: - '2026-08-21T10:00:00Z' format: date-time type: string status: enum: - REGISTERED - CANCELLED examples: - REGISTERED type: string taxIdNumber: description: 'CPF (11 digits) or CNPJ (14 characters: 12 uppercase alphanumeric characters followed by 2 digits, unformatted, per IN RFB 2.229/2024) marked' examples: - '12345678901' type: string required: - id - status - taxIdNumber - fraudType - creationTime - lastModified type: object DICTFraudMarkerInfractionReport: additionalProperties: false properties: id: description: Infraction report id at the provider examples: - 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b type: string reporterParticipant: description: ISPB of the participant that opened the infraction report examples: - '18236120' type: string required: - id - reporterParticipant type: object Detail: additionalProperties: true properties: code: description: 'Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN).' 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.' type: object EntryAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string openingDate: examples: - '2010-01-10T03:00:00Z' format: date-time type: string participant: examples: - '12345678' type: string type: examples: - CACC type: string required: - branch - number - type - participant type: object EntryBaseOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string description: CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account. id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - createdAt - updatedAt type: object EntryOwnerOutput: additionalProperties: false properties: document: examples: - '52998224725' type: string name: examples: - João Silva type: string personType: examples: - NATURAL type: string tradeName: examples: - Silva ME type: string required: - document - personType - name 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 FundsRecoveryOutput: additionalProperties: false properties: accountId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string bacenFundsRecoveryId: examples: - 9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f type: string description: Recovery id the provider assigned. Empty while status is PENDING. contactInformation: $ref: '#/components/schemas/ContactInformationOutput' correlationId: examples: - 7c9e6679742540de944be07fc1f90ae7 type: string createdAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string metadata: {} participantId: examples: - '12345678' type: string reportDetails: examples: - Victim of a WhatsApp scam type: string reporterParticipant: examples: - '12345678' type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - PENDING - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - CREATED type: string trackingGraph: {} trackingGraphParameters: {} updatedAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string required: - id - bacenFundsRecoveryId - participantId - accountId - rootTransactionId - situationType - status - reporterParticipant - contactInformation - createdAt - updatedAt type: object GetClaimOutput: additionalProperties: false properties: accountId: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string bacenId: examples: - claim-bacen-001 type: string cancelReason: type: string cancelledBy: type: string claimId: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string claimer: $ref: '#/components/schemas/ClaimClaimerOutput' completionPeriodEnd: examples: - '2026-06-18T03:00:00Z' type: string confirmReason: type: string correlationId: examples: - a9f13566e19f5ca51329479a5bae60c5 type: string createdAt: examples: - '2026-05-19T14:30:00Z' type: string donorParticipant: examples: - '12345678' type: string events: items: $ref: '#/components/schemas/ClaimEventOutput' type: - array - 'null' keyType: examples: - PHONE type: string keyValue: examples: - '+5511987659999' type: string lastModified: examples: - '2026-05-19T14:32:11Z' type: string requestId: examples: - e7c1a2b3-4d5e-6f70-8a90-1b2c3d4e5f60 type: string resolutionPeriodEnd: examples: - '2026-05-25T03:00:00Z' type: string status: examples: - WAITING_RESOLUTION type: string type: examples: - PORTABILITY type: string updatedAt: examples: - '2026-05-19T14:32:11Z' type: string required: - events - claimId - accountId - bacenId - status - type - keyType - keyValue - donorParticipant - claimer - lastModified - createdAt - updatedAt type: object GetEntryOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string description: CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account. id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - createdAt - updatedAt type: object InfractionReportDetailOutput: additionalProperties: false properties: analysisDetails: examples: - Mule account confirmed by anti-fraud analysis. type: string analysisResult: enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: examples: - 018f8c1d-1111-7abc-9def-000000000001 type: string bacenInfractionReportId: examples: - 018f8c1d-aaaa-7abc-9def-000000000010 type: string balanceBlocks: items: $ref: '#/components/schemas/BalanceBlockOutput' type: - array - 'null' contactInformation: $ref: '#/components/schemas/ContactInformationOutput' correlationId: examples: - 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f type: string counterpartyParticipant: examples: - '87654321' type: string createdAt: examples: - '2026-06-18T12:00:00Z' format: date-time type: string fraudMarkerId: examples: - 018f8c1d-bbbb-7abc-9def-000000000020 type: string fraudType: enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER examples: - MULE_ACCOUNT type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string infractionAmount: examples: - '1500.00' type: string monitorAccount: examples: - false type: boolean reportDetails: examples: - conta usada repetidamente em golpes type: string reporterParticipant: examples: - '12345678' type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - OPEN type: string transactionDepth: examples: - 1 format: int64 maximum: 2147483647 minimum: 1 type: integer transactionId: examples: - E12345678202601011200abcdef01234 type: string updatedAt: examples: - '2026-06-18T12:05:00Z' format: date-time type: string required: - id - bacenInfractionReportId - transactionId - situationType - contactInformation - status - balanceBlocks - monitorAccount - createdAt - updatedAt type: object InfractionReportListItemOutput: additionalProperties: false properties: analysisDeadline: examples: - '2026-06-25T12:00:00Z' format: date-time type: string bacenFundsRecoveryId: examples: - 018f8c1d-1111-7abc-9def-000000000001 type: string bacenInfractionReportId: examples: - 018f8c1d-aaaa-7abc-9def-000000000010 type: string createdAt: examples: - '2026-06-18T12:00:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string infractionAmount: examples: - '1500.00' type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string slaAtRisk: examples: - false type: boolean slaBreached: examples: - false type: boolean status: enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - OPEN type: string transactionDepth: examples: - 1 format: int64 maximum: 2147483647 minimum: 1 type: integer updatedAt: examples: - '2026-06-18T12:05:00Z' format: date-time type: string required: - id - bacenInfractionReportId - status - situationType - createdAt - updatedAt - analysisDeadline - slaBreached - slaAtRisk type: object InfractionReportOutput: additionalProperties: false properties: analysisDetails: examples: - Mule account confirmed by anti-fraud analysis. type: string analysisResult: enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: examples: - 018f8c1d-1111-7abc-9def-000000000001 type: string bacenInfractionReportId: examples: - 018f8c1d-aaaa-7abc-9def-000000000010 type: string contactInformation: $ref: '#/components/schemas/ContactInformationOutput' counterpartyParticipant: examples: - '87654321' type: string creationTime: examples: - '2026-06-18T12:00:00Z' type: string fraudMarkerId: examples: - 018f8c1d-bbbb-7abc-9def-000000000020 type: string infractionAmount: examples: - '1500.00' type: string lastModified: examples: - '2026-06-18T12:05:00Z' type: string reason: enum: - REFUND_REQUEST - REFUND_CANCELLED examples: - REFUND_REQUEST type: string reportDetails: examples: - Customer reported a scam. type: string reporterParticipant: examples: - '12345678' type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - OPEN type: string transactionId: examples: - E1234567820260618000000000000001 type: string required: - bacenInfractionReportId - transactionId - reason - status - reporterParticipant - counterpartyParticipant - contactInformation - creationTime - lastModified type: object InfractionReportPageOutput: additionalProperties: false properties: hasMore: examples: - false type: boolean items: items: $ref: '#/components/schemas/InfractionReportListItemOutput' type: - array - 'null' limit: examples: - 20 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 1 format: int64 type: integer required: - items - total - page - limit - hasMore type: object KeyCheckItemRequest: additionalProperties: false properties: key: description: Pix key value examples: - '52998224725' type: string required: - key type: object KeyCheckResultOutput: additionalProperties: false properties: hasEntry: examples: - true type: boolean key: examples: - '52998224725' type: string required: - key - hasEntry type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message type: object ListBalanceBlocksOutput: additionalProperties: false properties: infractionAmount: examples: - '1500.00' type: string items: items: $ref: '#/components/schemas/BalanceBlockOutput' type: - array - 'null' total: examples: - 1 format: int64 type: integer totalBlocked: examples: - '1000.00' type: string required: - items - total - totalBlocked type: object ListClaimsOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/ClaimOutput' type: - array - 'null' limit: examples: - 20 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 1 format: int64 type: integer required: - items - total - page - limit type: object ListDICTFraudMarkersOutput: additionalProperties: false properties: fraudMarkers: description: Matching fraud markers, empty when none match examples: - [] items: $ref: '#/components/schemas/DICTFraudMarker' type: array hasMoreElements: description: Whether more results exist beyond this page examples: - false type: boolean total: description: "Number of fraud markers in this page. It is not a count of every match: BACEN returns none, and hasMoreElements says whether more markers match." examples: - 1 format: int64 type: integer required: - fraudMarkers - total - hasMoreElements type: object ListEntriesOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/EntryBaseOutput' type: - array - 'null' limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 1 format: int64 type: integer required: - items - total - page - limit type: object ListFundsRecoveriesOutput: additionalProperties: false properties: hasMore: examples: - false type: boolean items: items: $ref: '#/components/schemas/FundsRecoveryOutput' type: - array - 'null' limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 1 format: int64 type: integer required: - items - total - page - limit - hasMore type: object ListInfractionReportsOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/InfractionReportOutput' type: - array - 'null' total: examples: - 1 format: int64 type: integer required: - items - total type: object ListRefundsOutput: additionalProperties: false properties: hasMore: examples: - false type: boolean items: items: $ref: '#/components/schemas/RefundOutput' type: - array - 'null' limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 0 format: int64 type: integer required: - items - total - page - limit - hasMore type: object ListRefundsView: additionalProperties: false properties: hasMore: examples: - false type: boolean items: items: $ref: '#/components/schemas/RefundView' type: - array - 'null' limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 1 format: int64 type: integer required: - items - total - page - limit - hasMore type: object LookupKeyAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string openingDate: examples: - '2010-01-10T03:00:00Z' format: date-time type: string participant: examples: - '12345678' type: string type: examples: - CACC type: string required: - participant - branch - number - type type: object LookupKeyOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/LookupKeyAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string endToEndId: examples: - E12345678202401011200abcdef12345 type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string person: $ref: '#/components/schemas/LookupKeyPersonOutput' required: - keyType - keyValue - account - person - createdAt type: object LookupKeyPersonOutput: additionalProperties: false properties: document: examples: - '52998224725' type: string name: examples: - João Silva type: string personType: examples: - NATURAL type: string tradeName: examples: - Silva ME type: string required: - document - name - personType type: object RefundAccountOutput: additionalProperties: false properties: accountNumber: examples: - '1234567' type: string accountType: enum: - CACC - TRAN - SLRY - SVGS - OTHR examples: - CACC type: string branch: examples: - '0001' type: string participant: examples: - '12345678' type: string taxIdNumber: examples: - '12345678900' type: string required: - taxIdNumber - participant - branch - accountNumber - accountType type: object RefundAccountView: additionalProperties: false properties: accountNumber: examples: - '123456' type: string accountType: examples: - CACC type: string branch: examples: - '0001' type: string participant: examples: - '99999011' type: string taxIdNumber: examples: - '12345678909' type: string required: - taxIdNumber - participant - branch - accountNumber - accountType type: object RefundFundsRecoveryResponse: additionalProperties: false properties: bacenFundsRecoveryId: examples: - 9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f type: string contactInformation: $ref: '#/components/schemas/ContactInformationOutput' correlationId: examples: - 7c9e6679742540de944be07fc1f90ae7 type: string createdAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string reportDetails: examples: - Victim of a WhatsApp scam type: string reporterParticipant: examples: - '12345678' type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - REFUNDING type: string required: - id - bacenFundsRecoveryId - rootTransactionId - situationType - contactInformation - status - reporterParticipant - createdAt type: object RefundOutput: additionalProperties: false properties: analysisDetails: examples: - Refund accepted after fraud confirmation. type: string analysisResult: enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string bacenFundsRecoveryId: examples: - 9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f type: string bacenRefundId: examples: - a1b2c3d4-e5f6-4789-8abc-1234567890ab type: string contestedParticipant: examples: - '12345678' type: string creationTime: examples: - '2026-06-15T12:00:00Z' type: string effectiveRefundedAmount: examples: - '1500.00' type: string infractionReportId: examples: - c3d4e5f6-a7b8-4901-abcd-34567890abcd type: string lastModified: examples: - '2026-06-16T09:30:00Z' type: string monitorAccount: examples: - false type: boolean refundAccount: $ref: '#/components/schemas/RefundAccountOutput' refundAmount: examples: - '1500.00' type: string refundDetails: examples: - Funds returned to the contested account. type: string refundReason: enum: - FRAUD - OPERATIONAL_FLAW - REFUND_CANCELLED - PIX_AUTOMATICO examples: - FRAUD type: string refundRejectionReason: enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER - PARTICIPANT_EXCLUSION examples: - NO_BALANCE type: string refundTransactionId: examples: - D1234567820260102120012345678901 type: string requestingParticipant: examples: - '87654321' type: string status: enum: - OPEN - CLOSED - CANCELLED examples: - CLOSED type: string transactionId: examples: - E1234567820260101120012345678901 type: string required: - bacenRefundId - bacenFundsRecoveryId - refundReason - refundAmount - status - transactionId - contestedParticipant - requestingParticipant - monitorAccount - creationTime - lastModified type: object RefundView: additionalProperties: false properties: alreadySettledAmount: type: string analysisDetails: type: string analysisResult: enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED type: string bacenRefundId: examples: - 3d48532f-1a2b-4422-81c3-b7dc852e262b type: string contestedParticipant: examples: - '87654321' type: string correlationId: examples: - 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f type: string creationTime: examples: - '2026-01-01T12:00:00Z' format: date-time type: string effectiveRefundedAmount: type: string fundsRecoveryId: type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string infractionReportId: type: string lastModified: examples: - '2026-01-01T12:30:00Z' format: date-time type: string monitorAccount: examples: - false type: boolean refundAccount: $ref: '#/components/schemas/RefundAccountView' refundAmount: examples: - '1000.00' type: string refundDetails: examples: - refund due to operational failure type: string refundReason: enum: - FRAUD - OPERATIONAL_FLAW - PIX_AUTOMATICO - REFUND_CANCELLED examples: - OPERATIONAL_FLAW type: string refundRejectionReason: enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER - PARTICIPANT_EXCLUSION type: string refundTransactionId: type: string requestingParticipant: examples: - '12345678' type: string settleReason: type: string settleType: enum: - REFUND - MANUAL type: string status: enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string surplusAmount: type: string transactionId: examples: - E12345678202601011200abcdef01234 type: string required: - id - transactionId - refundReason - refundAmount - status - requestingParticipant - contestedParticipant - monitorAccount - creationTime - lastModified type: object SettleBlockView: additionalProperties: false properties: amount: examples: - '120.00' type: string lockId: examples: - b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f type: string spiBlockId: examples: - 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: string required: - lockId - spiBlockId - amount type: object SettleFailureView: additionalProperties: false properties: code: examples: - PIX-0652 type: string lockId: examples: - c1a6d3b2-0f4e-5d8b-9032-2b3c4d5e6f70 type: string message: examples: - falha no Midaz ao liberar o bloqueio type: string required: - lockId - code - message type: object SettleRefundView: additionalProperties: false properties: alreadySettled: examples: - '50.00' type: string blocks: items: $ref: '#/components/schemas/SettleBlockView' type: - array - 'null' blocksStatus: enum: - SETTLING - PENDING - SETTLED examples: - SETTLING type: string endToEndId: type: string operationType: enum: - ROOT - SUBSEQUENT - UNKNOWN examples: - ROOT type: string originalAmount: examples: - '200.00' type: string refundId: examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string settleAmount: examples: - '150.00' type: string settleReason: examples: - FR01 type: string settleType: enum: - REFUND - MANUAL examples: - REFUND type: string settled: examples: - false type: boolean status: enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string surplusAmount: examples: - '50.00' type: string required: - refundId - status - operationType - originalAmount - alreadySettled - blocksStatus type: object TrackingGraphOutput: additionalProperties: false properties: correlationId: type: string trackingGraph: {} required: - trackingGraph type: object UpdateEntryAccountRequest: additionalProperties: false properties: branch: description: Account branch examples: - '0001' type: string number: description: Account number examples: - '0007654321' type: string openingDate: description: Account opening date (YYYY-MM-DD) examples: - '2010-01-10' type: string participant: description: Participant ISPB examples: - '12345678' type: string type: description: "Account type: CACC, SVGS, TRAN, SLRY or OTHR. Moving a key onto a salary account (SLRY), stated here or as the CRM type of a new branch and number, is refused with 422 PIX-0176 unless the key is already on one." examples: - CACC type: string type: object UpdateEntryBody: additionalProperties: false properties: account: $ref: '#/components/schemas/UpdateEntryAccountRequest' metadata: additionalProperties: {} description: Free-form, single-level key/value pairs persisted with the entry. Keys up to 100 characters, values up to 2000 characters, at most 25 entries; nested objects are rejected. examples: - source: mobile maxProperties: 25 type: object owner: $ref: '#/components/schemas/UpdateEntryOwnerRequest' type: object UpdateEntryOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string description: CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account. id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - createdAt - updatedAt type: object UpdateEntryOwnerRequest: additionalProperties: false properties: name: description: Owner name examples: - João Silva type: string tradeName: description: Owner trade name examples: - Silva ME type: string 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