# Cancel payment

Cancel an existing payment operation.

NOTE:
- This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.

This endpoint generates the following events:
- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)
- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)
- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)

Refer to [Data and reporting](doc:data-reporting-overview) for more information on events and setting up event notifications.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Banking - Transaction banking",
    "version": "0.9.0",
    "description": "Transaction banking API",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Payments",
      "description": "Payment endpoints supporting external accounts"
    }
  ],
  "components": {
    "schemas": {
      "CancellationMethod": {
        "type": "string",
        "enum": [
          "INSTANT",
          "ORIGINAL_DATES"
        ],
        "description": "Define the cancellation method used to determine which dates the cancellation will impact the account balance.\n\n<br>\n- `INSTANT` (default): Cancels the payment using the current business date.\n- `ORIGINAL_DATES`: Cancels the payment using the original payment dates.\n",
        "default": "INSTANT",
        "example": "INSTANT"
      },
      "CancelPaymentV2Request": {
        "title": "CancelPaymentV2Request",
        "type": "object",
        "required": [
          "original_tracking_id",
          "tracking_id"
        ],
        "properties": {
          "original_tracking_id": {
            "$ref": "#/components/schemas/OriginalTrackingID"
          },
          "tracking_id": {
            "$ref": "#/components/schemas/TrackingID"
          },
          "cancellation_method": {
            "$ref": "#/components/schemas/CancellationMethod"
          },
          "skip_account_date_validation": {
            "$ref": "#/components/schemas/SkipAccountDateValidation"
          },
          "metadata": {
            "$ref": "#/components/schemas/ConfirmPaymentMetadata"
          }
        }
      },
      "ConfirmPaymentMetadata": {
        "type": "object",
        "description": "Key-value pairs containing data intended for storage in the Pismo system."
      },
      "ErrorCode": {
        "description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 12,
        "example": "WPMT0017"
      },
      "ErrorMessage": {
        "description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 1000,
        "example": "Invalid JSON payload received: Error unmarshalling request"
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "$ref": "#/components/schemas/ErrorMessage"
          }
        }
      },
      "EventDatetime": {
        "type": "string",
        "format": "date-time",
        "minLength": 1,
        "maxLength": 30,
        "description": "Event date and time displayed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br>\n`minLength: 1`\n`maxLength: 30`\n",
        "example": "2023-04-27T12:01:24Z"
      },
      "OriginalTrackingID": {
        "type": "string",
        "description": "Tracking ID for the original operation.",
        "maxLength": 43,
        "example": "249fbd1c-cfcd-48aa-8bcb-1ffe3a5f7978"
      },
      "SettlementV2Response": {
        "title": "SettlementV2Response",
        "type": "object",
        "properties": {
          "original_tracking_id": {
            "$ref": "#/components/schemas/OriginalTrackingID"
          },
          "tracking_id": {
            "$ref": "#/components/schemas/TrackingID"
          },
          "event_datetime": {
            "$ref": "#/components/schemas/EventDatetime"
          }
        }
      },
      "SkipAccountDateValidation": {
        "type": "boolean",
        "description": "If `FALSE`, the `payment_datetime` is validated against the account creation date and time. If `TRUE`, the validation is skipped.",
        "default": false,
        "example": false
      },
      "TrackingID": {
        "type": "string",
        "description": "A unique payment tracking number provided by the client. If an existing `tracking_id` already exists in the system, the API returns a `409` error.\n\nThis field is:\n  - Unique within the Organization.\n  - Immutable — It can't be updated.\n  - Not recyclable — You can't reuse a `tracking_id`.\n",
        "minLength": 1,
        "maxLength": 43,
        "example": "0a50c88a-ade8-4bcc-a639-9a0b0f11e244"
      }
    },
    "responses": {
      "403Forbidden": {
        "description": "The request has been lost"
      },
      "500InternalServer": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "Generic internal error": {
                "value": {
                  "code": "ECMN9999",
                  "message": "Internal error"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/corporate/v2/payments/cancel": {
      "post": {
        "summary": "Cancel payment",
        "description": "Cancel an existing payment operation.\n\nNOTE:\n- This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.\n\nThis endpoint generates the following events:\n- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)\n- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)\n- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)\n\nRefer to [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) for more information on events and setting up event notifications.",
        "parameters": [],
        "operationId": "corporate-v2-post-cancel-payments",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "description": "Request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelPaymentV2Request"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementV2Response"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Operations blocked for account": {
                    "description": "This error occurs when there's an operations block for this account",
                    "value": {
                      "code": "WOBK0007",
                      "message": "Operations blocked for account"
                    }
                  },
                  "Invalid JSON payload": {
                    "value": {
                      "code": "WPMT0017",
                      "message": "Invalid JSON payload received: Error unmarshalling request"
                    }
                  },
                  "Tracking ID exceed size": {
                    "value": {
                      "code": "WPMT0018",
                      "message": "tracking_id must be a maximum of 43 characters in length"
                    }
                  },
                  "Original Tracking ID exceed size": {
                    "value": {
                      "code": "WPMT0018",
                      "message": "original_tracking_id must be a maximum of 43 characters in length"
                    }
                  },
                  "Tracking ID required": {
                    "value": {
                      "code": "WPMT0018",
                      "message": "tracking_id is a required field"
                    }
                  },
                  "Original Tracking ID required": {
                    "value": {
                      "code": "WPMT0018",
                      "message": "original_tracking_id is a required field"
                    }
                  },
                  "Payment date before account creation date": {
                    "value": {
                      "code": "WPMT0001",
                      "message": "The payment date cannot be earlier than the account creation date"
                    }
                  },
                  "Payment date before account migration date": {
                    "value": {
                      "code": "WPMT0061",
                      "message": "The payment date cannot be earlier than the account migration date"
                    }
                  },
                  "Holiday error": {
                    "value": {
                      "code": "WPMT0003",
                      "message": "Cannot post transaction on holidays"
                    }
                  },
                  "Weekend error": {
                    "value": {
                      "code": "WPMT0004",
                      "message": "Cannot post transaction on weekends"
                    }
                  },
                  "Invalid business date for the current business day cycle": {
                    "value": {
                      "code": "WPMT0028",
                      "message": "Invalid business date for the current business day cycle"
                    }
                  },
                  "Transaction owned by another account": {
                    "value": {
                      "code": "WPMT0038",
                      "message": "transaction is owned by another account"
                    }
                  },
                  "Transaction cannot be confirmed": {
                    "value": {
                      "code": "WPMT0039",
                      "message": "transaction cannot be confirmed"
                    }
                  },
                  "Transaction cannot be cancelled": {
                    "value": {
                      "code": "WPMT0040",
                      "message": "transaction cannot be canceled"
                    }
                  },
                  "Earmark internal operation cannot be cancelled": {
                    "value": {
                      "code": "WPMT0041",
                      "message": "earmark internal_operation cannot be canceled"
                    }
                  },
                  "Back business dating disabled": {
                    "description": "This error occurs when the back‑business‑date payment feature is disabled through [Past business date toggle](https://developers.pismo.io/pismo-docs/reference/put-back-business-toggle).",
                    "value": {
                      "code": "WPMT0044",
                      "message": "Back business dating is disabled"
                    }
                  },
                  "Back payment datetime above limit": {
                    "value": {
                      "code": "WPMT0046",
                      "message": "The maximum retroactive payment datetime allowed is <days_limit> days"
                    }
                  },
                  "Transfer must be sent by debit account": {
                    "description": "This error occurs when the transfer cancellation request originates from a credit leg account.",
                    "value": {
                      "code": "WPMT0049",
                      "message": "Transfer operations must be sent by the debit account"
                    }
                  },
                  "Cannot instantly cancel when original business date is after the current date": {
                    "value": {
                      "code": "WPMT0057",
                      "message": "Cannot instantly cancel when original business date is after the current date"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Unauthorized account": {
                    "value": {
                      "code": "WCAC0001",
                      "message": "Account not authorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Original Tracking ID not found": {
                    "value": {
                      "code": "WPMT0037",
                      "message": "original_tracking_id not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Tracking ID already in use": {
                    "description": "This error occurs when the client sends a duplicate tracking ID for the payment",
                    "value": {
                      "code": "WPMT0007",
                      "message": "tracking_id is already in use",
                      "data": {
                        "tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
                        "event_datetime": "2025-02-05T21:46:06Z"
                      }
                    }
                  },
                  "Tracking ID already in use by another account": {
                    "description": "This error occurs when the client sends a duplicate tracking ID that is already used by another account.",
                    "value": {
                      "code": "WPMT0052",
                      "message": "tracking_id is already in use"
                    }
                  }
                }
              }
            }
          },
          "423": {
            "description": "Locked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Transaction using this tracking ID in progress": {
                    "description": "This error occurs when multiple payment requests with the same `tracking_id` are made simultaneously",
                    "value": {
                      "code": "WPMT0047",
                      "message": "transaction using this tracking_id is in progress, please try again later"
                    }
                  },
                  "Transaction using this original tracking ID in progress": {
                    "description": "This error occurs when multiple payment requests with the same `original_tracking_id` are made simultaneously.",
                    "value": {
                      "code": "WPMT0048",
                      "message": "transaction using this original_tracking_id is in progress, please try again later"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        }
      }
    }
  }
}
```