Create a FundsRecovery (Recuperação de Valores)

​

Submits a new PIX MED FundsRecovery request to DICT. The reporting participant is the local PSP configured via med.participant.ispb — clients must not supply it in the request body. On success the record transitions CREATED → AWAITING_ANALYSIS synchronously (TRACKED state skipped per DEC-019 receive-only posture). Bacen citation: DICT API v2.10.1 §4.2.4 passo 2 (mgmt/bacen-docs/med/Guia_MED.pdf, SHA256:d9daabc5, p.14).

Headers
  • Idempotency-Key
    Type: string
    required

    RFC-standard idempotency key (UUID, operation: MED_FR_CREATE); safe to retry on timeout

Body·
required
application/json

Request body to create a new FundsRecovery record (Recuperação de Valores MED 2.0). Bacen-conformant per OpenAPI v2.10.1 FundsRecovery.required.

  • contactInformation
    Type: object ·
    required

    Contact information for the fraud reporting team

  • situationType
    Type: string enum
    required

    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
  • transactionId
    Type: string
    min length:  
    1    Pattern: [A-Za-z0-9]{8,32}
    required

    End-to-end ID of the original PIX transaction subject to funds recovery (Bacen EndToEndId, alphanumeric, 8–32 chars)

  • reportDetails
    Type: string
    max length:  
    2000

    Free-text details about the fraud situation (max 2000 chars; required when situationType=OTHER)

  • trackingParameters
    Type: object | null ·

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

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/funds-recovery
curl http://localhost:8080/api/v1/funds-recovery \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "transactionId": "",
  "situationType": "SCAM",
  "reportDetails": "",
  "contactInformation": {
    "email": "",
    "phone": ""
  },
  "trackingParameters": {
    "minTransactionAmount": 0.01,
    "maxTransactions": 1,
    "hopWindow": "PT24H",
    "maxHops": 1
  }
}'

{
  "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.556Z",
  "lastModified": "2026-07-29T19:28:46.556Z"
}

FundsRecovery created and submitted to DICT successfully.