--- updatedAt: 2026-04-23T18:12:51.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Create funds recovery [beta] 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). # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Instant payments - Pix management", "description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" }, "version": "0.0.1" }, "servers": [ { "url": "https://sandbox.pismolabs.io/pix-dict", "description": "Sandbox API server for testing." } ], "tags": [ { "name": "Funds recovery" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "AsyncResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Response code", "example": "EPDA0000" }, "message": { "type": "string", "description": "Descriptive message about the asynchronous operation", "example": "Operation will continue asynchronously. Monitor events for completion" } } }, "ContactInformation": { "type": "object", "required": [ "phone", "email" ], "properties": { "phone": { "type": "string", "maxLength": 16, "description": "Contact phone number", "example": "551154874551" }, "email": { "type": "string", "description": "Contact email", "maxLength": 77, "example": "polly_ester@email.com" } } }, "CreateFundsRecoveryRequest": { "type": "object", "description": "Create funds recovery request", "required": [ "root_transaction_id", "situation_type", "contact_information" ], "properties": { "root_transaction_id": { "$ref": "#/components/schemas/RootTransactionID" }, "situation_type": { "$ref": "#/components/schemas/SituationType" }, "contact_information": { "$ref": "#/components/schemas/ContactInformation" }, "report_details": { "$ref": "#/components/schemas/ReportDetails2" }, "tracking_graph_parameters": { "$ref": "#/components/schemas/TrackingGraphParameters" } } }, "CreateFundsRecoveryResponse": { "type": "object", "description": "Create funds recovery request", "properties": { "id": { "$ref": "#/components/schemas/FundsRecoveryId" }, "status": { "$ref": "#/components/schemas/FundsRecoveryStatus" }, "root_transaction_id": { "$ref": "#/components/schemas/RootTransactionID" }, "situation_type": { "$ref": "#/components/schemas/SituationType" }, "reporter_participant": { "$ref": "#/components/schemas/ReporterParticipant" }, "contact_information": { "$ref": "#/components/schemas/ContactInformation" }, "report_details": { "$ref": "#/components/schemas/ReportDetails2" }, "created_at": { "$ref": "#/components/schemas/CreationDatetime" }, "updated_at": { "$ref": "#/components/schemas/UpdatedDatetime" } } }, "CreationDatetime": { "type": "string", "description": "Creation datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" }, "FundsRecoveryId": { "type": "string", "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n", "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D" }, "FundsRecoveryStatus": { "type": "string", "description": "Funds recovery status:\n* `CREATED` - Recovery created, awaiting next action.\n* `TRACKED` - The transaction tracking graph has been created.\n* `AWAITING_ANALYSIS` - Awaiting analysis from receiver PSPs (deadline: 7 calendar days).\n* `ANALYSED` - Analysis completed, ready for refund.\n* `REFUNDING` - Refund process in progress.\n* `COMPLETED` - Recovery successfully completed.\n* `CANCELLED` - Recovery cancelled.\n", "enum": [ "CREATED", "AWAITING_ANALYSIS", "TRACKED", "ANALYSED", "REFUNDING", "COMPLETED", "CANCELLED" ], "example": "CREATED" }, "message.DetailMessage": { "type": "object", "properties": { "external": { "type": "array", "items": { "$ref": "#/components/schemas/message.ExternalMessage" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/message.ParameterMessage" } }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/message.PayloadMessage" } } } }, "message.ExternalMessage": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "PBE315" }, "message": { "type": "string", "description": "Error message", "example": "Generic error" } } }, "message.Message": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "EPDA0001" }, "details": { "$ref": "#/components/schemas/message.DetailMessage" }, "message": { "type": "string", "description": "Error message", "example": "User not found" } } }, "message.ParameterMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Parameter in error", "example": "query parameter" }, "message": { "type": "string", "description": "Error message", "example": "Generic error" } } }, "message.PayloadMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Field in error", "example": "Entity.field" }, "message": { "type": "string", "description": "Error messsage", "example": "Generic error" } } }, "ReportDetails2": { "type": "string", "description": "Details about report", "maxLength": 500, "example": "Details that can help the receiving participant to analyze the suspected violation" }, "ReporterParticipant": { "type": "string", "description": "Reporter participant ID", "example": "12345678" }, "RootTransactionID": { "type": "string", "description": "Identifier of the contested transaction, 32 characters.\n\n * Contesting an original transaction — its **end-to-end ID**, which begins with `E`.\n * Contesting a reversal transaction — its **reversal end-to-end ID**, which begins with `D`.\n", "minLength": 32, "maxLength": 32, "example": "E1234567890123456789012345678901" }, "SituationType": { "type": "string", "description": "Situation type:\n * `SCAM` - Scam/fraud through social engineering\n * `ACCOUNT_TAKEOVER` - Unauthorized transaction without digital authentication\n * `COERCION` - Coercion crime (kidnapping, extortion)\n * `FRAUDULENT_ACCESS` - Fraudulent access and authorization (phishing, stolen password) |\n * `OTHER` - Other cases. This option **REQUIRES** you pass `report_details`.\n * `UNKNOWN` - Unknown state\n\nWhen the contested transaction is a reversal, the DICT operating manual requires\n`situation_type` to be `OTHER`, which in turn makes `report_details` mandatory.\n", "enum": [ "SCAM", "ACCOUNT_TAKEOVER", "COERCION", "FRAUDULENT_ACCESS", "OTHER", "UNKNOWN" ] }, "TrackingGraphParameters": { "type": "object", "description": "Graph parameters. \n\nHigher 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.\n", "required": [ "min_transaction_amount", "max_transactions", "hop_window", "max_hops" ], "properties": { "min_transaction_amount": { "type": "number", "description": "Minimum amount in Brazilian reals to include transaction in tracking." }, "max_transactions": { "type": "integer", "description": "Maximum number of transactions to track" }, "hop_window": { "type": "string", "description": "The window duration between transactions\n\n * `PT30M` - 30 minutes\n * `PT45M` - 45 minutes\n * `PT1H` - 1 hour\n * `PT2H` - 2 hours\n \n \n", "example": "PT2H" }, "max_hops": { "type": "integer", "description": "Maximum tracking depth, in graph layers.", "minimum": 1, "maximum": 10, "default": 2, "example": 5 } } }, "UpdatedDatetime": { "type": "string", "description": "Updated datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" } } }, "security": [ { "BearerAuth": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true }, "paths": { "/v1/pix/funds-recoveries": { "post": { "summary": "Create funds recovery [beta]", "description": "Creates and establishes a new funds recovery to track and block diverted funds in Pix fraud cases. \n\nThe tracking follows the chain of subsequent transactions starting from the contested transaction.\n\nDICT manages the entire process. You define the initial `tracking_graph_parameters` and DICT\nexecutes tracking, prioritization, and blocking, then opens the infraction notifications that\nthe receiving PSPs analyze.\n\n**Notes:**\n\n * 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.\n * 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.\n * `root_transaction_id` takes the **end-to-end ID** of the original transaction, or the **reversal end-to-end ID** when contesting a reversal.\n * 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.\n * When contesting a reversal, `situation_type` must be `OTHER`, which makes `report_details` mandatory.\n * Recipient PSPs have **7 calendar days** to analyze infraction notifications\n * Refund must be initiated within **72 hours** after analysis completion\n * Once refunding starts, the process **cannot be cancelled**\n\n**Terminology:** the DICT operating manual refers to an original transaction as `pacs.008`\nand to a reversal transaction as `pacs.004`.\n\nThie endpoint generates a [Pix funds recovery status changed](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) event.\n\nFor more information refer to [Pix funds recovery](https://developers.pismo.io/pismo-docs/docs/pix-funds-recovery).\n", "operationId": "post-create-funds-recovery", "tags": [ "Funds recovery" ], "requestBody": { "description": "CheckRequest Body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFundsRecoveryRequest" }, "examples": { "originalTransaction": { "summary": "Contesting an original transaction", "value": { "root_transaction_id": "E9876543210987654321098765432109", "situation_type": "COERCION", "contact_information": { "email": "security@yourbank.com", "phone": "+5511988888888" }, "report_details": "Customer under coercion transferred R$ 10,000. Police report #12345/2025.", "tracking_graph_parameters": { "min_transaction_amount": 100, "max_transactions": 5, "hop_window": "PT2H", "max_hops": 5 } } }, "reversalTransaction": { "summary": "Contesting a reversal transaction", "value": { "root_transaction_id": "D2721411220260831204766547975600", "situation_type": "OTHER", "contact_information": { "email": "security@yourbank.com", "phone": "+5511988888888" }, "report_details": "Reversal of the root transaction of a funds recovery that was opened by the payer in order to defraud the payee.", "tracking_graph_parameters": { "min_transaction_amount": 100, "max_transactions": 5, "hop_window": "PT2H", "max_hops": 5 } } } } } } }, "responses": { "201": { "description": "Created - synchronous success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFundsRecoveryResponse" } } } }, "202": { "description": "Funds recovery creation continues asynchronously", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncResponse" }, "example": { "code": "EPDA0169", "message": "Funds recovery creation will continue asynchronously. Monitor events for completion." } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "invalidData": { "summary": "Invalid data", "value": { "code": "EPDA0001", "message": "Invalid request payload" } }, "accountDoesNotOwnTransaction": { "summary": "Account is not the payer of the contested transaction", "value": { "code": "EPDA0192", "message": "AccountID does not belong to the payer transaction" } } } } } }, "404": { "description": "Transaction not found.\n\nThis response is also returned when the transaction **does** exist in Pismo but the\nrequesting organization is not the payer of it. The root transaction is resolved from\nthe leg where the organization is the payer: a `PIX-OUT` for an original transaction,\nor a `PIX-IN` of type `PIX-IN-REVERSAL` for a reversal. A plain `PIX-IN` is rejected,\nsince the party that received a transaction is not its payer.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Transaction not found": { "value": { "code": "EPDA0079", "message": "Transaction not found" } } } } } }, "409": { "description": "Recovery already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Recovery already exists": { "value": { "code": "EPDA0190", "message": "An active funds recovery already exists for the given root transaction" } } } } } }, "422": { "description": "Transaction is not eligible for funds recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "transactionTooOld": { "summary": "Outside the 80-day eligibility window", "value": { "code": "EPDA0191", "message": "Transaction is outside the 80-day eligibility period for funds recovery" } }, "invalidTransactionStatus": { "summary": "Transaction is not settled", "value": { "code": "EPDA0192", "message": "Funds recovery cannot be initiated for this transaction due to its current status" } } } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Timeout": { "value": { "code": "EPDA0000", "message": "Timeout communicating with DICT" } } } } } } } } } } } ```