> ## 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 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 Idempotency-Key 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. ## OpenAPI ````yaml en/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: Elastic License 2.0 url: https://www.elastic.co/licensing/elastic-license title: Pix Lerian — DICT version: release-candidate 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: Register, retrieve, list, update, and remove Pix keys. name: Entries - description: Look up Pix keys and check whether keys exist in the DICT directory. name: Keys - description: Manage ownership and portability claims for Pix keys. name: Claims - 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: Create, query, cancel, and settle MED 2.0 refunds. name: Refunds - description: Create, query, list, and cancel DICT fraud markers. name: Fraud Markers 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 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 Idempotency-Key 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. operationId: closeRefund parameters: - description: Client-generated key used to retry exactly the same request safely. in: header name: Idempotency-Key required: true schema: maxLength: 64 minLength: 1 type: string description: >- Client-generated key used to retry exactly the same request safely. example: pix-demo-20260903-000001 - 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 example: 01960718-a213-2435-6078-901234567123 - 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 example: 019606a1-3b4c-7d8e-9f01-234567890abc requestBody: content: application/json: schema: $ref: '#/components/schemas/CloseRefundBody' examples: fictitiousExample: summary: Fictitious example value: analysisDetails: operational failure confirmed; full refund analysisResult: TOTALLY_ACCEPTED endToEndId: D12345678202601011200abcdef01234 refundRejectionReason: NO_BALANCE required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CloseRefundView' examples: fictitiousExample: summary: Fictitious example value: alreadySettledAmount: '100.50' analysisDetails: analysisdetails-example analysisResult: TOTALLY_ACCEPTED bacenRefundId: 3d48532f-1a2b-4422-81c3-b7dc852e262b blocks: - lockId: b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f spiBlockId: 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: SETTLED contestedParticipant: '87654321' correlationId: 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f creationTime: '2026-01-01T12:00:00Z' effectiveRefundedAmount: '100.50' fundsRecoveryId: 019606a1-3b4c-7d8e-9f01-234567890abc id: 018f8c1d-1234-7abc-9def-000000000001 infractionReportId: 019606a1-3b4c-7d8e-9f01-234567890abc lastModified: '2026-01-01T12:30:00Z' monitorAccount: false refundAccount: accountNumber: '123456' accountType: CACC branch: '0001' participant: '99999011' taxIdNumber: '12345678909' refundAmount: '1000.00' refundDetails: refund due to operational failure refundReason: OPERATIONAL_FLAW refundRejectionReason: NO_BALANCE refundTransactionId: 019606a1-3b4c-7d8e-9f01-234567890abc requestingParticipant: '12345678' settleReason: settlereason-example settleType: REFUND status: OPEN surplusAmount: '100.50' transactionId: E12345678202601011200abcdef01234 description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The Idempotency-Key header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Idempotency-Key absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The Idempotency-Key was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Idempotency-Key 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. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error x-codeSamples: - lang: bash label: cURL with fictitious data source: |- curl --request POST \ --url https://api.example.com/dict-hub/v1/dict/refunds/01960718-a213-2435-6078-901234567123/close \ --header 'Authorization: Bearer demo-access-token' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: pix-demo-20260903-000001' \ --header 'X-Correlation-Id: 019606a1-3b4c-7d8e-9f01-234567890abc' \ --data '{ "analysisDetails": "operational failure confirmed; full refund", "analysisResult": "TOTALLY_ACCEPTED", "endToEndId": "D12345678202601011200abcdef01234", "refundRejectionReason": "NO_BALANCE" }' 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 required: - code - title - message type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 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 ````