--- updatedAt: 2026-04-23T18:12:51.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Cancel funds recovery [beta] Cancel funds recovery Statuses that allow cancellation: | Status | Can Cancel? | Note | |--------|-------------|------| | `CREATED` | Yes | Before any processing | | `TRACKED` | Yes | After graph creation | | `AWAITING_ANALYSIS` | Yes | During analysis period (7 days) | | `ANALYSED` | Yes | After analysis completed, before refund | | `REFUNDING` | No | Refunds already started - irreversible process | | `COMPLETED` | No | Process already finished | When a recovery is cancelled: * Status changes to `CANCELLED` * All linked infraction notifications are automatically cancelled * Receiver PSPs must unblock the resources that were blocked * Tracking graph remains available for audit * Process cannot be undone (but new recovery can be created) Thie endpoint generates a [Pix funds recovery status changed](https://developers.pismo.io/events/docs/pix-dict-funds-recoveries-status-change-1) event. # 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" } }, "parameters": { "FundsRecoveryIdPath2": { "name": "funds_recovery_id", "in": "path", "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n", "schema": { "type": "string" }, "required": true, "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D" } }, "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" } } }, "CancelFundsRecoveryResponse": { "type": "object", "description": "Initiate funds recovery response", "properties": { "id": { "$ref": "#/components/schemas/FundsRecoveryId" }, "status": { "$ref": "#/components/schemas/FundsRecoveryStatus" }, "updated_at": { "$ref": "#/components/schemas/UpdatedDatetime" } } }, "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" } } }, "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/{funds_recovery_id}/cancel": { "post": { "summary": "Cancel funds recovery [beta]", "description": "Cancel funds recovery \n\nStatuses that allow cancellation:\n\n | Status | Can Cancel? | Note |\n |--------|-------------|------|\n | `CREATED` | Yes | Before any processing |\n | `TRACKED` | Yes | After graph creation |\n | `AWAITING_ANALYSIS` | Yes | During analysis period (7 days) |\n | `ANALYSED` | Yes | After analysis completed, before refund |\n | `REFUNDING` | No | Refunds already started - irreversible process |\n | `COMPLETED` | No | Process already finished |\n\nWhen a recovery is cancelled:\n * Status changes to `CANCELLED`\n * All linked infraction notifications are automatically cancelled\n * Receiver PSPs must unblock the resources that were blocked\n * Tracking graph remains available for audit\n * Process cannot be undone (but new recovery can be created)\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", "operationId": "post-cancel-funds-recovery", "tags": [ "Funds recovery" ], "parameters": [ { "$ref": "#/components/parameters/FundsRecoveryIdPath2" } ], "responses": { "200": { "description": "OK - synchronous success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFundsRecoveryResponse" } } } }, "202": { "description": "Ok - Asynchronous success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncResponse" }, "examples": { "Asynchrnous success": { "value": { "code": "EPDA0000", "message": "Refund funds recovery flow will continue asynchronously" } } } } } }, "400": { "description": "Invalid funds recovery ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Invalid funds recovery ID": { "value": { "code": "EPDA0000", "message": "Invalid funds recovery ID format" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Funds recovery not found": { "value": { "code": "EPDA0000", "message": "Funds recovery not found" } } } } } }, "409": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Status does not allow cancellation": { "value": { "code": "EPDA0000", "message": "Cannot cancel funds recovery in current status" } } } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "DICT timeout": { "value": { "code": "EPDA0000", "message": "Timeout communicating with DICT" } } } } } } } } } } } ```