Close a refund with the analysis outcome (Phase 3)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "analysisResult": "TOTALLY_ACCEPTED",
  "analysisDetails": "operational failure confirmed; full refund",
  "endToEndId": "D12345678202601011200abcdef01234",
  "refundRejectionReason": "NO_BALANCE"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds/{id}/close"

	payload := strings.NewReader("{\n  \"analysisResult\": \"TOTALLY_ACCEPTED\",\n  \"analysisDetails\": \"operational failure confirmed; full refund\",\n  \"endToEndId\": \"D12345678202601011200abcdef01234\",\n  \"refundRejectionReason\": \"NO_BALANCE\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    analysisResult: 'TOTALLY_ACCEPTED',
    analysisDetails: 'operational failure confirmed; full refund',
    endToEndId: 'D12345678202601011200abcdef01234',
    refundRejectionReason: 'NO_BALANCE'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/close', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/refunds/{id}/close"

payload = {
    "analysisResult": "TOTALLY_ACCEPTED",
    "analysisDetails": "operational failure confirmed; full refund",
    "endToEndId": "D12345678202601011200abcdef01234",
    "refundRejectionReason": "NO_BALANCE"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "blocks": [
    {
      "lockId": "b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f",
      "spiBlockId": "7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "status": "SETTLED"
    }
  ],
  "contestedParticipant": "87654321",
  "creationTime": "2026-01-01T12:00:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "lastModified": "2026-01-01T12:30:00Z",
  "monitorAccount": false,
  "refundAmount": "1000.00",
  "refundReason": "OPERATIONAL_FLAW",
  "requestingParticipant": "12345678",
  "status": "OPEN",
  "transactionId": "E12345678202601011200abcdef01234",
  "alreadySettledAmount": "<string>",
  "analysisDetails": "<string>",
  "analysisResult": "TOTALLY_ACCEPTED",
  "bacenRefundId": "3d48532f-1a2b-4422-81c3-b7dc852e262b",
  "correlationId": "9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f",
  "effectiveRefundedAmount": "<string>",
  "fundsRecoveryId": "<string>",
  "infractionReportId": "<string>",
  "refundAccount": {
    "accountNumber": "123456",
    "accountType": "CACC",
    "branch": "0001",
    "participant": "99999011",
    "taxIdNumber": "12345678909"
  },
  "refundDetails": "refund due to operational failure",
  "refundRejectionReason": "NO_BALANCE",
  "refundTransactionId": "<string>",
  "settleReason": "<string>",
  "settleType": "REFUND",
  "surplusAmount": "<string>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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//balance-blocks/, using blocks[].lockId as , 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.

POST

dict

refunds

{id}

Close a refund with the analysis outcome (Phase 3)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "analysisResult": "TOTALLY_ACCEPTED",
  "analysisDetails": "operational failure confirmed; full refund",
  "endToEndId": "D12345678202601011200abcdef01234",
  "refundRejectionReason": "NO_BALANCE"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds/{id}/close"

	payload := strings.NewReader("{\n  \"analysisResult\": \"TOTALLY_ACCEPTED\",\n  \"analysisDetails\": \"operational failure confirmed; full refund\",\n  \"endToEndId\": \"D12345678202601011200abcdef01234\",\n  \"refundRejectionReason\": \"NO_BALANCE\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    analysisResult: 'TOTALLY_ACCEPTED',
    analysisDetails: 'operational failure confirmed; full refund',
    endToEndId: 'D12345678202601011200abcdef01234',
    refundRejectionReason: 'NO_BALANCE'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/close', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/refunds/{id}/close"

payload = {
    "analysisResult": "TOTALLY_ACCEPTED",
    "analysisDetails": "operational failure confirmed; full refund",
    "endToEndId": "D12345678202601011200abcdef01234",
    "refundRejectionReason": "NO_BALANCE"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "blocks": [
    {
      "lockId": "b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f",
      "spiBlockId": "7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "status": "SETTLED"
    }
  ],
  "contestedParticipant": "87654321",
  "creationTime": "2026-01-01T12:00:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "lastModified": "2026-01-01T12:30:00Z",
  "monitorAccount": false,
  "refundAmount": "1000.00",
  "refundReason": "OPERATIONAL_FLAW",
  "requestingParticipant": "12345678",
  "status": "OPEN",
  "transactionId": "E12345678202601011200abcdef01234",
  "alreadySettledAmount": "<string>",
  "analysisDetails": "<string>",
  "analysisResult": "TOTALLY_ACCEPTED",
  "bacenRefundId": "3d48532f-1a2b-4422-81c3-b7dc852e262b",
  "correlationId": "9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f",
  "effectiveRefundedAmount": "<string>",
  "fundsRecoveryId": "<string>",
  "infractionReportId": "<string>",
  "refundAccount": {
    "accountNumber": "123456",
    "accountType": "CACC",
    "branch": "0001",
    "participant": "99999011",
    "taxIdNumber": "12345678909"
  },
  "refundDetails": "refund due to operational failure",
  "refundRejectionReason": "NO_BALANCE",
  "refundTransactionId": "<string>",
  "settleReason": "<string>",
  "settleType": "REFUND",
  "surplusAmount": "<string>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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.

Required string length: 1 - 64

X-Correlation-Id

string

Best-effort business correlation id (observability only; never fabricated).

Parâmetros de caminho

string

obrigatório

Refund internal ID (UUID format)

Exemplo:

"018f8c1d-1234-7abc-9def-000000000010"

Corpo

application/json

analysisResult

enum<string>

obrigatório

Opções disponíveis:

TOTALLY_ACCEPTED,

PARTIALLY_ACCEPTED,

REJECTED

Exemplo:

"TOTALLY_ACCEPTED"

analysisDetails

string

Exemplo:

"operational failure confirmed; full refund"

endToEndId

string

Exemplo:

"D12345678202601011200abcdef01234"

refundRejectionReason

enum<string>

Opções disponíveis:

NO_BALANCE,

ACCOUNT_CLOSURE,

INVALID_REQUEST,

OTHER

Exemplo:

"NO_BALANCE"

Resposta

blocks

object[] | null

obrigatório

Show child attributes

contestedParticipant

string

obrigatório

Exemplo:

"87654321"

creationTime

string<date-time>

obrigatório

Exemplo:

"2026-01-01T12:00:00Z"

string

obrigatório

Exemplo:

"018f8c1d-1234-7abc-9def-000000000001"

lastModified

string<date-time>

obrigatório

Exemplo:

"2026-01-01T12:30:00Z"

monitorAccount

boolean

obrigatório

Exemplo:

false

refundAmount

string

obrigatório

Exemplo:

"1000.00"

refundReason

enum<string>

obrigatório

Opções disponíveis:

FRAUD,

OPERATIONAL_FLAW,

PIX_AUTOMATICO,

REFUND_CANCELLED

Exemplo:

"OPERATIONAL_FLAW"

requestingParticipant

string

obrigatório

Exemplo:

"12345678"

status

enum<string>

obrigatório

Opções disponíveis:

OPEN,

CLOSED,

CANCELLED

Exemplo:

"OPEN"

transactionId

string

obrigatório

Exemplo:

"E12345678202601011200abcdef01234"

alreadySettledAmount

string

analysisDetails

string

analysisResult

enum<string>

Opções disponíveis:

TOTALLY_ACCEPTED,

PARTIALLY_ACCEPTED,

REJECTED

bacenRefundId

string

Exemplo:

"3d48532f-1a2b-4422-81c3-b7dc852e262b"

correlationId

string

Exemplo:

"9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f"

effectiveRefundedAmount

string

fundsRecoveryId

string

infractionReportId

string

refundAccount

object

Show child attributes

refundDetails

string

Exemplo:

"refund due to operational failure"

refundRejectionReason

enum<string>

Opções disponíveis:

NO_BALANCE,

ACCOUNT_CLOSURE,

INVALID_REQUEST,

OTHER,

PARTICIPANT_EXCLUSION

refundTransactionId

string

settleReason

string

settleType

enum<string>

Opções disponíveis:

REFUND,

MANUAL

surplusAmount

string

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Close a refund with the analysis outcome (Phase 3)

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta