# Refund transaction

Refund a previously authorized and captured transaction

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

## Path parameters:

  - `ratepay_transaction_id` (string, required)
    ID of transaction to refund. 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 refund given in currency of original transaction.
    Example: 67.6

  - `items` (array)
    List of refunded 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)
    Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "refund-id-1234"

  - `partner_shop_id` (string)
    The shop ID generated by the partner or provided upfront by Ratepay. 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 refunded special items, e.g. shipping costs or discounts.

  - `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, required)
    The net amount before taxes for the given tax rate.
    Example: 56.81

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

  - `vats.tax_rate` (number, required)
    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