Update advisory fields of a FundsRecovery record

​

Updates advisory fields (situationType, contactInformation, reportDetails) of a PIX MED FundsRecovery record via PATCH — only supplied fields are changed (merge semantics; null = no change). Allowed ONLY while the record is in one of the 3 update-permitted states: CREATED, TRACKED, or AWAITING_ANALYSIS — per Bacen Manual Operacional do DICT v8.1 §20.1.11 ("É possível alterar uma Recuperação de Valores que esteja nos estados CREATED, TRACKED ou AWAITING_ANALYSIS"). All other states (ANALYSED, REFUNDING, COMPLETED, CANCELLED) reject with HTTP 409. State transitions happen exclusively via POST /{id}/cancel or POST /{id}/refund. Note: trackingParameters are immutable after creation (Bacen DICT API v2.10.1 §4.2.4). Bacen citation: Manual DICT v8.1 §20.1.11 (state rule) + Guia MED v4.1 §4.2.4 passo 3 (mgmt/bacen-docs/med/Guia_MED.pdf, SHA256:d9daabc5, p.14).

Path Parameters
  • id
    Type: string Format: uuid
    required

    UUID of the FundsRecovery record to update

Headers
  • Idempotency-Key
    Type: string
    required

    RFC-standard idempotency key (UUID, operation: MED_FR_UPDATE)

Body·
required
application/json

Partial update payload for a FundsRecovery record. All fields are optional. Only advisory fields (situationType, contactInformation, reportDetails) may be changed via PATCH. State transitions happen exclusively via POST /{id}/cancel or POST /{id}/refund. Null fields are ignored (merge semantics, no explicit-clear in V1).

  • contactInformation
    Type: object ·

    Contact information for the fraud reporting team

  • reportDetails
    Type: string
    max length:  
    2000

    Updated free-text details about the fraud situation (max 2000 chars; omit to leave unchanged)

  • situationType
    Type: string enum

    Type of fraud/dispute situation (per Bacen DICT API v2.10.1 SituationType schema — shared across InfractionReport and FundsRecovery)

    values
    • SCAM
    • ACCOUNT_TAKEOVER
    • COERCION
    • FRAUDULENT_ACCESS
    • OTHER
    • UNKNOWN
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/funds-recovery/{id}
curl http://localhost:8080/api/v1/funds-recovery/123e4567-e89b-12d3-a456-426614174000 \
  --request PATCH \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "situationType": "SCAM",
  "reportDetails": "",
  "contactInformation": {
    "email": "",
    "phone": ""
  }
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "string",
  "status": "CREATED",
  "participantIspb": "string",
  "situationType": "SCAM",
  "reportDetails": null,
  "contactEmail": null,
  "contactPhone": null,
  "trackingParameters": {
    "minTransactionAmount": 0.01,
    "maxTransactions": 1,
    "hopWindow": "PT24H",
    "maxHops": 1
  },
  "effectiveRefundedAmount": null,
  "createdAt": "2026-07-29T19:28:46.547Z",
  "lastModified": "2026-07-29T19:28:46.547Z"
}

FundsRecovery record updated successfully.