> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Close a refund with the analysis outcome (Phase 3) > Closes a refund with the contested participant analysis outcome. TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED requires at least one linked infraction block other than RELEASED or FAILED, and every such block to be SETTLED. REJECTED requires refundRejectionReason and every such block to be PENDING, and is also accepted when there is no such block; 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. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/close 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.2.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 - description: >- Read the state of key reconciliation against BACEN, and start a verification or a file reconciliation. name: VSync paths: /dict/refunds/{id}/close: post: tags: - Refunds summary: Close a refund with the analysis outcome (Phase 3) description: >- Closes a refund with the contested participant analysis outcome. TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED requires at least one linked infraction block other than RELEASED or FAILED, and every such block to be SETTLED. REJECTED requires refundRejectionReason and every such block to be PENDING, and is also accepted when there is no such block; 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 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. Resending the same key and request within 1 hour returns the original response, its status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, path or body, or while the first request runs, 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. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. '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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, 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 components: schemas: 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 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 fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message 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 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 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 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 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.