# Authorize transaction

Perform an authorization request for a transaction.

Endpoint: POST /v2/transactions
Version: version 2
Security: Bearer Authentication

## 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):

  - `authorization_expires` (string)
    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.
    Example: "2025-04-02T16:15:18.823+02:00"

  - `buyer` (object, required)
    The buyer that wants to place the transaction.

  - `buyer.billing_address` (object, required)
    The address of the recipient.

  - `buyer.billing_address.city` (string, required)
    The city of the address. Must be at least 2 non whitespace characters.
    Example: "Berlin"

  - `buyer.billing_address.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).
    Example: "DE"

  - `buyer.billing_address.street` (string, required)
    The name of the street.
    Example: "Schönhauser Allee"

  - `buyer.billing_address.street_addition` (string)
    Additional information about the address, e.g. 2nd floor, c/o John Doe.
    Example: "Seitenflügel, 2. HH"

  - `buyer.billing_address.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".
    Example: "84"

  - `buyer.billing_address.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).
    Example: "10439"

  - `buyer.company` (object)
    The company that wants to place the transaction. This implies a B2B transaction. Either provide a person or company but not both.

  - `buyer.company.first_name` (string)
    The first name of the contact person within the company.
    Example: "Heinz"

  - `buyer.company.last_name` (string)
    The last name of the contact person within the company.
    Example: "Steeger"

  - `buyer.company.name` (string, required)
    Official company name, should include legal form if applicable.
    Example: "Berlin Advertising Agency GmbH"

  - `buyer.company.vat_id` (string)
    Value-added tax ID of the company. This can be a European VAT ID or a local one.
    Example: "DE123456789"

  - `buyer.contact` (object, required)
    The contact information of the buyer.

  - `buyer.contact.email` (string, required)
    The email address of the buyer.
    Example: "heinz.steeger@example.org"

  - `buyer.contact.phone` (string, required)
    The phone number of the buyer. Has to have at least 6 digits without spaces.
    Example: "+49 177 44455553"

  - `buyer.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).
    Example: "de"

  - `buyer.person` (object)
    The person that wants to place the transaction. This implies a B2C transaction. Either provide a person or company but not both.

  - `buyer.person.date_of_birth` (string, 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).
    Example: "1971-05-19"

  - `buyer.person.first_name` (string, required)
    The first name of the person.
    Example: "Heinz"

  - `buyer.person.last_name` (string, required)
    The last name of the person.
    Example: "Steeger"

  - `buyer.person.title` (string)
    The title of the person.
    Example: "Dr."

  - `buyer.shop_buyer_id` (string)
    The buyer ID of 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.
    Example: "shop-buyer-id-1234"

  - `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).
    Example: "EUR"

  - `delivery` (object)
    The delivery address and additional delivery parameters.

  - `delivery.address` (object)
    The address of the recipient.

  - `delivery.company` (string)
    The company name of the recipient.
    Example: "Berlin Advertising Agency"

  - `delivery.first_name` (string)
    The first name of the recipient. If supplied, the field last_name becomes mandatory, and full_name must not be sent.
    Example: "Heinz"

  - `delivery.full_name` (string)
    The full name of the recipient. If supplied, the fields first_name and last_name must not be sent.

  - `delivery.in_store_collect` (object)
    The information of the in-store collect.

  - `delivery.in_store_collect.location_name` (string)
    The name of the collection location.
    Example: "Apotheke am Rathaus"

  - `delivery.in_store_collect.street_addition` (string)
    Additional information about the address.

  - `delivery.in_store_collect.street_number` (string)
    The number describing where the building is located in the street.
    Example: "22"

  - `delivery.last_name` (string)
    The last name of the recipient. If supplied, the field first_name becomes mandatory, and full_name must not be sent.
    Example: "Steeger"

  - `delivery.pick_up_box` (object)
    The information of the pick up box.

  - `delivery.pick_up_box.carrier_name` (string)
    The name of the parcel carrier.
    Example: "DHL"

  - `delivery.pick_up_box.location_id` (string, required)
    The ID of pick up location with the carrier.
    Example: "Packstation 985"

  - `delivery.pick_up_box.recipient_account_id` (string)
    The ID of the receiver with the carrier. It is optional only for country_code AT, otherwise it is required.
    Example: "445522299"

  - `delivery.pick_up_shop` (object)
    The information of the pick up shop.

  - `delivery.pick_up_shop.location_name` (string)
    The name of the pick up shop.
    Example: "Kiosk am Stadtpark"

  - `device` (object)
    The device used to initiate the transaction.

  - `device.browser` (object)
    The browser used by the buyer.

  - `device.browser.language` (string)
    The language used by the browser. Must conform to [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag).
    Example: "de-DE"

  - `device.browser.name` (string)
    The name of the used browser.
    Example: "Mozilla Firefox"

  - `device.browser.version` (string)
    The version of the used browser.
    Example: "94.0 (64-bit)"

  - `device.finger_print` (string)
    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/). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "bc47575c-7f93-4bae-84dc-282edf6a5d85"

  - `device.geo_location` (object)
    The geographical position of the buyer's device.

  - `device.geo_location.latitude` (number)
    The latitude of the geographical position of the buyer's device.
    Example: 52.518368

  - `device.geo_location.longitude` (number)
    The longitude of the geographical position of the buyer's device.
    Example: 13.325109

  - `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.
    Example: "123.123.123.123"

  - `device.risk` (object)
    The risk associated with the buyer's device.

  - `device.risk.reasons` (array)
    List of reasons for the estimated risk.
    Example: ["RISKY_DEVICE_BEHAVIOR"]

  - `device.risk.score` (integer)
    A numerical value for the estimated risk.
    Example: 123

  - `device.screen` (object)
    The dimensions of the buyer's screen.

  - `device.screen.height` (integer)
    The height of the buyer's screen in pixel.
    Example: 1080

  - `device.screen.width` (integer)
    The width of the buyer's screen in pixel.
    Example: 1920

  - `device.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.
    Example: "10.17.1.1"

  - `device.token` (string)
    ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).Include the generated token if you are using the device fingerprintingfeature in your integration. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)used in payment API.
    Example: "ade028c1-d2a2-4189-9214-e21089cd47f1"

  - `options` (object)
    The options controlling transaction processing.

  - `options.sales_channel` (string)
    The sales channel the transaction originates from.
    Enum: "WEBSHOP", "POINT_OF_SALE", "PHONE_OR_MAIL"

  - `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: "partner-operation-id-1234"

  - `partner_transaction_id` (string)
    The transaction ID generated by the partner. 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.
    Example: "partner-transaction-id-1234"

  - `payment_details` (object)
    Provides details about the payment to be executed by Ratepay. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.

  - `payment_details.debit_bank_account` (object, required)
    The bank account Ratepay will use to deduct captured transaction amounts. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.

  - `payment_details.debit_bank_account.bic` (string)
    BIC of the bank, also known as SWIFT code, without any whitespaces. Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362).
    Example: "EXBANKXXX"

  - `payment_details.debit_bank_account.iban` (string, required)
    IBAN of the bank account. Any whitespaces will be removed. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
    Example: "DE12345678901234567890"

  - `payment_details.debit_bank_account.owner` (string, required)
    Owner of the bank account.
    Example: "Heinz Steeger"

  - `payment_method` (object, required)
    The payment method selected by the buyer.

  - `payment_method.payment_option` (string, required)
    The payment option the buyer selected.
    Enum: "OPEN_INVOICE", "PAY_NOW"

  - `payment_method.transfer_type` (string, required)
    The transfer type the buyer selected.
    Enum: "BANK_TRANSFER", "SEPA_DIRECT_DEBIT"

  - `shop_baskets` (array, 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.

  - `shop_baskets.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.
    Example: 67.6

  - `shop_baskets.items` (array, required)
    List of items contained in the transaction.

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

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

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

  - `shop_baskets.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

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

  - `shop_baskets.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

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

  - `shop_baskets.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

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

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

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

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

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

  - `shop_baskets.partner_shop_id` (string, required)
    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.
    Example: "partner-shop-id-1"

  - `shop_baskets.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.
    Example: "ratepay-merchant-id-123"

  - `shop_baskets.shop_transaction_id` (string, required)
    The transaction ID generated by the shop. 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.
    Example: "shop-transaction-id-1234"

  - `shop_baskets.special_items` (array)
    List of special items contained in the transaction, e.g. shipping costs or discounts.

  - `shop_baskets.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"

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

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

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

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

  - `shops` (array)
    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.

  - `shops.correspondence_settings` (object)
    Settings for buyer correspondences.

  - `shops.correspondence_settings.branding_settings` (object)
    Shop branding settings for buyer correspondences.

  - `shops.correspondence_settings.branding_settings.highlight_color` (string)
    The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g. #BADB11.
    Example: "#badb11"

  - `shops.correspondence_settings.branding_settings.logo_position` (string)
    Shop logo position in buyer correspondences.
    Enum: "LEFT", "RIGHT", "CENTER"

  - `shops.correspondence_settings.branding_settings.logo_url` (string)
    Publicly accessible shop logo to include in buyer correspondences. This must be a valid https:// or http:// URL.
    Example: "https://cdn.example.com/a/b/c/logo-fruits-and-more_400x65.png"

  - `shops.correspondence_settings.slangs` (object)
    Language settings for buyer correspondences.

  - `shops.correspondence_settings.slangs.de` (object)

  - `shops.correspondence_settings.slangs.de.customer_service_contact` (array)
    List of 1 to 5 lines with correspondence information. Include how to reach customer support.
    Example: ["You can reach our customer service Mon - Sun 7 am to 8 pm","by mail: customer-service@example.com","by phone: 030 / 123 456 789","contact form: example.com/contact"]

  - `shops.correspondence_settings.slangs.de.formal_tone` (string)
    Formality level for the buyer correspondences.
    Enum: "FORMAL", "INFORMAL"

  - `shops.correspondence_settings.slangs.de.name_format` (string)
    Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
    Enum: "EMPTY", "FIRST_NAME", "LAST_NAME", "FIRST_LAST_NAME"

  - `shops.correspondence_settings.slangs.de.salutation` (string)
    Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
    Example: "Hello"

  - `shops.correspondence_settings.slangs.de.transaction_type` (string)
    Specifies how to call the transaction in buyer correspondences.
    Enum: "ORDER", "BOOKING"

  - `shops.correspondence_settings.slangs.en` (object)

  - `shops.correspondence_settings.slangs.fr` (object)

  - `shops.correspondence_settings.slangs.nl` (object)

  - `shops.legal` (object, required)
    Legal information about the shop.

  - `shops.legal.commercial_register_number` (string)
    The registration number the shop is filed under.
    Example: "HRB 12345FF"

  - `shops.legal.legal_form` (string)
    The legal form as which the shop is registered, e.g. Ltd., GmbH, GbR, etc.
    Example: "GmbH"

  - `shops.legal.name` (string, required)
    The name of the shop as which it is registered.
    Example: "Fruits and more GmbH"

  - `shops.merchant` (object)
    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.

  - `shops.merchant.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.
    Example: "ratepay-merchant-id-123"

  - `shops.merchant.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.
    Example: "Merchant XYZ"

  - `shops.merchant_category_code` (string, required)
    The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html).
    Example: "5499"

  - `shops.name` (string, required)
    The name of the shop. May differ from legal name.
    Example: "fruits and more"

## Response 201 fields (application/hal+json):

  - `_links` (object, required)
    Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

  - `_links.self` (object, required)
    The self relation identifying the transaction resource itself.

  - `_links.self.href` (string, required)
    URI pointing to resource itself.
    Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"

  - `authorization_expires` (string, required)
    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).

  - `created` (string, required)
    Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `payment_details` (object)
    Provides details about the payment to be executed by the buyer (generated by Ratepay).

  - `payment_details.deposit_bank_account` (object)
    The bank account the buyer has to transfer the money to. Applicable only in case of transfer type BANK_TRANSFER.

  - `payment_details.deposit_bank_account.bank_name` (string, required)
    Name of the bank.
    Example: "Example Bank"

  - `payment_details.deposit_bank_account.bic` (string, required)
    BIC of the bank, also known as SWIFT code, without any whitespaces. Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362).
    Example: "EXBANKXXX"

  - `payment_details.deposit_bank_account.iban` (string, required)
    IBAN of the bank account. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
    Example: "DE12345678901234567890"

  - `payment_details.deposit_bank_account.owner` (string, required)
    Owner of the bank account.
    Example: "Ratepay GmbH"

  - `payment_details.ratepay_payment_references` (array)
    List of payment references and the shop they belong to.

  - `payment_details.ratepay_payment_references.partner_shop_id` (string, required)
    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.
    Example: "partner-shop-id-1"

  - `payment_details.ratepay_payment_references.ratepay_payment_reference` (string, required)
    Purpose to be indicated in the bank transfer (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "ET1285368M8"

  - `payment_details.ratepay_payment_reference` (string)
    Purpose to be indicated in the bank transfer (generated by Ratepay). This is deprecated in favor of ratepay_payment_references. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "ET1285368M8"

  - `result` (string, required)
    Indicates the outcome of the transaction request. Possible value : ACCEPTED – The transaction has been successfully authorized and can proceed to capture.
    Example: "ACCEPTED"

  - `ratepay_transaction_id` (string, required)
    ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "scwBgARW-nE93I7_ywhp"

## Response 202 fields (application/hal+json):

  - `_links` (object, required)
    Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

  - `_links.self` (object, required)
    The self relation identifying the transaction resource itself.

  - `_links.self.href` (string, required)
    URI pointing to resource itself.
    Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"

  - `authorization_expires` (string, required)
    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).

  - `created` (string, required)
    Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `payment_details` (object)
    Provides details about the payment to be executed by the buyer (generated by Ratepay).

  - `payment_details.deposit_bank_account` (object)
    The bank account the buyer has to transfer the money to. Applicable only in case of transfer type BANK_TRANSFER.

  - `payment_details.deposit_bank_account.bank_name` (string, required)
    Name of the bank.
    Example: "Example Bank"

  - `payment_details.deposit_bank_account.bic` (string, required)
    BIC of the bank, also known as SWIFT code, without any whitespaces. Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362).
    Example: "EXBANKXXX"

  - `payment_details.deposit_bank_account.iban` (string, required)
    IBAN of the bank account. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
    Example: "DE12345678901234567890"

  - `payment_details.deposit_bank_account.owner` (string, required)
    Owner of the bank account.
    Example: "Ratepay GmbH"

  - `payment_details.ratepay_payment_references` (array)
    List of payment references and the shop they belong to.

  - `payment_details.ratepay_payment_references.partner_shop_id` (string, required)
    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.
    Example: "partner-shop-id-1"

  - `payment_details.ratepay_payment_references.ratepay_payment_reference` (string, required)
    Purpose to be indicated in the bank transfer (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "ET1285368M8"

  - `payment_details.ratepay_payment_reference` (string)
    Purpose to be indicated in the bank transfer (generated by Ratepay). This is deprecated in favor of ratepay_payment_references. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "ET1285368M8"

  - `result` (string, required)
    Indicates the outcome of the transaction request. Possible value : OTP_REQUIRED – The buyer must complete OTP verification before the transaction can be finalized.
    Example: "OTP_REQUIRED"

  - `otp_details` (object)
    Present only when result = OTP_REQUIRED. Contains OTP validity, regeneration timing, localized messages, and verification endpoints.

  - `otp_details.regeneration_possible_in_seconds` (number)
    Time (in seconds) after which the buyer can request a new OTP if needed.
    Example: 60

  - `otp_details.time_to_live_in_seconds` (number)
    Duration (in seconds) for which the OTP remains valid before expiry.
    Example: 120

  - `otp_details.message` (object)

  - `otp_details.message.en` (string)
    Buyer-facing message confirming OTP send, intended for display in the checkout experience.
    Example: "The code has been sent to your phone number ."

  - `otp_details.message.de` (string)
    Buyer-facing message confirming OTP send, intended for display in the checkout experience.
    Example: "Der Code wurde an Ihre Telefonnummer  gesendet."

  - `otp_details.links` (object)

  - `otp_details.links.regenerate` (string)
    Endpoint to request generation of a new OTP code.
    Example: "/2fa/v1/public/regenerate/TKIZDYV_FU21Q0MSHDNN"

  - `otp_details.links.verify` (string)
    Endpoint to verify the OTP code entered by the buyer.
    Example: "/2fa/v1/public/verify/TKIZDYV_FU21Q0MSHDNN"

  - `ratepay_transaction_id` (string, required)
    ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "scwBgARW-nE93I7_ywhp"

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

  - `_links` (object, required)
    Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

  - `_links.self` (object, required)
    The self relation identifying the transaction resource itself.

  - `_links.self.href` (string, required)
    URI pointing to resource itself.
    Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"

  - `created` (string, required)
    Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `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"

  - `ratepay_transaction_id` (string, required)
    ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "scwBgARW-nE93I7_ywhp"

  - `result` (string, required)
    Indicates the outcome of the transaction request. Possible value : DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment.
    Example: "DECLINED"

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

  - `_links` (object, required)
    Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

  - `_links.self` (object, required)
    The self relation identifying the transaction resource itself.

  - `_links.self.href` (string, required)
    URI pointing to resource itself.
    Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"

  - `created` (string, required)
    Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `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)
    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"

  - `ratepay_transaction_id` (string, required)
    ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.
    Example: "scwBgARW-nE93I7_ywhp"

  - `result` (string, required)
    Indicates the outcome of the transaction request. Possible value : DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment.
    Example: "DECLINED"


## Response 500 fields