---
updatedAt: 2026-05-29T16:44:17.000Z
---

Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.

# Cancel installments payment

Cancel an existing installments payment. 

This endpoint generates the [Authorization created](https://developers.pismo.io/events/docs/authorization-authorization-event-1) event.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Core platform - Payment methods",
    "version": "1.0.0",
    "description": "API to handle payments.",
    "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"
    },
    {
      "url": "https://gw-pci.pismolabs.io",
      "description": "Sandbox PCI API server for testing"
    }
  ],
  "tags": [
    {
      "name": "Installments payments",
      "description": "APIs to manage installments payments."
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "AcceptedResponse": {
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code",
            "example": "EP2P0010",
            "deprecated": true
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "EP2P0010"
          },
          "message": {
            "type": "string",
            "description": "Message that the request is processing and will finish asynchronously.",
            "example": "Request is processing and will finish asynchronously"
          }
        },
        "title": "AcceptedResponse",
        "description": "Object indicating request could not finish synchronously but will be completed later"
      },
      "Authorization": {
        "properties": {
          "authorization_id": {
            "type": "integer",
            "format": "int64",
            "description": "Generated authorization ID.",
            "example": 16397984
          },
          "response_code": {
            "type": "string",
            "description": "Operation status code.",
            "example": "00"
          },
          "amount": {
            "description": "Credited or debited amount.",
            "type": "number",
            "format": "float",
            "example": 12.13
          },
          "date": {
            "type": "string",
            "description": "Authorization date/time in UTC-0 (RFC3339) format.",
            "format": "date-time",
            "example": "2020-01-02T15:14:00.218Z"
          }
        },
        "description": "Authorization object.",
        "title": "Authorization"
      },
      "ErrorModel": {
        "description": "API generic returned error.",
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code.",
            "deprecated": true
          },
          "code": {
            "type": "string",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "description": "Error description."
          }
        },
        "title": "ErrorModel"
      },
      "CancelInstallmentsPaymentPayload": {
        "title": "CancelInstallmentsPaymentPayload",
        "type": "object",
        "description": "Request object for `POST v1/payments/installments/cancel` (Cancel Installments payment).",
        "required": [
          "account_id"
        ],
        "properties": {
          "tracking_id": {
            "type": "string",
            "minLength": 36,
            "maxLength": 50,
            "description": "Unique tracking ID of the installments operation. If you don't provide one, the Pismo platform generates it randomly.",
            "example": "be68db6e-8da0-4761-8632-6a51857bd123",
            "pattern": "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
          },
          "original_tracking_id": {
            "type": "string",
            "minLength": 36,
            "maxLength": 50,
            "description": "Unique tracking ID of the original installments operation. You have to provide either `original_tracking_id` or `original_authorization_id` to execute this request.",
            "example": "be68db6e-8da0-4761-8632-6a51857bd123",
            "pattern": "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
          },
          "original_authorization_id": {
            "description": "Authorization ID of the original installments operation. You have to provide either `original_authorization_id` or `original_tracking_id` to execute this request.",
            "type": "integer",
            "format": "int64",
            "example": 15301234
          },
          "account_id": {
            "type": "integer",
            "description": "Pismo account ID.",
            "example": 101
          },
          "amount": {
            "description": "Total amount to be cancelled.",
            "type": "number",
            "format": "float",
            "example": 12.13
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "InstallmentsPaymentResponse": {
        "title": "InstallmentsPaymentResponse",
        "properties": {
          "authorization_id": {
            "description": "Generated authorization ID.",
            "type": "integer",
            "format": "int64",
            "example": 15301234
          },
          "event_date": {
            "description": "Date and time of the authorization, in UTC-0 (RFC3339) format.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-02T15:14:00.218Z"
          },
          "tracking_id": {
            "description": "Unique 36-character identifier for the installments payment. If you didn't provide an identifier, then the Pismo platform automatically generates and includes one in the response.",
            "type": "string",
            "example": "82766158-514c-42f0-87e2-1bb3250c6dee"
          }
        },
        "description": "Successful response object from `v1/payments/installments` (installments payment)."
      },
      "InstallmentsPaymentResponseTrackingIdAlreadyInUseResponse": {
        "properties": {
          "authorization_id": {
            "description": "Generated authorization ID.",
            "type": "integer",
            "example": 15301234
          },
          "event_date": {
            "description": "Date and time of the authorization, in UTC-0 (RFC3339) format.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-02T15:14:00.218Z"
          },
          "tracking_id": {
            "description": "Unique 36-character identifier for the installments payment. If you didn't provide an identifier, then the Pismo platform automatically generates and includes one in the response.",
            "type": "string",
            "example": "82766158-514c-42f0-87e2-1bb3250c6dee"
          }
        }
      },
      "TrackingIdAlreadyInUseResponse": {
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code.",
            "example": "WP2P0010",
            "deprecated": true
          },
          "code": {
            "type": "string",
            "description": "Error code.",
            "example": "WP2P0010"
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "example": "Tracking ID already in use"
          },
          "authorizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Authorization"
            }
          }
        },
        "title": "TrackingIdAlreadyInUseResponse",
        "description": "Tracking ID already in use error object."
      },
      "Metadata": {
        "type": "object",
        "description": "This optional user-defined key-value object field can be used with external operations to provide additional context or supplementary custom information for the operation. \n\nThe Pismo platform does not perform any validation or processing on this field but passes this object to the acquirer in transactions involving calls to the acquirer and sends it in the events related to the stream of data produced at the end of the request.\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n",
        "example": {
          "any-key": "any-value"
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/payments/v1/payments/installments/cancel": {
      "post": {
        "operationId": "post-payments-v1-installments-cancel",
        "summary": "Cancel installments payment",
        "description": "Cancel an existing installments payment. \n\nThis endpoint generates the [Authorization created](https://developers.pismo.io/events/docs/authorization-authorization-event-1) event.\n",
        "tags": [
          "Installments payments"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "minLength": 39,
              "maxLength": 39,
              "type": "string",
              "example": "TN-c0e4c660-9059-404c-ab22-761aa431766c",
              "pattern": "TN\\-[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"
            },
            "in": "header",
            "name": "x-tenant",
            "description": "Unique Org ID.",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "header",
            "name": "x-account-id",
            "description": "Optional account ID."
          },
          {
            "schema": {
              "type": "string",
              "example": "true"
            },
            "in": "header",
            "name": "x-skip-timeline",
            "description": "If set to `true`, this will prevent the generation of timeline events in the customer timeline."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelInstallmentsPaymentPayload"
              },
              "examples": {
                "post-v1-payments-cancel-installments-example": {
                  "value": "{\n\t\"amount\": 22.30,\n\t\"account_id\": 1,\n\t\"tracking_id\": \"c737895c-8159-4c0c-a92a-a4f8600bff37\",\n  \"metadata\": {\n      \"my-custom-key\": \"my-custom-info\"\n  },\n  \"original_tracking_id\": \"4bffde04-81f1-42ba-bb00-519daa88d2e6\"\n}"
                },
                "post-v1-payments-cancel-installments-authorization-id-example": {
                  "value": "{\n\t\"amount\": 22.30,\n\t\"account_id\": 1,\n\t\"tracking_id\": \"c737895c-8159-4c0c-a92a-a4f8600bff37\",\n  \"metadata\": {\n      \"my-custom-key\": \"my-custom-info\"\n  },\n  \"original_authorization_id\": 15301234\n}"
                },
                "post-v1-payments-cancel-installments-partial-cancellation-example": {
                  "value": "{\n\t\"amount\": 10.30,\n\t\"account_id\": 1,\n\t\"tracking_id\": \"c737895c-8159-4c0c-a92a-a4f8600bff37\",\n  \"metadata\": {\n      \"my-custom-key\": \"my-custom-info\"\n  },\n  \"original_tracking_id\": \"cdde684c-824d-4234-9d00-7a47e41b67cd\"\n}"
                },
                "post-v1-payments-cancel-installments-without-amount-cancellation-example": {
                  "value": "{\n\t\"account_id\": 1,\n\t\"tracking_id\": \"c737895c-8159-4c0c-a92a-a4f8600bff37\",\n  \"metadata\": {\n      \"my-custom-key\": \"my-custom-info\"\n  },\n  \"original_tracking_id\": \"cdde684c-824d-4234-9d00-7a47e41b67cd\"\n}"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallmentsPaymentResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Invalid payload": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Invalid payload"
                    }
                  },
                  "Invalid amount": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "The amount must have a maximum of two decimal places."
                    }
                  },
                  "Invalid account program type": {
                    "value": {
                      "error_code": "WP2P0025",
                      "code": "WP2P0025",
                      "message": "Debit program accounts are invalid for installments payments."
                    }
                  },
                  "Invalid credit processing code": {
                    "value": {
                      "error_code": "WP2P0006",
                      "code": "WP2P0006",
                      "message": "Invalid credit processing code."
                    }
                  },
                  "OriginalAuthorizationID or OriginalTrackingID missing": {
                    "value": {
                      "error_code": "WP2P0080",
                      "code": "WP2P0080",
                      "message": "Either the Original Authorization ID or Original Tracking ID is required."
                    }
                  },
                  "Cancellation amount exceeds original amount": {
                    "value": {
                      "error_code": "EP2P0005",
                      "code": "EP2P0005",
                      "message": "The amount passed {{.amount}} is greater than the current balance 0.00."
                    }
                  },
                  "Limit of two decimal places": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "The amount must have a maximum of two decimal places."
                    }
                  },
                  "Exceed amount limit": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "A maximum of 20 digits, including two decimals, is allowed for the amount field."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Account not found": {
                    "value": {
                      "error_code": "WP2P0023",
                      "code": "WP2P0023",
                      "message": "Accounts not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TrackingIdAlreadyInUseResponse"
                    },
                    {
                      "$ref": "#/components/schemas/InstallmentsPaymentResponseTrackingIdAlreadyInUseResponse"
                    }
                  ]
                },
                "examples": {
                  "Tracking ID is already in use by an ongoing request": {
                    "value": {
                      "error_code": "WP2P0010",
                      "code": "WP2P0010",
                      "message": "Tracking ID is already in use."
                    }
                  },
                  "Tracking ID has been already used": {
                    "value": {
                      "authorization_id": 16397984,
                      "date": "2020-01-02T15:14:00.218Z",
                      "tracking_id": "82766158-514c-42f0-87e2-1bb3250c6dee"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Authorized account is different from request": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Authorized account is different from the request"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Unexpected Error": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Unexpected error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```