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",
  "userComplaintAt": "2026-05-17T13:15:00Z",
  "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  \"userComplaintAt\": \"2026-05-17T13:15:00Z\",\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',
    userComplaintAt: '2026-05-17T13:15:00Z',
    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",
    "userComplaintAt": "2026-05-17T13:15:00Z",
    "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>"
}

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

{
  "code": "PIX-0112",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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. Resending the same request under an X-Idempotency header within one hour returns the original 201 or 202 response, status included, with the header X-Idempotency-Replayed: true; a resend while the first request still runs answers 412 / PIX-0112 with Retry-After: 1; 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",
  "userComplaintAt": "2026-05-17T13:15:00Z",
  "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  \"userComplaintAt\": \"2026-05-17T13:15:00Z\",\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',
    userComplaintAt: '2026-05-17T13:15:00Z',
    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",
    "userComplaintAt": "2026-05-17T13:15:00Z",
    "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>"
}

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

{
  "code": "PIX-0112",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

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

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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

Exemplo:

"a1b2c3d4-0000-0000-0000-000000000001"

Corpo

application/json

accountId

string

obrigatório

Exemplo:

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

contactInformation

object

obrigatório

Show child attributes

rootTransactionId

string

obrigatório

Exemplo:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

obrigatório

Opções disponíveis:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Exemplo:

"SCAM"

userComplaintAt

string<date-time>

obrigatório

The time the paying user's complaint was registered in your service channel, in RFC 3339. Required. A time later than the moment the recovery opens is refused with 422 (PIX-0100). Pix Lerian does not send it to BACEN; it relays it to the provider and stores it with the recovery.

Exemplo:

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

metadata

any

reportDetails

string

Exemplo:

"Victim of a WhatsApp scam"

trackingGraphParameters

any

Resposta

Created

accountId

string

obrigatório

Exemplo:

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

bacenFundsRecoveryId

string

obrigatório

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

Exemplo:

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

contactInformation

object

obrigatório

Show child attributes

createdAt

string<date-time>

obrigatório

Exemplo:

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

string

obrigatório

Exemplo:

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

participantId

string

obrigatório

Exemplo:

"12345678"

reporterParticipant

string

obrigatório

Exemplo:

"12345678"

rootTransactionId

string

obrigatório

Exemplo:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

obrigatório

Opções disponíveis:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Exemplo:

"SCAM"

status

enum<string>

obrigatório

Opções disponíveis:

PENDING,

CREATED,

TRACKED,

AWAITING_ANALYSIS,

ANALYSED,

REFUNDING,

COMPLETED,

CANCELLED

Exemplo:

"CREATED"

updatedAt

string<date-time>

obrigatório

Exemplo:

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

correlationId

string

Exemplo:

"7c9e6679742540de944be07fc1f90ae7"

metadata

any

reportDetails

string

Exemplo:

"Victim of a WhatsApp scam"

trackingGraph

any

trackingGraphParameters

any

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Create a funds recovery

Autorizações

Cabeçalhos

Corpo

Resposta