Guides
Sub-processorsAbout PismoContact us

Pix funds recovery [beta]

This guide details the process for recovering funds in Pix. There are two flows you can use.

  • INTERACTIVE—The Payment Service Provider (PSP) has full process control and is able to request multiple graphs and manually define prioritization.
  • AUTOMATIC—The Diretório de Identificadores de Contas Transacionais (DICT)—a national Pix key registry and database—automatically manages tracking and blocking using a standard algorithm.

When to use each flow

CriteriaINTERACTIVEAUTOMATIC
Case complexityHighLow/Medium
Need for human analysisYesNo
Case volumeLow/MediumHigh
Control over prioritizationTotalDelegated to DICT
Parameter experimentationYesNo
Response timeSlowerFaster

Flow examples

INTERACTIVE flow example

Scenario

Case: Fake investment scam with complex dispersion

  • Victim: João Silva (CPF: 123.456.789-00)
  • Amount: R$ 50,000.00
  • Fraud date: 11/10/2025 at 2:30 PM
  • Situation: Fraudster dispersed funds to multiple accounts across different banks
  • Objective: PSP wants to carefully analyze the graph before prioritizing blocks

Timeline

Day 1 - 11/10/2025

2:30 PM - Fraudulent rransaction occurs
Victim (PSP A) → Fraudster (PSP B)
EndToEndId: E12345678901234567890123456789001
Amount: R$ 50,000.00
3:00 PM - Victim reports to PSP

João calls PSP, reporting that he was a victim of a fake investment scam.

3:30 PM - PSP validates eligibility
# PSP verifies:
- ✅ Transaction less than 80 days old
- ✅ Client has clean history
- ✅ Evidence of fraud (screenshots, conversations)
- ✅ Police report filed
3:45 PM - STEP 1: Funds recovery creation (INTERACTIVE)

Create funds recovery

Request:

POST /v1/pix/funds-recoveries

{
  "flow_type": "INTERACTIVE",
  "root_transaction_id": "E12345678901234567890123456789001",
  "situation_type": "SCAM",
  "contact_information": {
    "email": "[email protected]",
    "phone": "+5511987654321"
  },
  "report_details": "Client reports fake investment scam. Promised 20% monthly return. After transfer, scammer disappeared."
}

Response (201 Created):

{
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "root_transaction_id": "E12345678901234567890123456789001",
  "created_at": "2025-11-10T15:45:00Z"
}

Note: DICT creates the funds recovery and immediately generates an infraction notification for PSP B (root transaction). PSP B blocks R$ 50,000 (or available balance).

3:46 PM - Status event published

Event received:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "schema_version": 1,
  "org_id": "TN-org-psp-a",
  "cid": "cid-001",
  "timestamp": "2025-11-10T15:46:00Z",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CREATED",
    "flow_type": "INTERACTIVE",
    "root_transaction_id": "E12345678901234567890123456789001",
    "situation_type": "SCAM",
    "reporter_participant": "12345678",
    "changed_at": "2025-11-10T15:46:00Z"
  }
}
4:00 PM - STEP 2: Tracking graph creation (attempt 1)

PSP A decides to start with conservative parameters to get an initial view.

Create tracking graph

Request:

POST /v1/pix/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/tracking-graph

{
  "tracking_graph_parameters": {
    "min_transaction_amount": 1000.00,
    "max_transactions": 50,
    "hop_window": "PT2H",
    "max_hops": 3
  }
}

Response (202 Accepted):

{
  "code": "EPDA0000",
  "message": "Tracking graph flow will continue asynchronously"
}
4:05 PM - Graph Created (Status: TRACKED)

DICT processes the tracking and returns a graph with 12 transactions.

Event received:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TRACKED",
    "changed_at": "2025-11-10T16:05:00Z"
  }
}
4:10 PM - PSP queries the graph

Get tracking graph

Request:

GET /v1/pix/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/tracking-graph

Response (200 OK) - Simplified graph:

{
  "graph_id": "graph-001",
  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
  "parameters": {
    "min_transaction_amount": 1000.00,
    "max_transactions": 50,
    "hop_window": "PT2H",
    "max_hops": 3
  },
  "persons": [
    {"id": "P1", "type": "NATURAL_PERSON"},
    {"id": "P2", "type": "NATURAL_PERSON"},
    {"id": "P3", "type": "NATURAL_PERSON"},
    {"id": "P4", "type": "NATURAL_PERSON"}
  ],
  "accounts": [
    {"id": "A1", "owner_id": "P1", "participant": "12345678"},
    {"id": "A2", "owner_id": "P2", "participant": "87654321"},
    {"id": "A3", "owner_id": "P3", "participant": "11111111"},
    {"id": "A4", "owner_id": "P4", "participant": "22222222"}
  ],
  "transactions": [
    {
      "id": "E12345678901234567890123456789001",
      "debtor_account_id": "A1",
      "creditor_account_id": "A2",
      "amount": 50000.00,
      "refundable_amount": 5000.00,
      "settlement_time": "2025-11-10T14:30:00Z",
      "hop": 0
    },
    {
      "id": "E12345678901234567890123456789002",
      "debtor_account_id": "A2",
      "creditor_account_id": "A3",
      "amount": 30000.00,
      "refundable_amount": 15000.00,
      "settlement_time": "2025-11-10T14:45:00Z",
      "hop": 1
    },
    {
      "id": "E12345678901234567890123456789003",
      "debtor_account_id": "A2",
      "creditor_account_id": "A4",
      "amount": 15000.00,
      "refundable_amount": 10000.00,
      "settlement_time": "2025-11-10T14:50:00Z",
      "hop": 1
    }
  ],
  "summary": {
    "total_transactions": 12,
    "total_amount": 95000.00,
    "max_hop_reached": 3
  },
  "created_at": "2025-11-10T16:05:00Z"
}
4:15 PM - Analyst evaluates the graph
PSP A Analysis:
- Root transaction: R$ 50,000 → only R$ 5,000 available (fraudster withdrew almost everything)
- Hop 1: R$ 30,000 → R$ 15,000 available (money mule account 1)
- Hop 1: R$ 15,000 → R$ 10,000 available (money mule account 2)
- Hops 2-3: Small amounts dispersed

Conclusion: Parameters too conservative.
Decision: Request new graph with more aggressive parameters.
4:20 PM - Tracking graph creation (attempt 2)

Create tracking graph

Request:

POST /v1/pix/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/tracking-graph

{
  "tracking_graph_parameters": {
    "min_transaction_amount": 100.00,
    "max_transactions": 200,
    "hop_window": "PT6H",
    "max_hops": 5
  }
}
4:30 PM - New graph created

Graph returns with 45 transactions, including smaller dispersions revealing a pattern of "atomization" of funds.

4:40 PM - STEP 3: Manual prioritization

PSP A analyst defines prioritization based on:

  1. Accounts with highest available balance
  2. Recently opened accounts (mules)
  3. Fast dispersion pattern

Prioritized transaction list (BFS ordering):

[
  "E12345678901234567890123456789001", // Root (mandatory)
  "E12345678901234567890123456789002", // Hop 1 - R$ 15,000 available
  "E12345678901234567890123456789003", // Hop 1 - R$ 10,000 available
  "E12345678901234567890123456789007", // Hop 2 - R$ 8,000 available
  "E12345678901234567890123456789008", // Hop 2 - R$ 7,000 available
  "E12345678901234567890123456789012"  // Hop 3 - R$ 5,000 available
]
4:45 PM - STEP 4: Block request

Block funds recovery

Request:

POST /v1/pix/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/block

{
  "prioritization_strategy": "TRANSACTION_LIST",
  "transactions": [
    "E12345678901234567890123456789001",
    "E12345678901234567890123456789002",
    "E12345678901234567890123456789003",
    "E12345678901234567890123456789007",
    "E12345678901234567890123456789008",
    "E12345678901234567890123456789012"
  ]
}

Response (202 Accepted):

{
  "code": "EPDA0000",
  "message": "Block funds recovery flow will continue asynchronously"
}
4:50 PM - Notifications rent (Status: AWAITING_ANALYSIS)

DICT validates prioritization and sends 6 infraction notifications to PSPs:

PSPEndToEndIdBlock AmountStatus
PSP BE1...001R$ 5,000Already blocked (root)
PSP CE1...002R$ 15,000Block requested
PSP DE1...003R$ 10,000Block requested
PSP EE1...007R$ 8,000Block requested
PSP FE1...008R$ 7,000Block requested
PSP GE1...012R$ 5,000Block requested

Event received:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "AWAITING_ANALYSIS",
    "changed_at": "2025-11-10T16:50:00Z"
  }
}

Days 2-8 - 11/11/2025 to 11/17/2025

STEP 5: Analysis by receiving PSPs (7 days)

Each PSP analyzes their notification:

11/11 - PSP C analyzes:

- Account opened 2 days ago (mule)
- Multiple transfers received and sent on the same day
- Client doesn't respond to contact
- Decision: ACCEPT

11/12 - PSP D analyzes:

- Old account (5 years)
- Client claims legitimate purchase
- Presents proof of sale (fake)
- Decision: REJECT

11/13 - PSP E analyzes:

- Account opened 1 day ago (mule)
- Full withdrawal made 2 hours after receiving
- Decision: ACCEPT

11/14 - PSP F analyzes:

- Account with fraud history
- Previous infraction marking
- Decision: ACCEPT

11/15 - PSP G analyzes:

- Account opened 3 days ago (mule)
- Multiple suspicious transfers
- Decision: ACCEPT

11/17 - 7-day deadline expires:

  • PSP B didn't respond → Considered REJECTED
11/17 4:50 PM - Status Changes to ANALYSED

Event received:

Pix funds recovery status changed 

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "ANALYSED",
    "changed_at": "2025-11-17T16:50:00Z"
  }
}

Day 9 - 11/18/2025

10:00 AM - PSP A Queries Analysis Results
GET /v2/pix/infraction-reports?fundsRecoveryId=550e8400-e29b-41d4-a716-446655440000

Response:

{
  "items": [
    {
      "id": "IR-001",
      "transaction_id": "E12345678901234567890123456789001",
      "status": "REJECTED",
      "counterparty_participant": "87654321"
    },
    {
      "id": "IR-002",
      "transaction_id": "E12345678901234567890123456789002",
      "status": "ACCEPTED",
      "counterparty_participant": "11111111"
    },
    {
      "id": "IR-003",
      "transaction_id": "E12345678901234567890123456789003",
      "status": "REJECTED",
      "counterparty_participant": "22222222"
    },
    {
      "id": "IR-004",
      "transaction_id": "E12345678901234567890123456789007",
      "status": "ACCEPTED",
      "counterparty_participant": "33333333"
    },
    {
      "id": "IR-005",
      "transaction_id": "E12345678901234567890123456789008",
      "status": "ACCEPTED",
      "counterparty_participant": "44444444"
    },
    {
      "id": "IR-006",
      "transaction_id": "E12345678901234567890123456789012",
      "status": "ACCEPTED",
      "counterparty_participant": "55555555"
    }
  ]
}

Summary:

  • ✅ Accepted: 4 transactions (R$ 35,000 potential)
  • ❌ Rejected: 2 transactions (R$ 15,000 lost)
10:30 AM - STEP 6: Refund request

Request:

Initiate refund funds recovery

POST /v1/pix/funds-recoveries/550e8400-e29b-41d4-a716-446655440000/refund

Response (202 Accepted):

{
  "code": "EPDA0000",
  "message": "Refund funds recovery flow will continue asynchronously"
}
10:35 AM - Status changes to REFUNDING

Event received:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "REFUNDING",
    "changed_at": "2025-11-18T10:35:00Z"
  }
}
10:40 AM - Sequential refunds initiated

DICT builds refund graph (accepted transactions only) and processes refunds sequentially:

Refund order:
1. E1...002 (PSP C) → R$ 15,000
2. E1...007 (PSP E) → R$ 8,000
3. E1...008 (PSP F) → R$ 7,000
4. E1...012 (PSP G) → R$ 5,000

Result: All refunds processed successfully
11:20 AM - Status changes to COMPLETED

Event received:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "changed_at": "2025-11-18T11:20:00Z"
  }
}
11:30 AM - PSP A notifies client
Email to João Silva:

Dear João,

Your funds recovery request has been completed.

Original Fraud Amount: R$ 50,000.00
Recovered Amount: R$ 35,000.00
Recovery Rate: 70%

The funds have been returned to your account.

Details:
- 4 institutions returned funds
- 2 institutions rejected (no evidence of fraud)

Sincerely,
Fraud Team - PSP A

INTERACTIVE flow summary

Timeline:
- Day 1 (3:45 PM): Creation (CREATED)
- Day 1 (4:05 PM): First graph (TRACKED)
- Day 1 (4:30 PM): Second graph (TRACKED)
- Day 1 (4:50 PM): Block (AWAITING_ANALYSIS)
- Day 9 (4:50 PM): Analysis completed (ANALYSED)
- Day 10 (10:35 AM): Refund initiated (REFUNDING)
- Day 10 (11:20 AM): Process completed (COMPLETED)

Result:
✅ R$ 35,000 recovered (70%)
❌ R$ 15,000 not recovered (30%)

INTERACTIVE flow advantages:
- PSP tested different graph parameters
- Manually prioritized accounts with higher balances
- Focused on suspicious accounts (mules)
- Full control over the process
AUTOMATIC flow example

Scenario

Case: Wrong PIX scam (high volume, standard case)

  • Victim: Maria Santos (CPF: 987.654.321-00)
  • Amount: R$ 800.00
  • Fraud date: 11/10/2025 at 9:15 AM
  • Situation: Scammer convinced victim to send PIX "by mistake"
  • Objective: PSP wants to process quickly using DICT's standard algorithm

Timeline

Day 1 - 11/10/2025

9:15 AM - Fraudulent transaction occurs
Victim (PSP A) → Scammer (PSP B)
EndToEndId: E98765432109876543210987654321001
Amount: R$ 800.00
9:30 AM - Victim reports to PSP

Maria calls PSP A reporting that she was a victim of a scam.

9:45 AM - STEP 1: Funds recovery creation (AUTOMATIC)

PSP A Request:

Create funds recovery

POST /v1/pix/funds-recoveries

{
  "flow_type": "AUTOMATED",
  "root_transaction_id": "E98765432109876543210987654321001",
  "situation_type": "SCAM",
  "contact_information": {
    "email": "[email protected]",
    "phone": "+5511987654321"
  },
  "report_details": "Client reports wrong PIX scam. Scammer claimed to have sent PIX by mistake and requested refund.",
  "tracking_graph_parameters": {
    "min_transaction_amount": 50.00,
    "max_transactions": 100,
    "hop_window": "PT1H",
    "max_hops": 4
  }
}

Response (202 Accepted):

{
  "code": "EPDA0000",
  "message": "Funds recovery flow will continue asynchronously"
}
9:46 AM - Automatic processing initiated

Note: DICT processes automatically:

  • Creates funds recovery
  • Sends root transaction infraction notification (PSP B blocks funds)
  • Builds tracking graph (8 transactions, 3 hops)
  • Calculates automatic prioritization
  • Sends infraction notifications to 5 PSPs
9:50 AM - Event: CREATED

Event published:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "CREATED",
    "flow_type": "AUTOMATED",
    "changed_at": "2025-11-10T09:50:00Z"
  }
}
9:55 AM - Event: AWAITING_ANALYSIS

After complete automatic processing, status changes directly to AWAITING_ANALYSIS:

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "AWAITING_ANALYSIS",
    "flow_type": "AUTOMATED",
    "changed_at": "2025-11-10T09:55:00Z"
  }
}

Important note: In AUTOMATIC flow, the status never goes through TRACKED, as the graph is created internally by DICT without exposure to the PSP.

10:00 AM - PSP A Receives Confirmation

PSP A queries the recovery:

Get funds recovery

GET /v1/pix/funds-recoveries/650e8400-e29b-41d4-a716-446655440001

Response:

{
  "id": "650e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_ANALYSIS",
  "flow_type": "AUTOMATED",
  "root_transaction_id": "E98765432109876543210987654321001",
  "situation_type": "SCAM",
  "reporter_participant": "12345678",
  "created_at": "2025-11-10T09:45:00Z",
  "updated_at": "2025-11-10T09:55:00Z"
}

Days 2-8 - 11/11/2025 to 11/17/2025

STEP 2: Analysis by receiving PSPs (7 days)

11/11 - PSP B analyzes (root transaction):

- Blocked balance: R$ 300 (of R$ 800)
- Client has complaint history
- Account with atypical movement
- Decision: ACCEPT

11/11 - PSP C analyzes:

- Mule account (opened 1 day ago)
- Blocked balance: R$ 200
- Decision: ACCEPT

11/12 - PSP D analyzes:

- Old account with clean history
- Client claims legitimate product sale
- Decision: REJECT

11/13 - PSP E analyzes:

- Mule account (opened 3 days ago)
- Multiple suspicious transfers
- Decision: ACCEPT

11/14 - PSP F analyzes:

- Account with fast dispersion pattern
- Blocked balance: R$ 80
- Decision: ACCEPT
11/17 9:55 AM - Status Changes to ANALYSED

After 7 days or all responses, status automatically changes:

Event published:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "ANALYSED",
    "changed_at": "2025-11-17T09:55:00Z"
  }
}

Day 9 - 11/18/2025

8:00 AM - PSP A queries results

Get infraction report

GET /v2/pix/infraction-reports?fundsRecoveryId=650e8400-e29b-41d4-a716-446655440001

Analysis summary:

  • ✅ Accepted: 4 transactions (R$ 680 potential)
  • ❌ Rejected: 1 transaction (R$ 150 lost)
8:30 AM - STEP 3: Refund Request

Request:

Initiate refund funds recovery

POST /v1/pix/funds-recoveries/650e8400-e29b-41d4-a716-446655440001/refund

Response (202 Accepted):

{
  "code": "EPDA0000",
  "message": "Refund funds recovery flow will continue asynchronously"
}
8:35 AM - Status Changes to REFUNDING

Event published:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "REFUNDING",
    "changed_at": "2025-11-18T08:35:00Z"
  }
}
8:40 AM - Sequential refunds

DICT builds refund graph (accepted transactions only) and processes refunds sequentially:

Refund order:
1. E9...001 (PSP B) → R$ 300
2. E9...002 (PSP C) → R$ 200
3. E9...005 (PSP E) → R$ 100
4. E9...007 (PSP F) → R$ 80

Result: All refunds processed successfully
9:00 AM - Status changes to COMPLETED

Event published:

Pix funds recovery status changed

{
  "domain": "pix-dict",
  "event_type": "funds_recoveries_status_changed",
  "data": {
    "funds_recovery_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "COMPLETED",
    "changed_at": "2025-11-18T09:00:00Z"
  }
}
9:15 AM - PSP A Notifies Client
SMS to Maria Santos:

Hello Maria,

Your funds recovery has been completed!

Fraud amount: R$ 800.00
Recovered amount: R$ 680.00
Recovery rate: 85%

The funds are already in your account.

PSP A - Anti-Fraud Team

AUTOMATIC flow summary

Timeline:
- Day 1 (9:45 AM): Creation + Automatic processing
- Day 1 (9:55 AM): Blocks sent (AWAITING_ANALYSIS)
- Day 9 (9:55 AM): Analysis completed (ANALYSED)
- Day 10 (8:35 AM): Refund initiated (REFUNDING)
- Day 10 (9:00 AM): Process completed (COMPLETED)

Result:
✅ R$ 680 recovered (85%)
❌ R$ 120 not recovered (15%)

AUTOMATIC flow advantages:
- Fast and automatic processing
- No need for human intervention
- Optimized DICT algorithm
- Ideal for high volume cases
- Shorter total processing time

Flow comparison

Side-by-side comparison

AspectINTERACTIVEAUTOMATIC
PSP controlTotalLimited
Setup time~1h (multiple graphs)~10 min (automatic)
TRACKED status✅ Yes❌ No (skips directly)
Multiple graphs✅ Allowed❌ Only 1 (internal)
PrioritizationManual or algorithmAlgorithm only
Graph visibility✅ Complete❌ Not exposed
Experimentation✅ Yes❌ No
Total time9-10 days9-10 days
ComplexityHighLow
Ideal forComplex casesStandard cases
Recommended volumeLow/MediumHigh

State flow

INTERACTIVE:

CREATED → TRACKED → AWAITING_ANALYSIS → ANALYSED → REFUNDING → COMPLETED
   ↓         ↓
CANCELLED  CANCELLED

AUTOMATIC:

CREATED → AWAITING_ANALYSIS → ANALYSED → REFUNDING → COMPLETED
   ↓
CANCELLED

Endpoints called

INTERACTIVE:

NameURL
Create funds recoveryPOST /funds-recoveries (without graph parameters)
Create tracking graphPOST /funds-recoveries/{id}/tracking-graph (can repeat)
Get tracking graphGET /funds-recoveries/{id}/tracking-graph\ (query graph)
Block funds recoveryPOST /funds-recoveries/{id}/block\ (with transaction list)
Initiate refund funds recoveryPOST /funds-recoveries/{id}/refund

AUTOMATIC:

NameURL
Create funds recoveryPOST /funds-recoveries (with graph parameters)
Initiate refund funds recoveryPOST /funds-recoveries/{id}/refund

Events generated

Pix funds recovery status changed

INTERACTIVE:

1. funds_recoveries_status_changed (CREATED)
2. funds_recoveries_status_changed (TRACKED) - can repeat
3. funds_recoveries_status_changed (AWAITING_ANALYSIS)
4. funds_recoveries_status_changed (ANALYSED)
5. funds_recoveries_status_changed (REFUNDING)
6. funds_recoveries_status_changed (COMPLETED)

AUTOMATIC:

1. funds_recoveries_status_changed (CREATED)
2. funds_recoveries_status_changed (AWAITING_ANALYSIS)
3. funds_recoveries_status_changed (ANALYSED)
4. funds_recoveries_status_changed (REFUNDING)
5. funds_recoveries_status_changed (COMPLETED)

Updated about 1 hour ago