openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: https://payment-integration.ratepay.com
    description: Integration environment
  - url: https://payment.ratepay.com
    description: Production environment
security:
  - Bearer Authentication: []
paths:
  /pps/api/v1/session:
    post:
      tags:
        - Session management API
      summary: Creates a new session
      operationId: createSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequestDto'
        required: true
      responses:
        '201':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCreatedResponseDto'
        '401':
          description: >-
            Authorization issue, due to e.g. missing or invalid authorization
            header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: >-
            Authorization issue, due to the provisioned token not having
            permission to create the specified session
        '404':
          description: Data not found, such as seller settings or transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '422':
          description: >-
            Unprocessable, due to e.g. invalid session state or missing customer
            contact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityErrorResponse'
  /pps/api/v1/session-record:
    get:
      tags:
        - Session Records API
      summary: Retrieve a list of session records based on supplied date
      operationId: getSessionRecordsByDate
      parameters:
        - name: createdDate
          in: query
          required: true
          description: A date, formatted as yyyy-MM-dd , when the records have been created
          schema:
            type: string
            format: date
      responses:
        '200':
          description: List of session records returned successfully
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionRecordDto'
        '401':
          description: >-
            Authorization issue, due to e.g. missing or invalid authorization
            header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: >-
            Authorization issue, due to the provisioned token not having
            permission to create the specified session
  /pps/api/v1/session-record/{sessionId}:
    get:
      tags:
        - Session Records API
      summary: Retrieve a session record according to the session ID
      operationId: getSessionRecord
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The session ID, as returned from the request to create sessions
          schema:
            type: string
      responses:
        '200':
          description: Session record returned successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SessionRecordDto'
        '401':
          description: >-
            Authorization issue, due to e.g. missing or invalid authorization
            header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: >-
            Authorization issue, due to the provisioned token not having
            permission to create the specified session
        '404':
          description: Session record not found
  /webhook-url:
    post:
      tags:
        - Webhook format
      summary: Monitor Session Status
      operationId: Webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRecordDto'
        required: true
      responses:
        2xx:
          description: Handled as success case - therefore, will not be retried.
        5xx:
          description: >-
            Handled as a failure, and will be retried later. It will be retried
            in intervals of 3, 6 and 9 seconds until giving up. If it cannot be
            delivered, the merchant is advised to use the session records API to
            fetch the latest status of the transaction.
        4xx:
          description: >-
            Handled as a failure, and will be retried later. It will be retried
            in intervals of 3, 6 and 9 seconds until giving up. If it cannot be
            delivered, the merchant is advised to use the session records API to
            fetch the latest status of the transaction.
components:
  schemas:
    AddressDto:
      required:
        - city
        - country_code
        - street
        - zip_code
      type: object
      properties:
        city:
          maxLength: 100
          minLength: 2
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
          example: Berlin
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
          description: >-
            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
        street:
          maxLength: 100
          minLength: 0
          type: string
          description: The name of the street.
          example: Schönhauser Allee
        street_addition:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Additional information about the address, e.g. 2nd floor, c/o John
            Doe.
          example: Seitenflügel, 2. HH
        street_number:
          maxLength: 30
          minLength: 0
          type: string
          description: >-
            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'
        zip_code:
          maxLength: 10
          minLength: 0
          type: string
          description: >-
            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'
      description: The address of the recipient.
    BrandingSettingsDto:
      type: object
      properties:
        highlight_color:
          pattern: ^#[a-fA-F0-9]{6}$
          type: string
          description: >-
            The color for the highlighted elements in buyer correspondences as
            HTML HEX color code, e.g. `#BADB11`.
        logo_position:
          type: string
          description: Shop logo position in buyer correspondences.
          enum:
            - LEFT
            - RIGHT
            - CENTER
        logo_url:
          type: string
          description: >-
            Publicly accessible shop logo to include in buyer correspondences.
            This must be a valid `https://` or `http://` URL.
      description: Shop branding settings for buyer correspondences.
    BuyerDto:
      required:
        - billing_address
        - contact
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/AddressDto'
        company:
          $ref: '#/components/schemas/CompanyDto'
        contact:
          $ref: '#/components/schemas/ContactDto'
        language:
          pattern: ^[a-z]{2}$
          type: string
          description: >-
            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).
        person:
          $ref: '#/components/schemas/PersonDto'
        shop_buyer_id:
          maxLength: 100
          minLength: 0
          type: string
          description: >-
            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.
      description: The buyer that wants to place the transaction.
    CompanyDto:
      required:
        - name
      type: object
      properties:
        first_name:
          maxLength: 100
          minLength: 0
          type: string
          description: The first name of the contact person within the company.
        last_name:
          maxLength: 100
          minLength: 0
          type: string
          description: The last name of the contact person within the company.
        name:
          maxLength: 100
          minLength: 0
          type: string
          description: Official company name, should include legal form if applicable.
        vat_id:
          maxLength: 20
          minLength: 0
          type: string
          description: >-
            Value-added tax ID of the company. This can be a European VAT ID or
            a local one.
      description: >-
        The company that wants to place the transaction. This implies a B2B
        transaction. Either provide a person or company but not both.
    ContactDto:
      required:
        - email
      type: object
      properties:
        email:
          maxLength: 100
          minLength: 0
          pattern: >-
            ^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$
          type: string
          description: The email address of the buyer.
        phone:
          maxLength: 60
          minLength: 6
          pattern: ^[+0-9/\\\- ().,;]*[0-9][+0-9/\\\- ().,;]*$
          type: string
          description: >-
            The phone number of the buyer. Has to have at least 6 digits without
            spaces.
      description: The contact information of the buyer.
    CorrespondenceSettingsDto:
      type: object
      properties:
        branding_settings:
          $ref: '#/components/schemas/BrandingSettingsDto'
        slangs:
          $ref: '#/components/schemas/SlangsDto'
      description: Settings for buyer correspondences.
    DeliveryDto:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressDto'
        company:
          type: string
          description: The company name of the recipient.
        first_name:
          type: string
          description: >-
            The first name of the recipient. If supplied, the field `last_name`
            becomes mandatory, and `full_name` must not be sent.
        full_name:
          type: string
          description: >-
            The full name of the recipient. If supplied, the fields `first_name`
            and `last_name` must not be sent.
        in_store_collect:
          $ref: '#/components/schemas/InStoreCollectDto'
        last_name:
          type: string
          description: >-
            The last name of the recipient. If supplied, the field `first_name`
            becomes mandatory, and `full_name` must not be sent.
        pick_up_box:
          $ref: '#/components/schemas/PickUpBoxDto'
        pick_up_shop:
          $ref: '#/components/schemas/PickUpShopDto'
      description: The delivery address and additional delivery parameters.
    InStoreCollectDto:
      required:
        - city
        - country_code
        - street
        - zip_code
      type: object
      properties:
        city:
          maxLength: 100
          minLength: 2
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
          description: >-
            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:
          maxLength: 127
          minLength: 0
          type: string
          description: The name of the collection location.
        street:
          maxLength: 100
          minLength: 1
          type: string
          description: The name of the street.
        street_addition:
          maxLength: 50
          minLength: 1
          type: string
          description: Additional information about the address.
        street_number:
          maxLength: 30
          minLength: 1
          type: string
          description: The number describing where the building is located in the street.
        zip_code:
          maxLength: 10
          minLength: 1
          type: string
          description: >-
            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).
      description: The information of the in-store collect.
    LegalDto:
      required:
        - name
      type: object
      properties:
        commercial_register_number:
          maxLength: 12
          minLength: 2
          type: string
          description: The registration number the shop is filed under.
        legal_form:
          maxLength: 255
          minLength: 2
          type: string
          description: >-
            The legal form as which the shop is registered, e.g. Ltd., GmbH,
            GbR, etc.
        name:
          maxLength: 255
          minLength: 2
          type: string
          description: The name of the shop as which it is registered.
      description: Legal information about the shop.
    MerchantDto:
      type: object
      properties:
        merchant_id:
          maxLength: 255
          minLength: 1
          type: string
          description: >-
            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.
        merchant_name:
          maxLength: 255
          minLength: 1
          type: string
          description: >-
            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.
      description: >-
        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.
    OrderData:
      required:
        - buyer
        - currency
        - shop_baskets
      type: object
      properties:
        authorization_expires:
          type: string
          description: >-
            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:
          $ref: '#/components/schemas/BuyerDto'
        currency:
          pattern: ^[A-Z]{3}$
          type: string
          description: >-
            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:
          $ref: '#/components/schemas/DeliveryDto'
        partner_operation_id:
          maxLength: 255
          minLength: 0
          type: string
          description: >-
            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.
        partner_transaction_id:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            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.
        shop_baskets:
          type: array
          description: >-
            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.
          items:
            $ref: '#/components/schemas/ShopBasketDto'
        shops:
          type: array
          description: >-
            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.
          items:
            $ref: '#/components/schemas/ShopDto'
    PersonDto:
      required:
        - first_name
        - last_name
      type: object
      properties:
        date_of_birth:
          type: string
          description: >-
            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:
          maxLength: 100
          minLength: 0
          type: string
          description: >-
            The first name of the person. It must be a string containing only
            characters with : <ul> <li>any kind of letter from any language
            (including accented letters)</li> <li>Unicode mark characters
            (accents/diacritics)</li> <li>any kind of numeric character</li>
            <li>space</li> <li>period</li> <li>backtick (`)</li> <li>apostrophe
            (')</li> <li>hyphen (-)</li></ul>
        last_name:
          maxLength: 100
          minLength: 0
          type: string
          description: >-
            The last name of the person. It must be a string containing only
            characters with : <ul> <li>any kind of letter from any language
            (including accented letters)</li> <li>Unicode mark characters
            (accents/diacritics)</li> <li>any kind of numeric character</li>
            <li>space</li> <li>period</li> <li>backtick (`)</li> <li>apostrophe
            (')</li> <li>hyphen (-)</li></ul>
        title:
          maxLength: 45
          minLength: 0
          type: string
          description: The title of the person.
      description: >-
        The person that wants to place the transaction. This implies a B2C
        transaction. Either provide a person or company but not both.
    PickUpBoxDto:
      required:
        - city
        - country_code
        - location_id
        - zip_code
      type: object
      properties:
        carrier_name:
          maxLength: 127
          minLength: 0
          type: string
          description: The name of the parcel carrier.
        city:
          maxLength: 100
          minLength: 2
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
          description: >-
            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:
          type: string
          description: The ID of pick up location with the carrier.
        recipient_account_id:
          maxLength: 127
          minLength: 0
          type: string
          description: >-
            The ID of the receiver with the carrier. It is optional only for
            country_code AT, otherwise it is required.
        zip_code:
          maxLength: 10
          minLength: 0
          type: string
          description: >-
            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).
      description: The information of the pick up box.
    PickUpShopDto:
      required:
        - city
        - country_code
        - street
        - zip_code
      type: object
      properties:
        city:
          maxLength: 100
          minLength: 2
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
          description: >-
            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:
          maxLength: 127
          minLength: 0
          type: string
          description: The name of the pick up shop.
        street:
          maxLength: 100
          minLength: 1
          type: string
          description: The name of the street.
        street_addition:
          maxLength: 50
          minLength: 1
          type: string
          description: Additional information about the address.
        street_number:
          maxLength: 30
          minLength: 1
          type: string
          description: The number describing where the building is located in the street.
        zip_code:
          maxLength: 10
          minLength: 1
          type: string
          description: >-
            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).
      description: The information of the pick up shop.
    SessionRequestDto:
      required:
        - order_data
      type: object
      properties:
        order_data:
          $ref: '#/components/schemas/OrderData'
        url_data:
          $ref: '#/components/schemas/UrlData'
    ShopBasketDto:
      required:
        - gross_amount
        - items
        - partner_shop_id
        - vats
      type: object
      properties:
        gross_amount:
          type: number
          description: >-
            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.
        items:
          type: array
          description: List of items contained in the transaction.
          items:
            $ref: '#/components/schemas/SpecialItemDto'
        partner_shop_id:
          maxLength: 255
          minLength: 0
          type: string
          description: >-
            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.
        shop_merchant_id:
          maxLength: 255
          minLength: 0
          type: string
          description: >-
            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.
        shop_transaction_id:
          maxLength: 127
          minLength: 0
          type: string
          description: >-
            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.
        special_items:
          type: array
          description: >-
            List of special items contained in the transaction, e.g. shipping
            costs or discounts.
          items:
            $ref: '#/components/schemas/SpecialItemDto'
        vats:
          type: array
          description: List of value-added tax (VAT) amounts.
          items:
            $ref: '#/components/schemas/VatDto'
      description: >-
        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.
    ShopDto:
      required:
        - legal
        - merchant_category_code
        - name
        - partner_shop_id
      type: object
      properties:
        correspondence_settings:
          $ref: '#/components/schemas/CorrespondenceSettingsDto'
        legal:
          $ref: '#/components/schemas/LegalDto'
        merchant:
          $ref: '#/components/schemas/MerchantDto'
        merchant_category_code:
          pattern: ^[0-9]{4}$
          type: string
          description: >-
            he branch of industry of the shop. Must conform to [ISO
            18245](https://www.iso.org/standard/79450.html).
        name:
          maxLength: 255
          minLength: 2
          type: string
          description: The name of the shop. May differ from legal name.
        partner_shop_id:
          maxLength: 255
          minLength: 1
          type: string
          description: >-
            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.
      description: >-
        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.
    SlangDto:
      type: object
      properties:
        customer_service_contact:
          type: array
          description: >-
            List of 1 to 5 lines with correspondence information. Include how to
            reach customer support.
          items:
            type: string
            description: >-
              List of 1 to 5 lines with correspondence information. Include how
              to reach customer support.
        formal_tone:
          type: string
          description: Formality level for the buyer correspondences.
          enum:
            - FORMAL
            - INFORMAL
        name_format:
          type: string
          description: >-
            Specifies how to visualize the buyer's name after the salutation in
            the buyer correspondences.
          enum:
            - EMTPY
            - FIRST_NAME
            - LAST_NAME
            - FIRST_LAST_NAME
        salutation:
          maxLength: 2147483647
          minLength: 1
          type: string
          description: >-
            Word for salutation in the buyer correspondences in this language,
            e.g. Hi, Hello, Hallo, Guten Tag, etc.
        transaction_type:
          type: string
          description: Specifies how to call the transaction in buyer correspondences.
          enum:
            - ORDER
            - BOOKING
    SlangsDto:
      type: object
      properties:
        de:
          $ref: '#/components/schemas/SlangDto'
        en:
          $ref: '#/components/schemas/SlangDto'
        fr:
          $ref: '#/components/schemas/SlangDto'
        nl:
          $ref: '#/components/schemas/SlangDto'
      description: Language settings for buyer correspondences.
    SpecialItemDto:
      required:
        - gross_unit_price
        - name
        - quantity
        - tax_rate
      type: object
      properties:
        article_number:
          maxLength: 255
          minLength: 0
          pattern: ^.*[\S].*$
          type: string
          description: >-
            The article number of the item, e.g. SKU. Not allowed to contain
            only whitespaces.
        category:
          maxLength: 511
          minLength: 0
          type: string
          description: Category for the item.
        description:
          maxLength: 511
          minLength: 0
          type: string
          description: Description of the item.
        gross_total_price:
          type: number
          description: >-
            Gross value including discount of these items after taxes.
            gross_total_price = (gross_unit_price + gross_unit_discount) *
            quantity
        gross_unit_discount:
          type: number
          description: >-
            Gross discount on one item after taxes. Needs to be a negative
            value.
        gross_unit_price:
          type: number
          description: >-
            Gross value of one item before taxes. For the RETURN_FEE type,
            applicable only to the REFUND operation, the value must be negative.
        name:
          type: string
          description: Name of the item.
        net_total_price:
          type: number
          description: >-
            Net value including discount of these items before taxes.
            net_total_price = (net_unit_price + net_unit_discount) * quantity
        net_unit_discount:
          type: number
          description: >-
            Net discount on one item before taxes. **Needs to be a negative
            value.**
        net_unit_price:
          type: number
          description: Net value of one item before taxes.
        quantity:
          type: integer
          description: Ordered quantity of the item.
          format: int32
        tax_rate:
          type: number
          description: Tax rate applicable for the item given in percent.
        unit:
          maxLength: 255
          minLength: 0
          type: string
          description: Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
      description: >-
        List of special items contained in the transaction, e.g. shipping costs
        or discounts.
    UrlData:
      type: object
      properties:
        success_url:
          type: string
          description: >-
            The location where the buyer should be redirected to, when the
            transaction succeeds
        cancel_url:
          type: string
          description: >-
            The location where the buyer should be redirected to, when the
            transaction gets canceled.
        failure_url:
          type: string
          description: >-
            The location where the buyer should be redirected to, when the
            transaction fails. 
        webhook_url:
          type: string
          description: >-
            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.
    VatDto:
      required:
        - net_amount
        - tax_amount
        - tax_rate
      type: object
      properties:
        net_amount:
          type: number
          description: The net amount before taxes for the given tax rate.
        tax_amount:
          type: number
          description: The tax amount for the given tax rate.
        tax_rate:
          type: number
          description: Tax rate given as percentage on the net amount.
      description: List of value-added tax (VAT) amounts.
    NotFoundErrorResponse:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          description: |2-

                    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
    UnauthorizedErrorResponse:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          description: |2-

                    INVALID_TOKEN: The provided token is invalid or expired.
                          
                
          enum:
            - INVALID_TOKEN
    UnprocessableEntityErrorResponse:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          description: |2-

                    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
    SessionCreatedResponseDto:
      required:
        - landing_page
      type: object
      properties:
        session_id:
          type: string
        landing_page:
          type: string
    DeclineDto:
      type: object
      properties:
        category:
          type: string
        reasons:
          type: array
          items:
            type: string
    SessionRecordDto:
      required:
        - session_id
        - session_status
      type: object
      properties:
        session_id:
          type: string
          description: >-
            The identifier of the interaction with the user within the scope of
            the Hosted Payment Page
        transaction_id:
          type: string
          description: The transaction identifier in Ratepay
        partner_transaction_id:
          type: string
          description: The transaction identifier on the merchant side
        shop_buyer_id:
          type: string
          description: The buyer identifier on the merchant side
        session_status:
          type: string
          enum:
            - CREATED
            - IN_PROGRESS
            - COMPLETED
            - ERROR
            - EXPIRED
            - CANCELED
            - FRAUD_CANCELLATION_REQUESTED
            - OTP_PENDING
        decline_reasons:
          $ref: '#/components/schemas/DeclineDto'
        created_date:
          type: string
          description: The date and time when the status was first created
        updated_date:
          type: string
          description: The date and time when the status was last updated
  securitySchemes:
    Bearer Authentication:
      bearerFormat: JWT
      description: >-
        For each request, a valid access token must be provided in the
        Authorization header. See [Authentication
        API](/docs/developer/authentication/authentication/) for obtaining a
        valid token.
      scheme: bearer
      type: http
