Update a funds recovery

curl --request PATCH \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '"<string>"'

package main

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

func main() {

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

	payload := strings.NewReader("\"<string>\"")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PATCH',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify('<string>')
};

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

payload = "<string>"
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(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>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency 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 X-Idempotency header 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": "<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"
  }
}

Update a funds recovery

Applies a JSON merge-patch (Content-Type: application/merge-patch+json) to the mutable fields (contact information and report details) of a funds recovery owned by the authenticated participant. Only the fields present in the body are changed; any other field (metadata, status, participantId, …) is rejected with 422. Returns 404 when no active recovery with that ID belongs to the participant and 409 when the recovery’s current status no longer allows information changes, or when the provider refuses the report-details correction for the recovery’s state (PIX-0114). When the provider accepts the request but BACEN has not resolved it yet, the operation answers 409 / PIX-0118, carrying the operationId that identifies the operation at the provider and its operationStatus as field details (errors[].location operationId and operationStatus). Each is present only when the provider sent a valid value, so handle a pending answer without them too. Nothing changes here, and the correction is not reflected on its own when BACEN applies it. Sending the same request again records it only after the provider stops replaying this pending answer for it; until then the resend answers 409 / PIX-0118 again. If the provider is still processing an earlier request for the same operation, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait. The retry answers with the earlier request’s outcome, or with the recovery’s new state once it has changed.

PATCH

dict

funds-recoveries

{id}

Update a funds recovery

curl --request PATCH \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '"<string>"'

package main

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

func main() {

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

	payload := strings.NewReader("\"<string>\"")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PATCH',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify('<string>')
};

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

payload = "<string>"
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(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>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency 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 X-Idempotency header 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": "<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

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

Content-Type

string

Must be application/merge-patch+json.

Example:

"application/merge-patch+json"

Path Parameters

string

required

Funds recovery internal ID (UUID format)

Example:

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

Body

application/merge-patch+json

The body is of type file.

Response

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

Update a funds recovery

Authorizations

Headers

Path Parameters

Body

Response