Close DICT refund

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "analysisResult": "TOTALLY_ACCEPTED",
  "analysisDetails": "<string>",
  "effectiveRefundedAmount": 123,
  "refundTransactionId": "D1234567820260220123456789012345",
  "rejectionReason": "NO_BALANCE"
}
'

package main

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

func main() {

	url := "https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close"

	payload := strings.NewReader("{\n  \"analysisResult\": \"TOTALLY_ACCEPTED\",\n  \"analysisDetails\": \"<string>\",\n  \"effectiveRefundedAmount\": 123,\n  \"refundTransactionId\": \"D1234567820260220123456789012345\",\n  \"rejectionReason\": \"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: '<string>',
    effectiveRefundedAmount: 123,
    refundTransactionId: 'D1234567820260220123456789012345',
    rejectionReason: 'NO_BALANCE'
  })
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close"

payload = {
    "analysisResult": "TOTALLY_ACCEPTED",
    "analysisDetails": "<string>",
    "effectiveRefundedAmount": 123,
    "refundTransactionId": "D1234567820260220123456789012345",
    "rejectionReason": "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)

{
  "amount": 1500,
  "createdAt": "2026-06-14T12:00:00Z",
  "endToEndId": "E12345678202607101200D3E4F5A6B7C",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "reason": "FRAUD",
  "reportStatus": "SENT",
  "requestedByISPB": "12345678",
  "status": "OPEN",
  "updatedAt": "2026-06-14T12:00:00Z",
  "analysisDetails": "<string>",
  "analysisResult": "TOTALLY_ACCEPTED",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "bacenCreationTime": "2026-06-14T12:00:00Z",
  "contestedISPB": "87654321",
  "effectiveRefundedAmount": 750,
  "fundsRecoveryId": "550e8400-e29b-41d4-a716-446655440003",
  "infractionReportId": "550e8400-e29b-41d4-a716-446655440004",
  "monitorAccount": true,
  "operationId": "01930000-0000-7000-8000-000000000000",
  "operationStatus": "UNKNOWN_OUTCOME",
  "originOperationId": "01930000-0000-7000-8000-000000000000",
  "refundAccount": {
    "accountNumber": "987654",
    "accountType": "CACC",
    "participant": "12345678",
    "taxIdNumber": "12345678909",
    "branch": "0001"
  },
  "refundDetails": "<string>",
  "refundTransactionId": "E99999010202606141430ZYXWVUTSRQP",
  "rejectionReason": "NO_BALANCE",
  "requestingISPB": "12345678"
}

{
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "operationStatus": "RESERVED"
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

POST

api

dict

refunds

{id}

Close DICT refund

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "analysisResult": "TOTALLY_ACCEPTED",
  "analysisDetails": "<string>",
  "effectiveRefundedAmount": 123,
  "refundTransactionId": "D1234567820260220123456789012345",
  "rejectionReason": "NO_BALANCE"
}
'

package main

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

func main() {

	url := "https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close"

	payload := strings.NewReader("{\n  \"analysisResult\": \"TOTALLY_ACCEPTED\",\n  \"analysisDetails\": \"<string>\",\n  \"effectiveRefundedAmount\": 123,\n  \"refundTransactionId\": \"D1234567820260220123456789012345\",\n  \"rejectionReason\": \"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: '<string>',
    effectiveRefundedAmount: 123,
    refundTransactionId: 'D1234567820260220123456789012345',
    rejectionReason: 'NO_BALANCE'
  })
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/close"

payload = {
    "analysisResult": "TOTALLY_ACCEPTED",
    "analysisDetails": "<string>",
    "effectiveRefundedAmount": 123,
    "refundTransactionId": "D1234567820260220123456789012345",
    "rejectionReason": "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)

{
  "amount": 1500,
  "createdAt": "2026-06-14T12:00:00Z",
  "endToEndId": "E12345678202607101200D3E4F5A6B7C",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "reason": "FRAUD",
  "reportStatus": "SENT",
  "requestedByISPB": "12345678",
  "status": "OPEN",
  "updatedAt": "2026-06-14T12:00:00Z",
  "analysisDetails": "<string>",
  "analysisResult": "TOTALLY_ACCEPTED",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "bacenCreationTime": "2026-06-14T12:00:00Z",
  "contestedISPB": "87654321",
  "effectiveRefundedAmount": 750,
  "fundsRecoveryId": "550e8400-e29b-41d4-a716-446655440003",
  "infractionReportId": "550e8400-e29b-41d4-a716-446655440004",
  "monitorAccount": true,
  "operationId": "01930000-0000-7000-8000-000000000000",
  "operationStatus": "UNKNOWN_OUTCOME",
  "originOperationId": "01930000-0000-7000-8000-000000000000",
  "refundAccount": {
    "accountNumber": "987654",
    "accountType": "CACC",
    "participant": "12345678",
    "taxIdNumber": "12345678909",
    "branch": "0001"
  },
  "refundDetails": "<string>",
  "refundTransactionId": "E99999010202606141430ZYXWVUTSRQP",
  "rejectionReason": "NO_BALANCE",
  "requestingISPB": "12345678"
}

{
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "operationStatus": "RESERVED"
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "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"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency

string

requerido

Required key used to prevent replaying the mutation.

Parámetros de ruta

string<uuid>

requerido

BACEN-assigned refund resource UUID; a local record UUID never resolves here

Cuerpo

application/json

closeRefund analysis body

analysisResult

enum<string>

requerido

Refund analysis outcome: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, or REJECTED

Opciones disponibles:

TOTALLY_ACCEPTED,

PARTIALLY_ACCEPTED,

REJECTED

Ejemplo:

"TOTALLY_ACCEPTED"

analysisDetails

string

Free-text analysis details; optional except when rejecting with INVALID_REQUEST, where DICT 8.4 §17 makes it mandatory.

effectiveRefundedAmount

number

Effective refunded amount as an exact decimal; required on a close bound to a funds recovery, validated against the refund amount when present

refundTransactionId

string

Identifier of the devolucao this closure executed. Mandatory when analysisResult is TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED, and must be the opposite message type from the contested transaction (a pacs.008 is refunded by a pacs.004 and vice-versa). Omit on a rejection.

Ejemplo:

"D1234567820260220123456789012345"

rejectionReason

enum<string>

BACEN rejection reason; mandatory when analysisResult is REJECTED, omit when accepted. INVALID_REQUEST is admissible only when the refund's own reason is OPERATIONAL_FLAW (DICT 8.4 §17).

Opciones disponibles:

NO_BALANCE,

ACCOUNT_CLOSURE,

INVALID_REQUEST,

OTHER

Ejemplo:

"NO_BALANCE"

Respuesta

Persisted local DICT refund request record, or {operationId, operationStatus} while BACEN's outcome is pending (202).

amount

number

requerido

Refund amount as an exact decimal number

Ejemplo:

1500

createdAt

string

requerido

Record creation timestamp (RFC 3339, UTC)

Ejemplo:

"2026-06-14T12:00:00Z"

endToEndId

string

requerido

BACEN end-to-end identifier (E2E ID) of the refunded PIX transaction

Ejemplo:

"E12345678202607101200D3E4F5A6B7C"

string

requerido

BACEN-assigned refund resource UUID — the public, canonical identity of this record

Ejemplo:

"550e8400-e29b-41d4-a716-446655440001"

reason

string

requerido

BACEN refund reason: FRAUD, OPERATIONAL_FLAW or PIX_AUTOMATICO

Ejemplo:

"FRAUD"

reportStatus

string

requerido

BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row).

Ejemplo:

"SENT"

requestedByISPB

string

requerido

ISPB (8 numeric digits) of the participant that requested the refund

Ejemplo:

"12345678"

status

enum<string>

requerido

DICT spec refund lifecycle state: OPEN, CLOSED, or CANCELLED. CLOSED alone does not say accept vs reject; see analysisResult.

Opciones disponibles:

OPEN,

CLOSED,

CANCELLED

Ejemplo:

"OPEN"

updatedAt

string

requerido

Last update timestamp (RFC 3339, UTC)

Ejemplo:

"2026-06-14T12:00:00Z"

analysisDetails

string

Free-text analysis details accompanying analysisResult; omitted until close (ours or the counterparty's, via refresh)

analysisResult

enum<string>

closeRefund analysis outcome: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, or REJECTED; omitted until close

Opciones disponibles:

TOTALLY_ACCEPTED,

PARTIALLY_ACCEPTED,

REJECTED

Ejemplo:

"TOTALLY_ACCEPTED"

bacen

object

BACEN's own operational envelope for its most recent interaction on this refund, including its LastModified version; omitted when no BACEN interaction has ever landed on it.

Show child attributes

bacenCreationTime

string

When BACEN created this refund request (RFC 3339, UTC); distinct from createdAt

Ejemplo:

"2026-06-14T12:00:00Z"

contestedISPB

string

BACEN-assigned contested participant ISPB (ExtendedRefund.ContestedParticipant)

Ejemplo:

"87654321"

effectiveRefundedAmount

number

MED 2.0: effective refunded amount recorded on an accepting close (exact decimal, verbatim); omitted until close

Ejemplo:

750

fundsRecoveryId

string

BACEN-assigned funds-recovery id this refund is bound to (refund-under-recovery); omitted for a standalone refund

Ejemplo:

"550e8400-e29b-41d4-a716-446655440003"

infractionReportId

string

BACEN-assigned infraction this refund was opened for (ExtendedRefund.InfractionReportId); omitted otherwise

Ejemplo:

"550e8400-e29b-41d4-a716-446655440004"

monitorAccount

boolean

MED 2.0: whether the destination account is monitored (ExtendedRefund.MonitorAccount); omitted when BACEN has never echoed a value, explicit true/false once it has

Ejemplo:

true

operationId

string

Durable MED operation-intent id: the operation that produced this resource's current state. Present on both a synchronous 200/201 and a pending 202.

Ejemplo:

"01930000-0000-7000-8000-000000000000"

operationStatus

enum<string>

Durable operation-intent status. Always COMPLETED on a synchronous 200/201; on a pending 202 it is never REJECTED or LOCAL_FAILURE — both are BACEN-final/local-final outcomes mapped to their own HTTP status instead of a 202.

Opciones disponibles:

RESERVED,

SUBMITTED,

CONFIRMED,

SYNC_PENDING,

UNKNOWN_OUTCOME,

MANUAL_REVIEW,

COMPLETED

Ejemplo:

"UNKNOWN_OUTCOME"

originOperationId

string

Durable operation-intent id that produced this snapshot's current state, when known

Ejemplo:

"01930000-0000-7000-8000-000000000000"

refundAccount

object

MED 2.0: destination account of a refund-under-recovery; omitted for a standalone refund

Show child attributes

refundDetails

string

Short description of why the refund was requested; present when the reason carries one

refundTransactionId

string

BACEN-executed refund transaction id (ExtendedRefund.RefundTransactionId), distinct from endToEndId; empty until a refund transaction exists

Ejemplo:

"E99999010202606141430ZYXWVUTSRQP"

rejectionReason

string

BACEN rejection reason accompanying a REJECTED analysisResult; omitted otherwise

Ejemplo:

"NO_BALANCE"

requestingISPB

string

BACEN-assigned requesting participant ISPB (ExtendedRefund.RequestingParticipant)

Ejemplo:

"12345678"