Cancel DICT refund

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

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

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	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>'}
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/cancel', 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}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, 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}

cancel

Cancel DICT refund

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

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

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	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>'}
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/refunds/{id}/cancel', 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}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, 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

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"