# Creates a new session

Endpoint: POST /pps/api/v1/session
Version: v0
Security: Bearer Authentication

## Request fields (application/json):

  - `order_data` (object, required)

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

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

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

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

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

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

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

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

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

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

  - `order_data.buyer.company.first_name` (string)
    The first name of the contact person within the company.

  - `order_data.buyer.company.last_name` (string)
    The last name of the contact person within the company.

  - `order_data.buyer.company.name` (string, required)
    Official company name, should include legal form if applicable.

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

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

  - `order_data.buyer.contact.email` (string, required)
    The email address of the buyer.

  - `order_data.buyer.contact.phone` (string)
    The phone number of the buyer. Has to have at least 6 digits without spaces.

  - `order_data.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_language_codes).

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

  - `order_data.buyer.person.date_of_birth` (string)
    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).

  - `order_data.buyer.person.first_name` (string, required)
    The first name of the person. It must be a string containing only characters with :  any kind of letter from any language (including accented letters) Unicode mark characters (accents/diacritics) any kind of numeric character space period backtick (`) apostrophe (') hyphen (-)

  - `order_data.buyer.person.last_name` (string, required)
    The last name of the person. It must be a string containing only characters with :  any kind of letter from any language (including accented letters) Unicode mark characters (accents/diacritics) any kind of numeric character space period backtick (`) apostrophe (') hyphen (-)

  - `order_data.buyer.person.title` (string)
    The title of the person.

  - `order_data.buyer.shop_buyer_id` (string)
    The buyer ID of a regular customer. See [regular customer documentation](https://docs.ratepay.com/docs/reporting/regular_customers/regular_customers_introduction/) for details. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.

  - `order_data.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).

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

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

  - `order_data.delivery.company` (string)
    The company name of the recipient.

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

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

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

  - `order_data.delivery.in_store_collect.location_name` (string)
    The name of the collection location.

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

  - `order_data.delivery.in_store_collect.street_number` (string)
    The number describing where the building is located in the street.

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

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

  - `order_data.delivery.pick_up_box.carrier_name` (string)
    The name of the parcel carrier.

  - `order_data.delivery.pick_up_box.location_id` (string, required)
    The ID of pick up location with the carrier.

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

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

  - `order_data.delivery.pick_up_shop.location_name` (string)
    The name of the pick up shop.

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.

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

  - `order_data.shop_baskets.items.article_number` (string)
    The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.

  - `order_data.shop_baskets.items.category` (string)
    Category for the item.

  - `order_data.shop_baskets.items.description` (string)
    Description of the item.

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

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

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

  - `order_data.shop_baskets.items.name` (string, required)
    Name of the item.

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

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

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

  - `order_data.shop_baskets.items.quantity` (integer, required)
    Ordered quantity of the item.

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

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

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.

  - `order_data.shop_baskets.shop_transaction_id` (string)
    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.

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `order_data.shops.correspondence_settings.slangs.de.customer_service_contact` (array)
    List of 1 to 5 lines with correspondence information. Include how to reach customer support.

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

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

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

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

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

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

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

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

  - `order_data.shops.legal.commercial_register_number` (string)
    The registration number the shop is filed under.

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

  - `order_data.shops.legal.name` (string, required)
    The name of the shop as which it is registered.

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

  - `order_data.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](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.

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

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

  - `order_data.shops.name` (string, required)
    The name of the shop. May differ from legal name.

  - `url_data` (object)

  - `url_data.success_url` (string)
    The location where the buyer should be redirected to, when the transaction succeeds

  - `url_data.cancel_url` (string)
    The location where the buyer should be redirected to, when the transaction gets canceled.

  - `url_data.failure_url` (string)
    The location where the buyer should be redirected to, when the transaction fails.

  - `url_data.webhook_url` (string)
    The address of where the result of the transaction should be posted. See [its documentation](/apis/hpp/openapi/hpp_api/webhook-format/webhook) to get more details.

## Response 201 fields (application/json):

  - `session_id` (string)

  - `landing_page` (string, required)

## Response 401 fields (application/json):

  - `code` (string, required)
    INVALID_TOKEN: The provided token is invalid or expired.
    Enum: "INVALID_TOKEN"

## Response 404 fields (application/json):

  - `code` (string, required)
    INVALID_SESSION_MISSING_TRANSACTION_ID: The session is missing a transaction ID.     
        SELLER_CONFIG_NOT_FOUND: Seller configuration not found for the provided token.
    Enum: "SELLER_CONFIG_NOT_FOUND", "INVALID_SESSION_MISSING_TRANSACTION_ID"

## Response 422 fields (application/json):

  - `code` (string, required)
    INVALID_SESSION_STATE: The session is in an invalid state.
        CUSTOMER_CONTACT_DETAILS_MISSING: Customer contact details are missing.
    Enum: "INVALID_SESSION_STATE", "CUSTOMER_CONTACT_DETAILS_MISSING"


## Response 403 fields