---
title: "Authorize transaction"
method: POST
path: "/v2/transactions"
tags: ["Transaction management"]
---

# Authorize transaction

`POST /v2/transactions`

Perform an authorization request for a transaction.

## Headers

- `Idempotency-Key` string
- `Prefer` 'return=representation'
- `X-Partner` string

## Request body

- TransactionRequestDto
  - `authorization_expires` string, date-time — The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). If not given, a default expiry time is generated.
  - `buyer` union, required — The buyer that wants to place the transaction.
    - object — B2C transaction. Provide a person for individual buyers. Either provide a person or company but not both.
      - `billing_address` AddressDto, required — The address of the recipient.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `street` string, required — The name of the street.
        - `street_addition` string — Additional information about the address, e.g. 2nd floor, c/o John Doe.
        - `street_number` string — The number describing where the building is located in the street. Notice that it **must** be sent in either this field or in `street`. For example, if the `street` field contains "Musterstraße 1, then it is not needed to supply data here. But if `street` only contains "Musterstraße", then `street_number` must contain "1".
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
      - `contact` ContactDto, required — The contact information of the buyer.
        - `email` string, required — The email address of the buyer.
        - `phone` string, required — The phone number of the buyer. Has to have at least 6 digits without spaces.
      - `language` string — The language in which the buyer prefers communication to be done. If the preferred language is not supported, the buyer communication will be in German. Must conform to [ISO 639-1 alpha 2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
      - `shop_buyer_id` string — The unique buyer ID to identify a regular customer. See [regular customer documentation](/docs/reporting/regular_customers/regular_customers_introduction/) for details. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
      - `person` PersonDto, required — The person that wants to place the transaction. This implies a B2C transaction. Either provide a person or company but not both.
        - `date_of_birth` string, date, required — The date of birth of the person. Must be in format `YYYY-MM-DD` conforming to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
        - `first_name` string, required — The first name of the person.
        - `last_name` string, required — The last name of the person.
        - `title` string — The title of the person.
    - object — B2B transaction. Provide a company for business buyers. Either provide a person or company but not both.
      - `billing_address` AddressDto, required — The address of the recipient.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `street` string, required — The name of the street.
        - `street_addition` string — Additional information about the address, e.g. 2nd floor, c/o John Doe.
        - `street_number` string — The number describing where the building is located in the street. Notice that it **must** be sent in either this field or in `street`. For example, if the `street` field contains "Musterstraße 1, then it is not needed to supply data here. But if `street` only contains "Musterstraße", then `street_number` must contain "1".
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
      - `contact` ContactDto, required — The contact information of the buyer.
        - `email` string, required — The email address of the buyer.
        - `phone` string, required — The phone number of the buyer. Has to have at least 6 digits without spaces.
      - `language` string — The language in which the buyer prefers communication to be done. If the preferred language is not supported, the buyer communication will be in German. Must conform to [ISO 639-1 alpha 2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
      - `shop_buyer_id` string — The unique buyer ID to identify a regular customer. See [regular customer documentation](/docs/reporting/regular_customers/regular_customers_introduction/) for details. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
      - `company` CompanyDto, required — The company that wants to place the transaction. This implies a B2B transaction. Either provide a person or company but not both.
        - `first_name` string — The first name of the contact person within the company.
        - `last_name` string — The last name of the contact person within the company.
        - `name` string, required — Official company name, should include legal form if applicable.
        - `vat_id` string — Value-added tax ID of the company. This can be a European VAT ID or a local one.
  - `currency` string, required — The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
  - `delivery` union — The delivery address and additional delivery parameters.
    - object — Standard delivery to an address.
      - `first_name` string — The first name of the recipient. If supplied together with `last_name`, `full_name` will be ignored if also provided.
      - `full_name` string — The full name of the recipient. This is used only when `first_name` and `last_name` are not provided.
      - `last_name` string — The last name of the recipient. If supplied together with `first_name`, `full_name` will be ignored if also provided.
      - `address` AddressDto, required — The address of the recipient.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `street` string, required — The name of the street.
        - `street_addition` string — Additional information about the address, e.g. 2nd floor, c/o John Doe.
        - `street_number` string — The number describing where the building is located in the street. Notice that it **must** be sent in either this field or in `street`. For example, if the `street` field contains "Musterstraße 1, then it is not needed to supply data here. But if `street` only contains "Musterstraße", then `street_number` must contain "1".
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
    - object — Collect in-store. Only one of address, in_store_collect, pick_up_box, or pick_up_shop may be provided.
      - `first_name` string — The first name of the recipient. If supplied together with `last_name`, `full_name` will be ignored if also provided.
      - `full_name` string — The full name of the recipient. This is used only when `first_name` and `last_name` are not provided.
      - `last_name` string — The last name of the recipient. If supplied together with `first_name`, `full_name` will be ignored if also provided.
      - `in_store_collect` InStoreCollectDto, required — The information of the in-store collect.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `location_name` string — The name of the collection location.
        - `street` string, required — The name of the street.
        - `street_addition` string — Additional information about the address.
        - `street_number` string — The number describing where the building is located in the street.
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
    - object — Delivery to a pick-up box (e.g. DHL Packstation). Only one of address, in_store_collect, pick_up_box, or pick_up_shop may be provided.
      - `first_name` string — The first name of the recipient. If supplied together with `last_name`, `full_name` will be ignored if also provided.
      - `full_name` string — The full name of the recipient. This is used only when `first_name` and `last_name` are not provided.
      - `last_name` string — The last name of the recipient. If supplied together with `first_name`, `full_name` will be ignored if also provided.
      - `pick_up_box` PickUpBoxDto, required — The information of the pick up box.
        - `carrier_name` string — The name of the parcel carrier.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `location_id` string, required — The ID of pick up location with the carrier.
        - `recipient_account_id` string — The ID of the receiver with the carrier. It is optional only for country_code AT, otherwise it is required.
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
    - object — Delivery to a pick-up shop. Only one of address, in_store_collect, pick_up_box, or pick_up_shop may be provided.
      - `first_name` string — The first name of the recipient. If supplied together with `last_name`, `full_name` will be ignored if also provided.
      - `full_name` string — The full name of the recipient. This is used only when `first_name` and `last_name` are not provided.
      - `last_name` string — The last name of the recipient. If supplied together with `first_name`, `full_name` will be ignored if also provided.
      - `pick_up_shop` PickUpShopDto, required — The information of the pick up shop.
        - `city` string, required — The city of the address. Must be at least 2 non whitespace characters.
        - `country_code` string, required — The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        - `location_name` string — The name of the pick up shop.
        - `street` string, required — The name of the street.
        - `street_addition` string — Additional information about the address.
        - `street_number` string — The number describing where the building is located in the street.
        - `zip_code` string, required — The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).
  - `device` union — The device used to initiate the transaction.
    - object — Use this variant when integrating Ratepay's device fingerprinting feature. Provide the token generated by the Ratepay script.
      - `browser` BrowserDto — The browser used by the buyer.
        - `language` string — The language used by the browser. Must conform to [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag).
        - `name` string — The name of the used browser.
        - `version` string — The version of the used browser.
      - `geo_location` GeoLocationDto — The geographical position of the buyer's device.
        - `latitude` number — The latitude of the geographical position of the buyer's device.
        - `longitude` number — The longitude of the geographical position of the buyer's device.
      - `http_forwarded_ip_address` string — The IP address of the network client initiating the connection to the web shop. Can be an IPv4 or IPv6 address. It is **mandatory** in case of Online orders, but optional otherwise.
      - `risk` RiskDto — The risk associated with the buyer's device. Can be empty.
        - `reasons` string[] — List of reasons for the estimated risk.
        - `score` integer — A numerical value for the estimated risk.
      - `screen` ScreenDto — The dimensions of the buyer's screen.
        - `height` integer — The height of the buyer's screen in pixel.
        - `width` integer — The width of the buyer's screen in pixel.
      - `source_ip_address` string — The IP address of the network client initiating the connection to the web shop. Can be an IPv4 or IPv6 address. It is **mandatory** in case of Online orders, but optional otherwise.
      - `token` string, required — ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/). Include the generated token if you are using the device fingerprinting feature in your integration.
    - object — Use this variant when NOT using Ratepay's device fingerprinting feature. Provide a fingerprint generated by your own system.
      - `browser` BrowserDto — The browser used by the buyer.
        - `language` string — The language used by the browser. Must conform to [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag).
        - `name` string — The name of the used browser.
        - `version` string — The version of the used browser.
      - `geo_location` GeoLocationDto — The geographical position of the buyer's device.
        - `latitude` number — The latitude of the geographical position of the buyer's device.
        - `longitude` number — The longitude of the geographical position of the buyer's device.
      - `http_forwarded_ip_address` string — The IP address of the network client initiating the connection to the web shop. Can be an IPv4 or IPv6 address. It is **mandatory** in case of Online orders, but optional otherwise.
      - `risk` RiskDto — The risk associated with the buyer's device. Can be empty.
        - `reasons` string[] — List of reasons for the estimated risk.
        - `score` integer — A numerical value for the estimated risk.
      - `screen` ScreenDto — The dimensions of the buyer's screen.
        - `height` integer — The height of the buyer's screen in pixel.
        - `width` integer — The width of the buyer's screen in pixel.
      - `source_ip_address` string — The IP address of the network client initiating the connection to the web shop. Can be an IPv4 or IPv6 address. It is **mandatory** in case of Online orders, but optional otherwise.
      - `finger_print` string, required — A unique fingerprint to identify the buyer's device. This fingerprint is generated by the partner. Provide this if you do not integrate [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).
  - `options` OptionsDto — The options controlling transaction processing.
    - `sales_channel` 'WEBSHOP' | 'POINT_OF_SALE' | 'PHONE_OR_MAIL' — The sales channel the transaction originates from.
  - `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.
  - `partner_transaction_id` string — The transaction ID generated by the partner (i.e. Partner Order ID). Use the same value as shop_transaction_id unless the shop and integration partner manage separate transaction IDs, such as in PSP (payment service provider) integrations. **This field must be included in at least one of the following requests: authorization or capture.** 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.
  - `payment_method` PaymentMethodDto, required — The payment method selected by the buyer.
    - `payment_option` 'OPEN_INVOICE' | 'PAY_NOW', required — The payment option the buyer selected.
    - `transfer_type` 'BANK_TRANSFER' | 'SEPA_DIRECT_DEBIT', required — The transfer type the buyer selected.
  - `shop_baskets` ShopBasketDto[], required — One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.
    - `gross_amount` number, required — The amount for the basket including VAT given in the currency of the transaction. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.
    - `items` ItemDto[], required — List of items contained in the transaction.
      - `article_number` string — The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.
      - `category` string — Category for the item.
      - `description` string — Description of the item.
      - `gross_total_price` number — Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity
      - `gross_unit_discount` number — Gross discount on one item after taxes. Needs to be a negative value.
      - `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.
      - `name` string, required — Name of the item.
      - `net_total_price` number — Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity
      - `net_unit_discount` number — Net discount on one item before taxes. Needs to be a negative value.
      - `net_unit_price` number — Net value of one item before taxes.
      - `quantity` number, required — Ordered quantity of the item.
      - `tax_rate` number, required — Tax rate applicable for the item given in percent.
      - `unit` string — Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
    - `partner_shop_id` string, required — 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.
    - `shop_merchant_id` string — This is the unique identifier for the merchant. Before using the merchant_id in the shop_baskets object, it must be requested from Ratepay and connected with a respective partner_shop_id in the Ratepay systems. Please refer to the [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.
    - `shop_transaction_id` string, required — The transaction ID generated by the shop (i.e. Shop Order ID). Use the same value as partner_transaction_id unless the shop and integration partner manage separate transaction IDs, such as in PSP integrations. **This field must be included in at least one of the following requests: authorization or capture.** This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support.
    - `special_items` SpecialItemDto[] — List of special items contained in the transaction, e.g. shipping costs or discounts.
      - `article_number` string — The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.
      - `category` string — Category for the item.
      - `description` string — Description of the item.
      - `gross_total_price` number — Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity
      - `gross_unit_discount` number — Gross discount on one item after taxes. Needs to be a negative value.
      - `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.
      - `name` string, required — Name of the item.
      - `net_total_price` number — Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity
      - `net_unit_discount` number — Net discount on one item before taxes. Needs to be a negative value.
      - `net_unit_price` number — Net value of one item before taxes.
      - `quantity` number, required — Ordered quantity of the item.
      - `tax_rate` number, required — Tax rate applicable for the item given in percent.
      - `type` 'RETURN_FEE' — 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.
      - `unit` string — Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
    - `vats` VatDto[] — List of value-added tax (VAT) amounts.
      - `net_amount` number — The net amount before taxes for the given tax rate.
      - `tax_amount` number — The tax amount for the given tax rate.
      - `tax_rate` number — Tax rate given as percentage on the net amount.
  - `shops` ShopDto[] — Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.
    - `correspondence_settings` CorrespondenceSettingsDto — Settings for buyer correspondences.
      - `branding_settings` BrandingSettingsDto — Shop branding settings for buyer correspondences.
        - `highlight_color` string — The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g. `#BADB11`.
        - `logo_position` 'LEFT' | 'RIGHT' | 'CENTER' — Shop logo position in buyer correspondences.
        - `logo_url` string — Publicly accessible shop logo to include in buyer correspondences. This must be a valid `https://` or `http://` URL.
      - `slangs` SlangsDto — Language settings for buyer correspondences.
        - `de` SlangDto
          - `customer_service_contact` string[] — List of 1 to 5 lines with correspondence information. Include how to reach customer support.
          - `formal_tone` 'FORMAL' | 'INFORMAL' — Formality level for the buyer correspondences.
          - `name_format` 'EMPTY' | 'FIRST_NAME' | 'LAST_NAME' | 'FIRST_LAST_NAME' — Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
          - `salutation` string — Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
          - `transaction_type` 'ORDER' | 'BOOKING' — Specifies how to call the transaction in buyer correspondences.
        - `en` SlangDto
          - `customer_service_contact` string[] — List of 1 to 5 lines with correspondence information. Include how to reach customer support.
          - `formal_tone` 'FORMAL' | 'INFORMAL' — Formality level for the buyer correspondences.
          - `name_format` 'EMPTY' | 'FIRST_NAME' | 'LAST_NAME' | 'FIRST_LAST_NAME' — Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
          - `salutation` string — Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
          - `transaction_type` 'ORDER' | 'BOOKING' — Specifies how to call the transaction in buyer correspondences.
        - `fr` SlangDto
          - `customer_service_contact` string[] — List of 1 to 5 lines with correspondence information. Include how to reach customer support.
          - `formal_tone` 'FORMAL' | 'INFORMAL' — Formality level for the buyer correspondences.
          - `name_format` 'EMPTY' | 'FIRST_NAME' | 'LAST_NAME' | 'FIRST_LAST_NAME' — Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
          - `salutation` string — Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
          - `transaction_type` 'ORDER' | 'BOOKING' — Specifies how to call the transaction in buyer correspondences.
        - `nl` SlangDto
          - `customer_service_contact` string[] — List of 1 to 5 lines with correspondence information. Include how to reach customer support.
          - `formal_tone` 'FORMAL' | 'INFORMAL' — Formality level for the buyer correspondences.
          - `name_format` 'EMPTY' | 'FIRST_NAME' | 'LAST_NAME' | 'FIRST_LAST_NAME' — Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
          - `salutation` string — Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
          - `transaction_type` 'ORDER' | 'BOOKING' — Specifies how to call the transaction in buyer correspondences.
    - `legal` ShopLegalDto, required — Legal information about the shop.
      - `commercial_register_number` string, required — The registration number the shop is filed under.
      - `legal_form` string, required — The legal form as which the shop is registered, e.g. Ltd., GmbH, GbR, etc.
      - `name` string, required — The name of the shop as which it is registered.
    - `merchant` MerchantDto — This section contains optional details about a merchant managing a shop. A single merchant may operate one or more shops. By connecting shops to a specific merchant, it becomes possible to configure a merchant-level set of settings in the Ratepay systems. These settings will then be applied to all the associated shops.
      - `merchant_id` string — This is the unique identifier for the merchant. Before using the merchant_id in the API payload request, it must be requested from Ratepay. Please refer to the [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.
      - `merchant_name` string — This refers to the name of the merchant. It may vary from both the shop name and the legal name of the shop, both of which are also present in the current shops object.
    - `merchant_category_code` string, required — The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html).
    - `name` string, required — The name of the shop. May differ from legal name.
    - `partner_shop_id` string, required — 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.

## Response `201`

Transaction authorized

## Other responses

- `202` — Transaction pre-authorized — buyer OTP verification required to complete payment
- `400` — Bad request
- `422` — Transaction declined
- `500` — Technical problem

---

[API](https://skmtc.net/ratepay/apis/payment-openapi-specification.md) · [All operations](https://skmtc.net/ratepay/apis/payment-openapi-specification/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ratepay/payment-openapi-specification/revisions/1c957020939e/schema)