Initiate a refund for a funds recovery

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund"

	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://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund', 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/funds-recoveries/{id}/refund"

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

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

print(response.text)

{
  "bacenFundsRecoveryId": "9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "createdAt": "2026-05-17T13:30:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "REFUNDING",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "reportDetails": "Victim of a WhatsApp scam"
}

{
  "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-0110",
  "title": "Not Found",
  "status": 404,
  "detail": "No funds recovery exists with the provided ID for this participant.",
  "code": "PIX-0110"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0113",
  "title": "Conflict",
  "status": 409,
  "detail": "A funds recovery already exists for this root transaction.",
  "code": "PIX-0113"
}

{
  "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-0100",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Missing or malformed required fields.",
  "code": "PIX-0100"
}

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

Initiate a refund for a funds recovery

Initiates a refund for a funds recovery in the ANALYSED state, within the scope of the participant determined by the authenticated tenant. The recovery changes to REFUNDING, and the updated recovery is returned with HTTP 200. Returns 404 when no active recovery with that ID belongs to the participant and 409 when its current state does not allow a refund. The response is a concise funds recovery representation.

POST

dict

funds-recoveries

{id}

refund

Initiate a refund for a funds recovery

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund"

	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://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/refund', 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/funds-recoveries/{id}/refund"

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

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

print(response.text)

{
  "bacenFundsRecoveryId": "9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "createdAt": "2026-05-17T13:30:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "REFUNDING",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "reportDetails": "Victim of a WhatsApp scam"
}

{
  "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-0110",
  "title": "Not Found",
  "status": 404,
  "detail": "No funds recovery exists with the provided ID for this participant.",
  "code": "PIX-0110"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0113",
  "title": "Conflict",
  "status": 409,
  "detail": "A funds recovery already exists for this root transaction.",
  "code": "PIX-0113"
}

{
  "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-0100",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Missing or malformed required fields.",
  "code": "PIX-0100"
}

{
  "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": "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).

Ejemplo:

"7c9e6679742540de944be07fc1f90ae7"

Parámetros de ruta

string

requerido

Funds recovery internal ID (UUID format)

Ejemplo:

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

Respuesta

bacenFundsRecoveryId

string

requerido

Ejemplo:

"9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f"

contactInformation

object

requerido

Show child attributes

createdAt

string<date-time>

requerido

Ejemplo:

"2026-05-17T13:30:00Z"

string

requerido

Ejemplo:

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

reporterParticipant

string

requerido

Ejemplo:

"12345678"

rootTransactionId

string

requerido

Ejemplo:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

requerido

Opciones disponibles:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Ejemplo:

"SCAM"

status

enum<string>

requerido

Opciones disponibles:

CREATED,

TRACKED,

AWAITING_ANALYSIS,

ANALYSED,

REFUNDING,

COMPLETED,

CANCELLED

Ejemplo:

"REFUNDING"

correlationId

string

Ejemplo:

"7c9e6679742540de944be07fc1f90ae7"

reportDetails

string

Ejemplo:

"Victim of a WhatsApp scam"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

Manejo de errores

Initiate a refund for a funds recovery

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta