--- updatedAt: 2026-04-24T22:22:58.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Pix funds recovery [beta] This guide details the process for recovering funds in Pix. There is one flow you can use. * **`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. # Flow example
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](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) ```bash POST /v1/pix/funds-recoveries { "flow_type": "AUTOMATED", "root_transaction_id": "E98765432109876543210987654321001", "situation_type": "SCAM", "contact_information": { "email": "fraud@pspa.com.br", "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)**: ```json { "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](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) ```json { "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: ```json { "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](https://developers.pismo.io/pismo-docs/reference/post-get-funds-recovery) ```bash GET /v1/pix/funds-recoveries/650e8400-e29b-41d4-a716-446655440001 ``` **Response**: ```json { "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](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) ```json { "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](https://developers.pismo.io/pismo-docs/reference/get-v2-pix-infraction) ```bash 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](https://developers.pismo.io/pismo-docs/reference/post-refund-recovery) ```bash POST /v1/pix/funds-recoveries/650e8400-e29b-41d4-a716-446655440001/refund ``` **Response (202 Accepted)**: ```json { "code": "EPDA0000", "message": "Refund funds recovery flow will continue asynchronously" } ``` ##### 8:35 AM - Status Changes to REFUNDING **Event published**: [Pix funds recovery status changed](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) ```json { "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](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) ```json { "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 aspects | Aspect | AUTOMATIC | | ---------------------- | --------------------- | | **PSP control** | Limited | | **Setup time** | \~10 min (automatic) | | **`TRACKED`status** | ❌ No (skips directly) | | **Multiple graphs** | ❌ Only 1 (internal) | | **Prioritization** | Algorithm only | | **Graph visibility** | ❌ Not exposed | | **Experimentation** | ❌ No | | **Total time** | 9-10 days | | **Complexity** | Low | | **Ideal for** | Standard cases | | **Recommended volume** | High | ## State flow **`AUTOMATIC`**: ``` CREATED → AWAITING_ANALYSIS → ANALYSED → REFUNDING → COMPLETED ↓ CANCELLED ``` # Endpoints called **`AUTOMATIC`**: | Name | URL | | ---------------------------------------------------------- | ------------------------------------------------ | | [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) | `POST /funds-recoveries` (with graph parameters) | | [Initiate refund funds recovery](https://developers.pismo.io/pismo-docs/reference/post-refund-recovery) | `POST /funds-recoveries/{id}/refund` | # Events generated [Pix funds recovery status changed](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1)