Create a Funds Recovery Request

Use this endpoint to create a new funds recovery request for a Pix transaction suspected of fraud.

Notes:

• The rootTransactionId must be a valid 32-character Pix End-to-End ID
• situationType indicates the type of fraud situation (SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN)
• Contact information (email and phone) is required for communication during the recovery process

POST /v1/dict/funds-recoveries

Create a Funds Recovery Request

cURL

curl --request POST \
  --url https://api.example.com/v1/dict/funds-recoveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactInformation": {
    "email": "[e-mail]",
    "phone": "[phone]"
  },
  "rootTransactionId": "E12345678202411241430ABCDEFGHIJK",
  "situationType": "SCAM",
  "reportDetails": "Customer reported receiving a call from fake bank employee",
  "trackingGraphParameters": {
    "hopWindow": "PT24H",
    "maxHops": 2,
    "maxTransactions": 5,
    "minTransactionAmount": "200.00"
  }
}
'

201

{
  "bacenFundsRecoveryId": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
  "createdAt": "2023-11-07T05:31:56Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202411241430ABCDEFGHIJK",
  "situationType": "SCAM",
  "status": "CREATED",
  "updatedAt": "2023-11-07T05:31:56Z",
  "contactInformation": {
    "email": "[e-mail]",
    "phone": "[phone]"
  },
  "reportDetails": "Customer reported receiving a call from fake bank employee",
  "trackingGraph": {
    "accounts": [
      {
        "id": 1,
        "openingDate": "2020-01-15",
        "ownerId": 1,
        "participant": "12345678"
      }
    ],
    "creationTime": "2023-11-07T05:31:56Z",
    "fundsRecoveryId": "550e8400-e29b-41d4-a716-446655440000",
    "parameters": {
      "hopWindow": "PT24H",
      "maxHops": 2,
      "maxTransactions": 5,
      "minTransactionAmount": "200.00"
    },
    "persons": [
      {
        "id": 1,
        "type": "NATURAL_PERSON",
        "entityCreationDate": "2020-01-15"
      }
    ],
    "rootTransactionId": "E12345678202411241430ABCDEFGHIJK",
    "transactions": [
      {
        "amount": 1000.5,
        "creditorAccountId": 2,
        "debtorAccountId": 1,
        "id": "E12345678202411241430ABCDEFGHIJK",
        "refundableAmount": 1000.5,
        "settlementTime": "2023-11-07T05:31:56Z",
        "transactionDepth": 1
      }
    ]
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Account-Id · string<uuid>

Account ID (UUID) from X-Account-Id header

Cuerpo

application/json

contactInformation · object · requerido

Contact information of the person reporting the fraud

Show child attributes

rootTransactionId · string · requerido

Pix End-to-End transaction ID (32 characters)

Minimum string length: 1

Ejemplo:

"E12345678202411241430ABCDEFGHIJK"

situationType · enum<string> · requerido

Type of fraud situation

Opciones disponibles: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN

Minimum string length: 1

Ejemplo:

"SCAM"

reportDetails · string

Detailed description of the fraud incident (max 2000 characters)

Maximum string length: 2000

Ejemplo:

"Customer reported receiving a call from fake bank employee"

trackingGraphParameters · object

Optional parameters for tracking graph generation

Show child attributes

Respuesta

201

application/json

Created

bacenFundsRecoveryId · string · requerido

BACEN/BTG funds recovery external identifier

Ejemplo:

"91d65e98-97c0-4b0f-b577-73625da1f9fc"

createdAt · string<date-time> · requerido

Creation timestamp (ISO 8601 UTC)

Ejemplo:

"2023-11-07T05:31:56Z"

id · string · requerido

Unique identifier for the funds recovery (UUID)

Ejemplo:

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

reporterParticipant · string · requerido

ISPB of the PSP reporting the fraud (8 uppercase alphanumeric characters)

Ejemplo:

"12345678"

rootTransactionId · string · requerido

Pix End-to-End transaction ID (32 characters)

Ejemplo:

"E12345678202411241430ABCDEFGHIJK"

situationType · enum<string> · requerido

Type of fraud situation

Opciones disponibles: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN

Ejemplo:

"SCAM"

status · enum<string> · requerido

Current status of the funds recovery

Opciones disponibles: CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, CANCELLED

Ejemplo:

"CREATED"

updatedAt · string<date-time> · requerido

Last update timestamp (ISO 8601 UTC)

Ejemplo:

"2023-11-07T05:31:56Z"

contactInformation · object

Contact information of the person reporting the fraud

Show child attributes

reportDetails · string

Detailed description of the fraud incident

Ejemplo:

"Customer reported receiving a call from fake bank employee"

trackingGraph · object

Tracking graph generated during creation (when trackingGraphParameters provided)

Show child attributes