Create a refund

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refundAmount": "1000.00",
  "refundReason": "OPERATIONAL_FLAW",
  "transactionId": "E12345678202601011200abcdef01234",
  "refundDetails": "refund due to operational failure"
}
'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds"

	payload := strings.NewReader("{\n  \"refundAmount\": \"1000.00\",\n  \"refundReason\": \"OPERATIONAL_FLAW\",\n  \"transactionId\": \"E12345678202601011200abcdef01234\",\n  \"refundDetails\": \"refund due to operational failure\"\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({
    refundAmount: '1000.00',
    refundReason: 'OPERATIONAL_FLAW',
    transactionId: 'E12345678202601011200abcdef01234',
    refundDetails: 'refund due to operational failure'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds', 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"

payload = {
    "refundAmount": "1000.00",
    "refundReason": "OPERATIONAL_FLAW",
    "transactionId": "E12345678202601011200abcdef01234",
    "refundDetails": "refund due to operational failure"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "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 Idempotency-Key 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 Idempotency-Key was already used with a different request."
}

{
  "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": "PIX-0032",
  "title": "Idempotency Unavailable",
  "message": "The request was not processed because the idempotency store is unavailable. Please retry."
}

{
  "code": "ERR-0001",
  "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"
  }
}

Create a refund

Opens a MED 2.0 refund for a contested transaction. If an OPEN refund already exists for the same transaction, organization, and requesting participant, a sequential retry returns the existing refund with HTTP 200. Idempotency-Key is required and deduplicates retries, including concurrent requests. The transaction amount is validated against the SPI; a successful creation returns HTTP 201 with status OPEN. The requesting participant is determined by the authenticated tenant. participant, requestingParticipant, contestedParticipant, and organizationId are rejected when included in the body.

POST

dict

refunds

Create a refund

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refundAmount": "1000.00",
  "refundReason": "OPERATIONAL_FLAW",
  "transactionId": "E12345678202601011200abcdef01234",
  "refundDetails": "refund due to operational failure"
}
'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds"

	payload := strings.NewReader("{\n  \"refundAmount\": \"1000.00\",\n  \"refundReason\": \"OPERATIONAL_FLAW\",\n  \"transactionId\": \"E12345678202601011200abcdef01234\",\n  \"refundDetails\": \"refund due to operational failure\"\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({
    refundAmount: '1000.00',
    refundReason: 'OPERATIONAL_FLAW',
    transactionId: 'E12345678202601011200abcdef01234',
    refundDetails: 'refund due to operational failure'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds', 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"

payload = {
    "refundAmount": "1000.00",
    "refundReason": "OPERATIONAL_FLAW",
    "transactionId": "E12345678202601011200abcdef01234",
    "refundDetails": "refund due to operational failure"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "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 Idempotency-Key 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 Idempotency-Key was already used with a different request."
}

{
  "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": "PIX-0032",
  "title": "Idempotency Unavailable",
  "message": "The request was not processed because the idempotency store is unavailable. Please retry."
}

{
  "code": "ERR-0001",
  "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. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Correlation-Id

string

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

Cuerpo

application/json

refundAmount

string

requerido

Ejemplo:

"1000.00"

refundReason

enum<string>

requerido

Opciones disponibles:

FRAUD,

OPERATIONAL_FLAW,

PIX_AUTOMATICO,

REFUND_CANCELLED

Ejemplo:

"OPERATIONAL_FLAW"

transactionId

string

requerido

Ejemplo:

"E12345678202601011200abcdef01234"

refundDetails

string

Ejemplo:

"refund due to operational failure"

Respuesta

Created

contestedParticipant

string

requerido

Ejemplo:

"87654321"

creationTime

string<date-time>

requerido

Ejemplo:

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

string

requerido

Ejemplo:

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

lastModified

string<date-time>

requerido

Ejemplo:

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

monitorAccount

boolean

requerido

Ejemplo:

false

refundAmount

string

requerido

Ejemplo:

"1000.00"

refundReason

enum<string>

requerido

Opciones disponibles:

FRAUD,

OPERATIONAL_FLAW,

PIX_AUTOMATICO,

REFUND_CANCELLED

Ejemplo:

"OPERATIONAL_FLAW"

requestingParticipant

string

requerido

Ejemplo:

"12345678"

status

enum<string>

requerido

Opciones disponibles:

OPEN,

CLOSED,

CANCELLED

Ejemplo:

"OPEN"

transactionId

string

requerido

Ejemplo:

"E12345678202601011200abcdef01234"

alreadySettledAmount

string

analysisDetails

string

analysisResult

enum<string>

Opciones disponibles:

TOTALLY_ACCEPTED,

PARTIALLY_ACCEPTED,

REJECTED

bacenRefundId

string

Ejemplo:

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

correlationId

string

Ejemplo:

"9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f"

effectiveRefundedAmount

string

fundsRecoveryId

string

infractionReportId

string

refundAccount

object

Show child attributes

refundDetails

string

Ejemplo:

"refund due to operational failure"

refundRejectionReason

enum<string>

Opciones disponibles:

NO_BALANCE,

ACCOUNT_CLOSURE,

INVALID_REQUEST,

OTHER,

PARTICIPANT_EXCLUSION

refundTransactionId

string

settleReason

string

settleType

enum<string>

Opciones disponibles:

REFUND,

MANUAL

surplusAmount

string

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

Manejo de errores

Create a refund

Autorizaciones

Encabezados

Cuerpo

Respuesta