Create a funds recovery

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraphParameters": "<unknown>"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"contactInformation\": {\n    \"email\": \"user@example.com\",\n    \"phone\": \"+5511999999999\"\n  },\n  \"rootTransactionId\": \"E12345678202605171530aB3xK9mWq2z\",\n  \"situationType\": \"SCAM\",\n  \"metadata\": \"<unknown>\",\n  \"reportDetails\": \"Victim of a WhatsApp scam\",\n  \"trackingGraphParameters\": \"<unknown>\"\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({
    accountId: '550e8400-e29b-41d4-a716-446655440000',
    contactInformation: {email: 'user@example.com', phone: '+5511999999999'},
    rootTransactionId: 'E12345678202605171530aB3xK9mWq2z',
    situationType: 'SCAM',
    metadata: '<unknown>',
    reportDetails: 'Victim of a WhatsApp scam',
    trackingGraphParameters: '<unknown>'
  })
};

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

payload = {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "contactInformation": {
        "email": "user@example.com",
        "phone": "+5511999999999"
    },
    "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
    "situationType": "SCAM",
    "metadata": "<unknown>",
    "reportDetails": "Victim of a WhatsApp scam",
    "trackingGraphParameters": "<unknown>"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "Your request is missing one or more required header params.",
  "code": "PIX-0001"
}

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

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

Create a funds recovery

Opens a MED 2.0 funds recovery. A successful creation returns HTTP 201 with status CREATED. When BACEN has not resolved the creation yet, the recovery is stored as PENDING with an empty bacenFundsRecoveryId and returned with HTTP 202: keep its id and use it for every later operation. A PENDING recovery resolves when it is next read or operated on, or when the provider reports on it: it then reads as CREATED with its bacenFundsRecoveryId or, when BACEN never applied the creation, it is withdrawn and reads as 404 / PIX-0110, which frees the root transaction for a new creation. While it is PENDING, cancel, refund, and patch return 409 / PIX-0114, the tracking graph returns 404 / PIX-0110, and the linked lists are empty. Reusing an X-Idempotency header returns the original 201 or 202 response with HTTP 200; a failed creation is not cached, so repeating it runs the creation again. A duplicate recovery is rejected with 409 / PIX-0113. If the timestamp in rootTransactionId is outside the applicable MED contestation window, the request is rejected with 422 / PIX-0117. The window is determined by the funds recovery creation time: pacs.008 uses 80 calendar days; pacs.004 uses 30 calendar days before 2026-09-01T00:00:00Z and 80 calendar days from that instant onward. This timestamp validation does not confirm that the referenced transaction exists. The participant is determined by the authenticated tenant. participantId, reporterParticipant, rootTransactionType, and idempotencyKey are rejected when included in the body. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait.

POST

dict

funds-recoveries

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraphParameters": "<unknown>"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"contactInformation\": {\n    \"email\": \"user@example.com\",\n    \"phone\": \"+5511999999999\"\n  },\n  \"rootTransactionId\": \"E12345678202605171530aB3xK9mWq2z\",\n  \"situationType\": \"SCAM\",\n  \"metadata\": \"<unknown>\",\n  \"reportDetails\": \"Victim of a WhatsApp scam\",\n  \"trackingGraphParameters\": \"<unknown>\"\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({
    accountId: '550e8400-e29b-41d4-a716-446655440000',
    contactInformation: {email: 'user@example.com', phone: '+5511999999999'},
    rootTransactionId: 'E12345678202605171530aB3xK9mWq2z',
    situationType: 'SCAM',
    metadata: '<unknown>',
    reportDetails: 'Victim of a WhatsApp scam',
    trackingGraphParameters: '<unknown>'
  })
};

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

payload = {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "contactInformation": {
        "email": "user@example.com",
        "phone": "+5511999999999"
    },
    "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
    "situationType": "SCAM",
    "metadata": "<unknown>",
    "reportDetails": "Victim of a WhatsApp scam",
    "trackingGraphParameters": "<unknown>"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "correlationId": "7c9e6679742540de944be07fc1f90ae7",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam",
  "trackingGraph": "<unknown>",
  "trackingGraphParameters": "<unknown>"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "Your request is missing one or more required header params.",
  "code": "PIX-0001"
}

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

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

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

Idempotency key (at most 64 bytes); required on create. Enforced by the replay middleware, not the handler.

Example:

"a1b2c3d4-0000-0000-0000-000000000001"

Body

application/json

accountId

string

required

Example:

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

contactInformation

object

required

Show child attributes

rootTransactionId

string

required

Example:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

required

Available options:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Example:

"SCAM"

metadata

any

reportDetails

string

Example:

"Victim of a WhatsApp scam"

trackingGraphParameters

any

Response

Idempotent replay: a repeated X-Idempotency header returns the funds recovery created by the first request (cached response body).

accountId

string

required

Example:

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

bacenFundsRecoveryId

string

required

Recovery id the provider assigned. Empty while status is PENDING.

Example:

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

contactInformation

object

required

Show child attributes

createdAt

string<date-time>

required

Example:

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

string

required

Example:

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

participantId

string

required

Example:

"12345678"

reporterParticipant

string

required

Example:

"12345678"

rootTransactionId

string

required

Example:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

required

Available options:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Example:

"SCAM"

status

enum<string>

required

Available options:

PENDING,

CREATED,

TRACKED,

AWAITING_ANALYSIS,

ANALYSED,

REFUNDING,

COMPLETED,

CANCELLED

Example:

"CREATED"

updatedAt

string<date-time>

required

Example:

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

correlationId

string

Example:

"7c9e6679742540de944be07fc1f90ae7"

metadata

any

reportDetails

string

Example:

"Victim of a WhatsApp scam"

trackingGraph

any

trackingGraphParameters

any

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Create a funds recovery

Authorizations

Headers

Body

Response