# Cancel transaction

Cancel a previously authorized transaction

Endpoint: POST /v2/transactions/{ratepay_transaction_id}/cancellations
Version: version 2
Security: Bearer Authentication

## Path parameters:

  - `ratepay_transaction_id` (string, required)
    ID of transaction to cancel. Get an overview of key identifiers used in payment API.

## Header parameters:

  - `Idempotency-Key` (string)
    ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See Idempotency for further details.

  - `Prefer` (string)
    According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.
    Enum: "return=representation"

  - `X-Partner` (string)
    The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.

## Request fields (application/json):

  - `gross_amount` (number, required)
    Amount to cancel given in currency of original transaction.
    Example: 67.6

  - `items` (array)
    List of cancelled items

  - `items.article_number` (string)
    The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.
    Example: "kitchen-utils-1"

  - `items.category` (string)
    Category for the item.
    Example: "household"

  - `items.description` (string)
    Description of the item.
    Example: "fruit knife with curved blade, 8 cm"

  - `items.gross_total_price` (number)
    Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity
    Example: 33.8

  - `items.gross_unit_discount` (number)
    Gross discount on one item after taxes. Needs to be a negative value.
    Example: -1.55

  - `items.gross_unit_price` (number, required)
    Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative.
    Example: 18.45

  - `items.name` (string, required)
    Name of the item.
    Example: "fruit knife"

  - `items.net_total_price` (number)
    Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity
    Example: 28.4

  - `items.net_unit_discount` (number)
    Net discount on one item before taxes. Needs to be a negative value.
    Example: -1.3

  - `items.net_unit_price` (number)
    Net value of one item before taxes.
    Example: 15.5

  - `items.quantity` (number, required)
    Ordered quantity of the item.
    Example: 2

  - `items.tax_rate` (number, required)
    Tax rate applicable for the item given in percent.
    Example: 19

  - `items.unit` (string)
    Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
    Example: "piece"

  - `partner_operation_id` (string)
    The unique ID generated by the partner or shop to identify an API operation. This ID can be displayed in settlement reports to allow relating settlement report items to API operations. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "cancel-id-1234"

  - `partner_shop_id` (string)
    The shop ID provided upfront by Ratepay or generated by the partner in PSP (payment service providers) scenarios. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.
    Example: "partner-shop-id-1"

  - `special_items` (array)
    List of cancelled special items, e.g. shipping costs or discounts.
    Example: [{"article_number":"SHIPPING_001","category":"shipping","description":"Standard shipping via DHL","gross_total_price":5.95,"gross_unit_price":5.95,"name":"Shipping costs","net_total_price":5,"net_unit_price":5,"quantity":1,"tax_rate":19,"unit":"shipment"}]

  - `special_items.type` (string)
    The special item type the buyer selected. RETURN_FEE type is applicable only for the REFUND operation. Click [here](/docs/developer/api_integration/payment_2.0/example_requests/for_merchants/#With-items-and-buyer-return-fee) for example about usage for merchants or [here](/docs/developer/api_integration/payment_2.0/example_requests/for_marketplaces/#With-items-and-buyer-return-fee) for marketplaces.
    Enum: "RETURN_FEE"

  - `vats` (array)
    List of value-added tax (VAT) amounts.

  - `vats.net_amount` (number)
    The net amount before taxes for the given tax rate.
    Example: 56.81

  - `vats.tax_amount` (number)
    The tax amount for the given tax rate.
    Example: 10.79

  - `vats.tax_rate` (number)
    Tax rate given as percentage on the net amount.
    Example: 19

## Response 400 fields (application/problem+json):

  - `decline` (object, required)
    Information about why transaction was not accepted and declined.

  - `decline.category` (string, required)
    Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.
    Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION"

  - `decline.invalid_fields` (array)
    List of one or multiple entries describing each failed validation. Only present if reason is INVALID_FIELDS.

  - `decline.invalid_fields.json_path` (string, required)
    The JSON path pointing to the location where the validation failed.
    Example: "partner_operation_id"

  - `decline.invalid_fields.message` (string, required)
    A message describing which constraint was violated.
    Example: "size must be between 0 and 255"

  - `decline.reasons` (array, required)
    List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.
    Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED", "OTP_VERIFICATION_REQUIRED_BUT_FEATURE_NOT_ENABLED", "ORDER_WITH_PHONE_INTELLIGENCE_FRAUD_SUSPICION_BLOCKLISTED", "OTP_FAILED", "OTP_EXPIRED"

## Response 404 fields (application/problem+json):

  - `decline` (object, required)
    Information about why transaction was not accepted and declined.

  - `decline.category` (string, required)
    Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.
    Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION"

  - `decline.reasons` (array, required)
    List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.
    Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED"

## Response 422 fields (application/problem+json):

  - `decline` (object, required)

  - `decline.category` (string, required)
    Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.
    Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION"

  - `decline.reasons` (array)
    List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.
    Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED"

## Response 451 fields (application/problem+json):

  - `decline` (object, required)
    Information about why transaction was not accepted and declined.

  - `decline.category` (string, required)
    Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.
    Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION"

  - `decline.reasons` (array, required)
    List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.
    Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED"


## Response 500 fields