FundsRecoveryResponse

FundsRecovery (Recuperação de Valores MED 2.0) record details returned by the API. Includes lifecycle status, participant identity, fraud situation characterisation, contact information, and optional tracking graph parameters.

  • contactEmail
    Type: string | null

    Contact email of the reporting PSP's fraud team; null when not provided

  • contactPhone
    Type: string | null

    Contact phone of the reporting PSP's fraud team; null when not provided

  • createdAt
    Type: string Format: date-time

    ISO-8601 timestamp of record creation (UTC)

  • effectiveRefundedAmount
    Type: number | null

    Cached total refunded amount (BRL) from DICT listRefunds, populated after REFUNDING state. Null if not yet computed (DICT-502 at refund time or pre-Wave-3 record). Wave 3 F9 field — used by cancel-from-REFUNDING settlement-return gate.

  • id
    Type: string Format: uuid

    Unique identifier of the FundsRecovery record (UUID v7)

  • lastModified
    Type: string Format: date-time

    ISO-8601 timestamp of the last state change (UTC)

  • participantIspb
    Type: string

    ISPB of the participant who reported the FundsRecovery (8-digit Bacen code)

  • reportDetails
    Type: string | null

    Free-text description of the fraud situation (max 2000 chars); null when not provided

  • situationType
    Type: string | null 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
  • status
    Type: string enum

    Lifecycle status of a FundsRecovery record per Bacen DICT API v2.10.1 §4.2.4. TRACKED is included for spec completeness but not externally observable in receive-only deployments.

    values
    • CREATED
    • TRACKED
    • AWAITING_ANALYSIS
    • ANALYSED
    • REFUNDING
    • COMPLETED
    • CANCELLED
  • trackingParameters
    Type: object | null · TrackingGraphParameters

    Tracking graph parameters used for forensic analysis; null when not provided

    • hopWindow
      Type: string Format: duration

      Time window around each transaction that DICT considers when linking graph edges. ISO-8601 duration. Optional (Bacen default: PT24H).

    • maxHops
      Type: integer Format: int32
      min:  
      1
      max:  
      10

      Maximum number of hops (graph depth) that DICT will traverse from the originating transaction. Limits depth of the fraud network analysis. Optional (Bacen default: 5; Bacen ceiling: 10 per OpenAPI v2.10.1 line 4748).

    • maxTransactions
      Type: integer Format: int32
      min:  
      1

      Maximum number of outgoing transactions per account node that DICT will follow. Caps graph traversal breadth to prevent analysis explosion on high-volume accounts. Optional (Bacen default: 500).

    • minTransactionAmount
      Type: number
      min:  
      0.01

      Minimum transaction amount (BRL) to include in the forensic graph traversal. Transactions below this value are excluded from the fraud network graph. Optional — Bacen applies its own floor when absent (default: 200.00).

  • transactionId
    Type: string

    End-to-end ID of the original disputed PIX transaction