--- title: "Create funds recovery [beta]" method: POST path: "/v1/pix/funds-recoveries" tags: ["Funds recovery"] --- # Create funds recovery \[beta\] `POST /v1/pix/funds-recoveries` ## Request - Base URL: `https://sandbox.pismolabs.io/pix-dict` - URL: `https://sandbox.pismolabs.io/pix-dict/v1/pix/funds-recoveries` - Auth: HTTP bearer Creates and establishes a new funds recovery to track and block diverted funds in Pix fraud cases. The tracking follows the chain of subsequent transactions starting from the contested transaction. DICT manages the entire process. You define the initial `tracking_graph_parameters` and DICT executes tracking, prioritization, and blocking, then opens the infraction notifications that the receiving PSPs analyze. **Notes:** * The contested transaction must have occurred less than **80 days** ago. This limit is the same for an original transaction and for a reversal transaction. * Only the payer **of the contested transaction** can create funds recovery. When contesting a reversal, the payer is the participant that sent the reversal — that is, the PSP of the party who received the original transaction. * `root_transaction_id` takes the **end-to-end ID** of the original transaction, or the **reversal end-to-end ID** when contesting a reversal. * A reversal issued to settle an **operational flaw cannot be contested**. If the refund behind the reversal had `refund_reason` of `OPERATIONAL_FLAW`, DICT rejects the funds recovery as ineligible. This is the only restriction on contesting a reversal. * When contesting a reversal, `situation_type` must be `OTHER`, which makes `report_details` mandatory. * Recipient PSPs have **7 calendar days** to analyze infraction notifications * Refund must be initiated within **72 hours** after analysis completion * Once refunding starts, the process **cannot be cancelled** **Terminology:** the DICT operating manual refers to an original transaction as `pacs.008` and to a reversal transaction as `pacs.004`. Thie endpoint generates a [Pix funds recovery status changed](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) event. For more information refer to [Pix funds recovery](doc:pix-funds-recovery). ## Request body - CreateFundsRecoveryRequest: Create funds recovery request - `root_transaction_id` string, required: Identifier of the contested transaction, 32 characters. * Contesting an original transaction — its **end-to-end ID**, which begins with `E`. * Contesting a reversal transaction — its **reversal end-to-end ID**, which begins with `D`. - `situation_type` 'SCAM' | 'ACCOUNT_TAKEOVER' | 'COERCION' | 'FRAUDULENT_ACCESS' | 'OTHER' | 'UNKNOWN', required: Situation type: * `SCAM` - Scam/fraud through social engineering * `ACCOUNT_TAKEOVER` - Unauthorized transaction without digital authentication * `COERCION` - Coercion crime (kidnapping, extortion) * `FRAUDULENT_ACCESS` - Fraudulent access and authorization (phishing, stolen password) | * `OTHER` - Other cases. This option **REQUIRES** you pass `report_details`. * `UNKNOWN` - Unknown state When the contested transaction is a reversal, the DICT operating manual requires `situation_type` to be `OTHER`, which in turn makes `report_details` mandatory. - `contact_information` ContactInformation, required - `phone` string, required: Contact phone number - `email` string, required: Contact email - `report_details` string: Details about report - `tracking_graph_parameters` TrackingGraphParameters: Graph parameters. Higher values for `min_transaction_amount` and lower values for `max_transactions`,`max_hops`, and `hop_window` generate smaller and faster graphs. The opposite generates larger and more complete graphs. - `min_transaction_amount` number, required: Minimum amount in Brazilian reals to include transaction in tracking. - `max_transactions` integer, required: Maximum number of transactions to track - `hop_window` string, required: The window duration between transactions * `PT30M` - 30 minutes * `PT45M` - 45 minutes * `PT1H` - 1 hour * `PT2H` - 2 hours - `max_hops` integer, required: Maximum tracking depth, in graph layers. ## Response `201` Created - synchronous success - CreateFundsRecoveryResponse: Create funds recovery request - `id` string: Funds recovery identifier. Returned from the [Create funds recovery](ref:post-create-funds-recovery) endpoint. - `status` 'CREATED' | 'AWAITING_ANALYSIS' | 'TRACKED' | 'ANALYSED' | 'REFUNDING' | 'COMPLETED' | 'CANCELLED': Funds recovery status: * `CREATED` - Recovery created, awaiting next action. * `TRACKED` - The transaction tracking graph has been created. * `AWAITING_ANALYSIS` - Awaiting analysis from receiver PSPs (deadline: 7 calendar days). * `ANALYSED` - Analysis completed, ready for refund. * `REFUNDING` - Refund process in progress. * `COMPLETED` - Recovery successfully completed. * `CANCELLED` - Recovery cancelled. - `root_transaction_id` string: Identifier of the contested transaction, 32 characters. * Contesting an original transaction — its **end-to-end ID**, which begins with `E`. * Contesting a reversal transaction — its **reversal end-to-end ID**, which begins with `D`. - `situation_type` 'SCAM' | 'ACCOUNT_TAKEOVER' | 'COERCION' | 'FRAUDULENT_ACCESS' | 'OTHER' | 'UNKNOWN': Situation type: * `SCAM` - Scam/fraud through social engineering * `ACCOUNT_TAKEOVER` - Unauthorized transaction without digital authentication * `COERCION` - Coercion crime (kidnapping, extortion) * `FRAUDULENT_ACCESS` - Fraudulent access and authorization (phishing, stolen password) | * `OTHER` - Other cases. This option **REQUIRES** you pass `report_details`. * `UNKNOWN` - Unknown state When the contested transaction is a reversal, the DICT operating manual requires `situation_type` to be `OTHER`, which in turn makes `report_details` mandatory. - `reporter_participant` string: Reporter participant ID - `contact_information` ContactInformation - `phone` string, required: Contact phone number - `email` string, required: Contact email - `report_details` string: Details about report - `created_at` string, date-time: Creation datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. - `updated_at` string, date-time: Updated datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. ## Other responses - `202`: Funds recovery creation continues asynchronously - `400`: Invalid request data - `404`: Transaction not found. This response is also returned when the transaction **does** exist in Pismo but the requesting organization is not the payer of it. The root transaction is resolved from the leg where the organization is the payer: a `PIX-OUT` for an original transaction, or a `PIX-IN` of type `PIX-IN-REVERSAL` for a reversal. A plain `PIX-IN` is rejected, since the party that received a transaction is not its payer. - `409`: Recovery already exists - `422`: Transaction is not eligible for funds recovery - `504`: Timeout --- [API](https://skmtc.dev/pismo/apis/instant-payments-pix-management.md) - [All operations](https://skmtc.dev/pismo/apis/instant-payments-pix-management/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/instant-payments-pix-management/revisions/eb540c289547?raw)