openapi: 3.0.1
info:
  contact:
    email: info@ratepay.com
    name: Ratepay
    url: https://www.ratepay.com/
  description: >-
    This is the documentation for the Ratepay Payment API v2. The API is still
    in development and subject to change. The documentation will evolve as the
    development of the API progresses.
  title: Payment OpenAPI Specification
  version: version 2
servers:
  - description: Ratepay Integration Platform
    url: https://api-integration.ratepay.com/transaction/management
  - description: Ratepay Production Platform
    url: https://api.ratepay.com/transaction/management
security:
  - Bearer Authentication: []
paths:
  /v2/transactions:
    post:
      description: Perform an authorization request for a transaction.
      operationId: createTransaction
      parameters:
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource. If not provided, the response will only contain the
            minimal set of attributes .
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                $ref: >-
                  #/components/schemas/AuthorizationTransactionMinimalResponseDto
          description: Transaction authorized
        '202':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/TransactionMinimalResponseDtoOtpRequired'
          description: >-
            Transaction pre-authorized — buyer OTP verification required to
            complete payment
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TransactionBadRequestErrorDto'
          description: Bad request
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TransactionCreateRejectedErrorResponseDto'
          description: Transaction declined
        '500':
          description: Technical problem
      summary: Authorize transaction
      tags:
        - Transaction management
  /v2/transactions/{ratepay_transaction_id}:
    get:
      description: >-
        Retrieve attributes of an existing transaction including list of
        follow-up operations.
      operationId: getTransaction
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LookupTransactionMinimalResponseDto'
                  - $ref: '#/components/schemas/LookupTransactionFullResponseDto'
          description: Transaction retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve transaction
      tags:
        - Transaction management
    patch:
      description: Change attributes of an existing transaction.
      operationId: change
      parameters:
        - description: >-
            ID of transaction to change. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ChangeDto'
        required: true
      responses:
        '204':
          content:
            '*/*':
              schema:
                type: object
          description: Transaction changed
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ChangeRejectedErrorResponseDto'
          description: Change declined
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Change transaction
      tags:
        - Transaction management
  /v2/transactions/{ratepay_transaction_id}/authorizations:
    get:
      description: >-
        Retrieve all authorization resources of an existing transaction
        including their attributes.
      operationId: getAllAuthorizations
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/LookupAllIncrementalAuthsMinimalResponseDto
                  - $ref: >-
                      #/components/schemas/LookupAllIncrementalAuthsFullResponseDto
          description: Authorizations retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve all authorizations
      tags:
        - Incremental authorization
    post:
      description: Increase the amount of a previously authorized transaction
      operationId: incrementalAuthorizationTransaction
      parameters:
        - description: >-
            ID of transaction to extend with additional authorization. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncrementalAuthorizationRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                $ref: >-
                  #/components/schemas/IncrementalAuthorizationMinimalResponseDto
          description: Authorization created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: >-
                  #/components/schemas/IncrementalAuthorizationCreateRejectedErrorResponseDto
          description: Authorization declined
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Incrementally authorize transaction
      tags:
        - Incremental authorization
  /v2/transactions/{ratepay_transaction_id}/authorizations/{ratepay_authorization_id}:
    get:
      description: >-
        Retrieve an authorization resource of an existing transaction including
        its attributes.
      operationId: getSingleAuthorization
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            ID of authorization to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_authorization_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/IncrementalAuthorizationMinimalResponseDto
                  - $ref: >-
                      #/components/schemas/IncrementalAuthorizationFullResponseDto
          description: Authorization retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve an authorization
      tags:
        - Incremental authorization
  /v2/transactions/{ratepay_transaction_id}/cancellations:
    get:
      description: >-
        Retrieve all cancellation resources of an existing transaction including
        their attributes.
      operationId: getAllCancellations
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/LookupAllCancellationsMinimalResponseDto
                  - $ref: '#/components/schemas/LookupAllCancellationsFullResponseDto'
          description: Cancellations retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve all cancellations
      tags:
        - Cancellation
    post:
      description: Cancel a previously authorized transaction
      operationId: cancelTransaction
      parameters:
        - description: >-
            ID of transaction to cancel. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancellationRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CancellationMinimalResponseDto'
                  - $ref: '#/components/schemas/CancellationFullResponseDto'
          description: Cancellation created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CancellationRejectedErrorResponseDto'
          description: Cancellation declined
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Cancel transaction
      tags:
        - Cancellation
  /v2/transactions/{ratepay_transaction_id}/cancellations/{ratepay_cancellation_id}:
    get:
      description: >-
        Retrieve a cancellation resource of an existing transaction including
        its attributes.
      operationId: getSingleCancellation
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            ID of cancellation to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_cancellation_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CancellationMinimalResponseDto'
                  - $ref: '#/components/schemas/CancellationFullResponseDto'
          description: Cancellation retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve a cancellation
      tags:
        - Cancellation
  /v2/transactions/{ratepay_transaction_id}/captures:
    get:
      description: >-
        Retrieve all capture resources of an existing transaction including
        their attributes.
      operationId: getAllCaptures
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LookupAllCapturesMinimalResponseDto'
                  - $ref: '#/components/schemas/LookupAllCapturesFullResponseDto'
          description: Captures retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve all captures
      tags:
        - Capture
    post:
      description: Capture a previously authorized transaction
      operationId: captureTransaction
      parameters:
        - description: >-
            ID of transaction to capture. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CaptureMinimalResponseDto'
                  - $ref: '#/components/schemas/CaptureFullResponseDto'
          description: Capture created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CaptureCreateRejectedErrorResponseDto'
          description: Capture declined
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Capture transaction
      tags:
        - Capture
  /v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}:
    get:
      description: >-
        Retrieve a capture resource of an existing transaction including its
        attributes.
      operationId: getSingleCapture
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            ID of capture to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_capture_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CaptureMinimalResponseDto'
                  - $ref: '#/components/schemas/CaptureFullResponseDto'
          description: Capture retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve a capture
      tags:
        - Capture
  /v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}/shipping-information:
    post:
      description: Add shipping information to previously captured transaction
      operationId: addShippingInformation
      parameters:
        - description: >-
            ID of transaction. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            ID of capture the shipping information should be added to. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_capture_id
          required: true
          schema:
            type: string
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingInformationRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ShippingInformationMinimalResponseDto'
          description: Shipping information added
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction or capture not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Add shipping information
      tags:
        - Shipping information
  /v2/transactions/{ratepay_transaction_id}/refunds:
    get:
      description: >-
        Retrieve all refund resources of an existing transaction including their
        attributes.
      operationId: getAllRefunds
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LookupAllRefundsMinimalResponseDto'
                  - $ref: '#/components/schemas/LookupAllRefundsFullResponseDto'
          description: Refunds retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve all refunds
      tags:
        - Refund
    post:
      description: Refund a previously authorized and captured transaction
      operationId: refundTransaction
      parameters:
        - description: >-
            ID of transaction to refund. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            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](/docs/developer/api_integration/payment_2.0/idempotency/)
            for further details.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 64
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequestDto'
        required: true
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RefundMinimalResponseDto'
                  - $ref: '#/components/schemas/RefundFullResponseDto'
          description: Refund created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/RefundCreateRejectedErrorResponseDto'
          description: Refund declined
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Refund transaction
      tags:
        - Refund
  /v2/transactions/{ratepay_transaction_id}/refunds/{ratepay_refund_id}:
    get:
      description: >-
        Retrieve a refund resource of an existing transaction including its
        attributes.
      operationId: getSingleRefund
      parameters:
        - description: >-
            ID of transaction to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_transaction_id
          required: true
          schema:
            type: string
        - description: >-
            ID of refund to retrieve. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          in: path
          name: ratepay_refund_id
          required: true
          schema:
            type: string
        - description: >-
            According to RFC 7240: Provide `return=representation` if you prefer
            that the response to a request includes the current state of the
            resource.
          in: header
          name: Prefer
          required: false
          schema:
            type: string
            enum:
              - return=representation
        - description: >-
            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.
          in: header
          name: X-Partner
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RefundMinimalResponseDto'
                  - $ref: '#/components/schemas/RefundFullResponseDto'
          description: Refund retrieved
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseDto'
          description: Bad request
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
          description: Transaction not found
        '451':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/LegalErrorResponseDto'
          description: Legally not allowed
        '500':
          description: Technical problem
      summary: Retrieve a refund
      tags:
        - Refund
components:
  schemas:
    AddressDto:
      type: object
      description: The address of the recipient.
      properties:
        city:
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
          example: Berlin
          maxLength: 100
          minLength: 2
        country_code:
          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
          pattern: '[A-Z]{2}'
        street:
          type: string
          description: The name of the street.
          example: Schönhauser Allee
          maxLength: 100
          minLength: 1
        street_addition:
          type: string
          description: >-
            Additional information about the address, e.g. 2nd floor, c/o John
            Doe.
          example: Seitenflügel, 2. HH
          maxLength: 50
          minLength: 1
        street_number:
          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'
          maxLength: 30
          minLength: 1
        zip_code:
          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'
          maxLength: 10
          minLength: 1
      required:
        - city
        - country_code
        - street
        - zip_code
    BadRequestDeclineDto:
      type: object
      description: Information about why transaction was not accepted and declined.
      properties:
        category:
          type: string
          description: >-
            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
          example: SYNTAX
        invalid_fields:
          type: array
          description: >-
            List of one or multiple entries describing each failed validation.
            Only present if reason is `INVALID_FIELDS`.
          items:
            $ref: '#/components/schemas/InvalidField'
        reasons:
          type: array
          description: >-
            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.
          example:
            - INVALID_FIELDS
          items:
            type: string
            description: >-
              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
            example: '["INVALID_FIELDS"]'
      required:
        - category
        - reasons
    BadRequestErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/BadRequestDeclineDto'
      required:
        - decline
    BankDetailsRequestDto:
      type: object
      description: >-
        The bank account Ratepay will use to deduct captured transaction
        amounts. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.
      properties:
        bic:
          type: string
          description: >-
            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
          pattern: '[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?'
        iban:
          type: string
          description: >-
            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
          maxLength: 34
          minLength: 15
        owner:
          type: string
          description: Owner of the bank account.
          example: Heinz Steeger
          maxLength: 100
          minLength: 1
          pattern: '[A-Za-zäöüÄÖÜß0-9/.,+\- ]*'
      required:
        - iban
        - owner
    BankDetailsResponseDto:
      type: object
      description: >-
        The bank account the buyer has to transfer the money to. Applicable only
        in case of transfer type BANK_TRANSFER.
      properties:
        bank_name:
          type: string
          description: Name of the bank.
          example: Example Bank
          maxLength: 127
        bic:
          type: string
          description: >-
            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
          pattern: '[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?'
        iban:
          type: string
          description: >-
            IBAN of the bank account. Format as specified by [ISO
            13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
          example: DE12345678901234567890
          maxLength: 34
          minLength: 15
        owner:
          type: string
          description: Owner of the bank account.
          example: Ratepay GmbH
          maxLength: 100
          pattern: '[A-Za-zäöüÄÖÜß0-9/.,+\- ]*'
      required:
        - bank_name
        - bic
        - iban
        - owner
    BrandingSettingsDto:
      type: object
      description: Shop branding settings for buyer correspondences.
      properties:
        highlight_color:
          type: string
          description: >-
            The color for the highlighted elements in buyer correspondences as
            HTML HEX color code, e.g. `#BADB11`.
          example: '#badb11'
          pattern: '#[a-fA-F0-9]{6}'
        logo_position:
          type: string
          description: Shop logo position in buyer correspondences.
          enum:
            - LEFT
            - RIGHT
            - CENTER
          example: RIGHT
        logo_url:
          type: string
          description: >-
            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
    BrowserDto:
      type: object
      description: The browser used by the buyer.
      properties:
        language:
          type: string
          description: >-
            The language used by the browser. Must conform to [BCP
            47](https://en.wikipedia.org/wiki/IETF_language_tag).
          example: de-DE
          pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2})?$
        name:
          type: string
          description: The name of the used browser.
          example: Mozilla Firefox
          maxLength: 255
          minLength: 1
        version:
          type: string
          description: The version of the used browser.
          example: 94.0 (64-bit)
          maxLength: 255
          minLength: 1
    BuyerDto:
      type: object
      description: The buyer that wants to place the transaction.
      properties:
        billing_address:
          $ref: '#/components/schemas/AddressDto'
        contact:
          $ref: '#/components/schemas/ContactDto'
        language:
          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-1_codes).
          example: de
          pattern: '[a-z]{2}'
        shop_buyer_id:
          type: string
          description: >-
            The unique buyer ID to identify a regular customer. See [regular
            customer
            documentation](/docs/reporting/regular_customers/regular_customers_introduction/)
            for details. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: shop-buyer-id-1234
          maxLength: 100
          minLength: 1
      required:
        - billing_address
        - contact
      oneOf:
        - title: B2C
          description: >-
            B2C transaction. Provide a person for individual buyers. Either
            provide a person or company but not both.
          properties:
            person:
              $ref: '#/components/schemas/PersonDto'
          required:
            - person
        - title: B2B
          description: >-
            B2B transaction. Provide a company for business buyers. Either
            provide a person or company but not both.
          properties:
            company:
              $ref: '#/components/schemas/CompanyDto'
          required:
            - company
    CancellationFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of cancellation.
      properties:
        _links:
          $ref: '#/components/schemas/CancellationLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        gross_amount:
          type: number
          description: Amount to cancel given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of cancelled items
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: cancel-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        ratepay_cancellation_id:
          type: string
          description: >-
            ID of confirmed cancellation (generated by Ratepay). Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: aa7rth5-__GG44rdsasf
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        special_items:
          type: array
          description: List of cancelled special items, 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'
      required:
        - _links
        - created
        - gross_amount
        - ratepay_cancellation_id
    CancellationLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/CancellationSelfLink'
      required:
        - self
    CancellationMinimalResponseDto:
      type: object
      description: >-
        Includes only minimal set of attributes generated by Ratepay during
        cancellation creation.
      properties:
        _links:
          $ref: '#/components/schemas/CancellationLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        ratepay_cancellation_id:
          type: string
          description: >-
            ID of confirmed cancellation generated by Ratepay. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: aa7rth5-__GG44rdsasf
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - created
        - ratepay_cancellation_id
    CancellationRejectedDeclineDto:
      type: object
      properties:
        category:
          type: string
          description: >-
            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
          example: UNPROCESSABLE_OPERATION
        reasons:
          type: array
          description: >-
            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.
          example:
            - CANCELLATION_AMOUNT_TOO_HIGH
          items:
            type: string
            description: >-
              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
            example: '["CANCELLATION_AMOUNT_TOO_HIGH"]'
      required:
        - category
    CancellationRejectedErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/CancellationRejectedDeclineDto'
      required:
        - decline
    CancellationRequestDto:
      type: object
      properties:
        gross_amount:
          type: number
          description: Amount to cancel given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of cancelled items
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: cancel-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        special_items:
          type: array
          description: List of cancelled special items, 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'
      required:
        - gross_amount
    CancellationSelfLink:
      type: object
      description: The self relation identifying the cancellation resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/cancellations/aa7rth5-__GG44rdsasf
      required:
        - href
    CaptureCreateRejectedDeclineDto:
      type: object
      properties:
        category:
          type: string
          description: >-
            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
          example: UNPROCESSABLE_OPERATION
        reasons:
          type: array
          description: >-
            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.
          example:
            - CAPTURE_AMOUNT_TOO_HIGH
          items:
            type: string
            description: >-
              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
            example: '["CAPTURE_AMOUNT_TOO_HIGH"]'
      required:
        - category
    CaptureCreateRejectedErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/CaptureCreateRejectedDeclineDto'
      required:
        - decline
    CaptureFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of capture.
      properties:
        _links:
          $ref: '#/components/schemas/CaptureLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        gross_amount:
          type: number
          description: Amount to capture given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of captured items.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_invoice_id:
          type: string
          description: Arbitrary invoice ID generated by partner.
          example: partner-invoice-id-1234
          maxLength: 50
          minLength: 0
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: capture-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        partner_transaction_id:
          type: string
          description: >
            The transaction ID generated by the partner (i.e. Partner Order ID).
            Use the same value as shop_transaction_id unless the shop and
            integration partner manage separate transaction IDs, such as in PSP
            (payment service provider) integrations. **This field must be
            included in at least one of the following requests: authorization or
            capture.** This ID can be displayed in settlement reports. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-transaction-id-1234
          maxLength: 50
          minLength: 1
        ratepay_capture_id:
          type: string
          description: >-
            ID of confirmed capture (generated by Ratepay). Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: BFNpWnim6LUDFQA8x3VN
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        shop_transaction_id:
          type: string
          description: >
            The transaction ID generated by the shop (i.e. Shop Order ID).
            Differs from partner_transaction_id only in PSP (payment service
            provider) scenarios. **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
          maxLength: 127
          minLength: 1
        special_items:
          type: array
          description: List of captured special items, 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'
      required:
        - _links
        - created
        - gross_amount
        - ratepay_capture_id
    CaptureLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/CaptureSelfLink'
      required:
        - self
    CaptureMinimalResponseDto:
      type: object
      description: >-
        Includes only minimal set of attributes generated by Ratepay during
        capture creation.
      properties:
        _links:
          $ref: '#/components/schemas/CaptureLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        ratepay_capture_id:
          type: string
          description: >-
            ID of confirmed capture (generated by Ratepay). Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: BFNpWnim6LUDFQA8x3VN
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - created
        - ratepay_capture_id
    CaptureRequestDto:
      type: object
      properties:
        gross_amount:
          type: number
          description: Amount to capture given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of captured items.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_invoice_id:
          type: string
          description: Arbitrary invoice ID generated by partner.
          example: partner-invoice-id-1234
          maxLength: 50
          minLength: 0
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: capture-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        partner_transaction_id:
          type: string
          description: >
            The transaction ID generated by the partner (i.e. Partner Order ID).
            Use the same value as shop_transaction_id unless the shop and
            integration partner manage separate transaction IDs, such as in PSP
            (payment service provider) integrations. **This field must be
            included in at least one of the following requests: authorization or
            capture.** This ID can be displayed in settlement reports. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-transaction-id-1234
          maxLength: 50
          minLength: 1
        shop_transaction_id:
          type: string
          description: >
            The transaction ID generated by the shop (i.e. Shop Order ID).
            Differs from partner_transaction_id only in PSP (payment service
            provider) scenarios. **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
          maxLength: 127
          minLength: 1
        special_items:
          type: array
          description: List of captured special items, 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'
      required:
        - gross_amount
        - shop_transaction_id
        - partner_transaction_id
    CaptureSelfLink:
      type: object
      description: The self relation identifying the capture resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN
      required:
        - href
    ChangeDto:
      type: object
      properties:
        authorization_expires:
          type: string
          format: date-time
          description: Timestamp when the transaction should expire.
          example: '2025-04-02T16:15:18.823+02:00'
      required:
        - authorization_expires
    ChangeRejectedErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: >-
            #/components/schemas/UnprocessableOperationNotAllowedForDeclinedTransaction
      required:
        - decline
    CompanyDto:
      type: object
      description: >-
        The company that wants to place the transaction. This implies a B2B
        transaction. Either provide a person or company but not both.
      properties:
        first_name:
          type: string
          description: The first name of the contact person within the company.
          example: Heinz
          maxLength: 100
          minLength: 1
        last_name:
          type: string
          description: The last name of the contact person within the company.
          example: Steeger
          maxLength: 100
          minLength: 1
        name:
          type: string
          description: Official company name, should include legal form if applicable.
          example: Berlin Advertising Agency GmbH
          maxLength: 100
          minLength: 1
        vat_id:
          type: string
          description: >-
            Value-added tax ID of the company. This can be a European VAT ID or
            a local one.
          example: DE123456789
          maxLength: 20
          minLength: 1
      required:
        - name
    ContactDto:
      type: object
      description: The contact information of the buyer.
      properties:
        email:
          type: string
          description: The email address of the buyer.
          example: heinz.steeger@example.org
          maxLength: 100
          minLength: 1
          pattern: >-
            [A-Za-z0-9!#$%&amp;'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&amp;'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?
        phone:
          type: string
          description: >-
            The phone number of the buyer. Has to have at least 6 digits without
            spaces.
          example: +49 177 44455553
          maxLength: 60
          minLength: 6
          pattern: '[+0-9/\\\- ().,;]*[0-9][+0-9/\\\- ().,;]*'
      required:
        - email
        - phone
    CorrespondenceSettingsDto:
      type: object
      description: Settings for buyer correspondences.
      properties:
        branding_settings:
          $ref: '#/components/schemas/BrandingSettingsDto'
        slangs:
          $ref: '#/components/schemas/SlangsDto'
    DeclineDto:
      type: object
      description: Information about why transaction was not accepted and declined.
      properties:
        category:
          type: string
          description: >-
            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
          example: BUYER_DATA
        reasons:
          type: array
          description: >-
            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.
          example:
            - INVALID_BILLING_ADDRESS
          items:
            type: string
            description: >-
              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
            example: '["INVALID_BILLING_ADDRESS"]'
      required:
        - category
        - reasons
    DeliveryDto:
      type: object
      description: The delivery address and additional delivery parameters.
      properties:
        first_name:
          type: string
          description: >-
            The first name of the recipient. If supplied together with
            `last_name`, `full_name` will be ignored if also provided.
          example: Heinz
          maxLength: 100
          minLength: 1
        full_name:
          type: string
          description: >-
            The full name of the recipient. This is used only when `first_name`
            and `last_name` are not provided.
          maxLength: 200
          minLength: 1
        last_name:
          type: string
          description: >-
            The last name of the recipient. If supplied together with
            `first_name`, `full_name` will be ignored if also provided.
          example: Steeger
          maxLength: 100
          minLength: 1
      oneOf:
        - title: Regular delivery
          description: Standard delivery to an address.
          properties:
            address:
              $ref: '#/components/schemas/AddressDto'
          required:
            - address
        - title: In-Store Collect
          description: >-
            Collect in-store. Only one of address, in_store_collect,
            pick_up_box, or pick_up_shop may be provided.
          properties:
            in_store_collect:
              $ref: '#/components/schemas/InStoreCollectDto'
          required:
            - in_store_collect
        - title: Pick-Up Box
          description: >-
            Delivery to a pick-up box (e.g. DHL Packstation). Only one of
            address, in_store_collect, pick_up_box, or pick_up_shop may be
            provided.
          properties:
            pick_up_box:
              $ref: '#/components/schemas/PickUpBoxDto'
          required:
            - pick_up_box
        - title: Pick-Up Shop
          description: >-
            Delivery to a pick-up shop. Only one of address, in_store_collect,
            pick_up_box, or pick_up_shop may be provided.
          properties:
            pick_up_shop:
              $ref: '#/components/schemas/PickUpShopDto'
          required:
            - pick_up_shop
    DeviceDto:
      type: object
      description: The device used to initiate the transaction.
      properties:
        browser:
          $ref: '#/components/schemas/BrowserDto'
        geo_location:
          $ref: '#/components/schemas/GeoLocationDto'
        http_forwarded_ip_address:
          type: string
          description: >-
            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
          maxLength: 255
          minLength: 1
        risk:
          $ref: '#/components/schemas/RiskDto'
        screen:
          $ref: '#/components/schemas/ScreenDto'
        source_ip_address:
          type: string
          description: >-
            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
          maxLength: 255
          minLength: 1
      oneOf:
        - title: WithToken
          description: >-
            Use this variant when integrating Ratepay's device fingerprinting
            feature. Provide the token generated by the Ratepay script.
          required:
            - token
          properties:
            token:
              type: string
              description: >-
                ID generated using [Ratepay's device fingerprinting
                feature](/docs/developer/device_fingerprinting/device_fingerprinting/).
                Include the generated token if you are using the device
                fingerprinting feature in your integration.
              example: ade028c1-d2a2-4189-9214-e21089cd47f1
              maxLength: 255
              minLength: 1
        - title: WithFingerprint
          description: >-
            Use this variant when NOT using Ratepay's device fingerprinting
            feature. Provide a fingerprint generated by your own system.
          required:
            - finger_print
          properties:
            finger_print:
              type: string
              description: >-
                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/).
              example: bc47575c-7f93-4bae-84dc-282edf6a5d85
              maxLength: 255
              minLength: 1
    DeviceLookupResponseDto:
      type: object
      description: The device used to initiate the transaction.
      properties:
        token:
          type: string
          description: >-
            ID generated using [Ratepay's device fingerprinting
            feature](/docs/developer/device_fingerprinting/device_fingerprinting/).
            Include the generated token if you are using the device
            fingerprinting feature in your integration. 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
          maxLength: 255
          minLength: 1
    GeoLocationDto:
      type: object
      description: The geographical position of the buyer's device.
      properties:
        latitude:
          type: number
          description: The latitude of the geographical position of the buyer's device.
          example: 52.518368
        longitude:
          type: number
          description: The longitude of the geographical position of the buyer's device.
          example: 13.325109
    InStoreCollectDto:
      type: object
      description: The information of the in-store collect.
      properties:
        city:
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
          example: Berlin
          maxLength: 100
          minLength: 2
        country_code:
          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
          pattern: '[A-Z]{2}'
        location_name:
          type: string
          description: The name of the collection location.
          example: Apotheke am Rathaus
          maxLength: 127
          minLength: 1
        street:
          type: string
          description: The name of the street.
          example: Hauptstraße
          maxLength: 100
          minLength: 1
        street_addition:
          type: string
          description: Additional information about the address.
          maxLength: 50
          minLength: 1
        street_number:
          type: string
          description: The number describing where the building is located in the street.
          example: '22'
          maxLength: 30
          minLength: 1
        zip_code:
          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'
          maxLength: 10
          minLength: 1
      required:
        - city
        - country_code
        - street
        - zip_code
    IncrementalAuthorizationCreateRejectedDeclineDto:
      type: object
      properties:
        category:
          type: string
          description: >-
            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
          example: UNPROCESSABLE_OPERATION
        reasons:
          type: array
          description: >-
            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.
          example:
            - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
          items:
            type: string
            description: >-
              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
            example: '["SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT"]'
      required:
        - category
    IncrementalAuthorizationCreateRejectedErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: >-
            #/components/schemas/IncrementalAuthorizationCreateRejectedDeclineDto
      required:
        - decline
    IncrementalAuthorizationFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of authorization.
      properties:
        _links:
          $ref: '#/components/schemas/IncrementalAuthorizationLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        gross_amount:
          type: number
          description: Amount to increase given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of items to add.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: authorization-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        ratepay_authorization_id:
          type: string
          description: >-
            ID of confirmed authorization (generated by Ratepay). Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: 9wdn0Fvkb9Zxsfiql5l6
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        special_items:
          type: array
          description: List of special items to add, 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'
      required:
        - _links
        - created
        - gross_amount
        - ratepay_authorization_id
    IncrementalAuthorizationLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/IncrementalAuthorizationSelfLink'
      required:
        - self
    IncrementalAuthorizationMinimalResponseDto:
      type: object
      description: >-
        Includes only minimal set of attributes generated by Ratepay during
        authorization creation.
      properties:
        _links:
          $ref: '#/components/schemas/IncrementalAuthorizationLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        ratepay_authorization_id:
          type: string
          description: >-
            ID of confirmed authorization generated by Ratepay. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: 9wdn0Fvkb9Zxsfiql5l6
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - created
        - ratepay_authorization_id
    IncrementalAuthorizationRequestDto:
      type: object
      properties:
        gross_amount:
          type: number
          description: Amount to increase given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of items to add.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: authorization-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        special_items:
          type: array
          description: List of special items to add, 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'
      required:
        - gross_amount
    IncrementalAuthorizationSelfLink:
      type: object
      description: The self relation identifying the authorization resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/authorizations/9wdn0Fvkb9Zxsfiql5l6
      required:
        - href
    InvalidField:
      type: object
      description: >-
        List of one or multiple entries describing each failed validation. Only
        present if reason is `INVALID_FIELDS`.
      properties:
        json_path:
          type: string
          description: The JSON path pointing to the location where the validation failed.
          example: partner_operation_id
        message:
          type: string
          description: A message describing which constraint was violated.
          example: size must be between 0 and 255
      required:
        - json_path
        - message
    ItemDto:
      type: object
      description: List of items to add.
      properties:
        article_number:
          type: string
          description: >-
            The article number of the item, e.g. SKU. Not allowed to contain
            only whitespaces.
          example: kitchen-utils-1
          maxLength: 255
          minLength: 1
          pattern: .*[\S].*
        category:
          type: string
          description: Category for the item.
          example: household
          maxLength: 511
          minLength: 0
        description:
          type: string
          description: Description of the item.
          example: fruit knife with curved blade, 8 cm
          maxLength: 511
          minLength: 0
        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
          example: 33.8
          multipleOf: 0.01
        gross_unit_discount:
          type: number
          description: >-
            Gross discount on one item after taxes. Needs to be a negative
            value.
          example: -1.55
          exclusiveMaximum: false
          maximum: 0
          multipleOf: 0.01
        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.
          example: 18.45
          multipleOf: 0.01
        name:
          type: string
          description: Name of the item.
          example: fruit knife
          maxLength: 255
          minLength: 1
        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
          example: 28.4
          multipleOf: 0.01
        net_unit_discount:
          type: number
          description: Net discount on one item before taxes. Needs to be a negative value.
          example: -1.3
          exclusiveMaximum: false
          maximum: 0
          multipleOf: 0.01
        net_unit_price:
          type: number
          description: Net value of one item before taxes.
          example: 15.5
          multipleOf: 0.01
        quantity:
          type: number
          description: Ordered quantity of the item.
          example: 2
          exclusiveMinimum: false
          minimum: 0
          multipleOf: 1.e-10
        tax_rate:
          type: number
          description: Tax rate applicable for the item given in percent.
          example: 19
          exclusiveMaximum: true
          exclusiveMinimum: false
          maximum: 1000
          minimum: 0
          multipleOf: 0.01
        unit:
          type: string
          description: Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
          example: piece
          maxLength: 255
          minLength: 0
      required:
        - gross_unit_price
        - name
        - quantity
        - tax_rate
    LegalDeclineDto:
      type: object
      description: Information about why transaction was not accepted and declined.
      properties:
        category:
          type: string
          description: >-
            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
          example: LEGAL
        reasons:
          type: array
          description: >-
            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.
          example:
            - ANONYMIZED_BY_BUYER
          items:
            type: string
            description: >-
              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
            example: '["ANONYMIZED_BY_BUYER"]'
      required:
        - category
        - reasons
    LegalErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/LegalDeclineDto'
      required:
        - decline
    LookupAllCancellationsFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of all cancellations.
      properties:
        _embedded:
          type: object
          properties:
            cancellations:
              type: array
              description: Embedded list of cancellations.
              items:
                $ref: '#/components/schemas/CancellationFullResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllCancellationsMinimalResponseDto:
      type: object
      description: Includes only minimal set of attributes generated by Ratepay.
      properties:
        _embedded:
          type: object
          properties:
            cancellations:
              type: array
              description: Embedded list of cancellations.
              items:
                $ref: '#/components/schemas/CancellationMinimalResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllCapturesFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of all captures.
      properties:
        _embedded:
          type: object
          properties:
            captures:
              type: array
              description: Embedded list of captures.
              items:
                $ref: '#/components/schemas/CaptureFullResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllCapturesMinimalResponseDto:
      type: object
      description: Includes only minimal set of attributes generated by Ratepay.
      properties:
        _embedded:
          type: object
          properties:
            captures:
              type: array
              description: Embedded list of captures.
              items:
                $ref: '#/components/schemas/CaptureMinimalResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllIncrementalAuthsFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of all incremental auths.
      properties:
        _embedded:
          type: object
          properties:
            authorizations:
              type: array
              description: Embedded list of incremental auths.
              items:
                $ref: '#/components/schemas/IncrementalAuthorizationFullResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllIncrementalAuthsMinimalResponseDto:
      type: object
      description: Includes only minimal set of attributes generated by Ratepay.
      properties:
        _embedded:
          type: object
          properties:
            authorizations:
              type: array
              description: Embedded list of incremental auths.
              items:
                $ref: >-
                  #/components/schemas/IncrementalAuthorizationMinimalResponseDto
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllRefundsFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of all refunds.
      properties:
        _embedded:
          type: object
          properties:
            refunds:
              type: array
              description: Embedded list of refunds.
              items:
                $ref: '#/components/schemas/RefundFullResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupAllRefundsMinimalResponseDto:
      type: object
      description: Includes only minimal set of attributes generated by Ratepay.
      properties:
        _embedded:
          type: object
          properties:
            refunds:
              type: array
              description: Embedded list of refunds.
              items:
                $ref: '#/components/schemas/RefundMinimalResponseDto'
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - ratepay_transaction_id
    LookupTransactionFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of transaction plus links to related
        resources. Note that in case of a declined transaction, all attributes
        are optional as they may have not been present in the original request
        due to syntax error.
      properties:
        _links:
          $ref: '#/components/schemas/LookupTransactionLinks'
        authorization_expires:
          type: string
          format: date-time
          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).
          example: '2025-04-02T16:15:18.823+02:00'
        buyer:
          $ref: '#/components/schemas/BuyerDto'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        currency:
          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).
          example: EUR
          pattern: '[A-Z]{3}'
        decline:
          $ref: '#/components/schemas/DeclineDto'
        delivery:
          $ref: '#/components/schemas/DeliveryDto'
        device:
          $ref: '#/components/schemas/DeviceLookupResponseDto'
        options:
          $ref: '#/components/schemas/OptionsDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-operation-id-1234
          maxLength: 255
        partner_transaction_id:
          type: string
          description: >-
            The transaction ID generated by the partner (i.e. Partner Order ID).
            Use the same value as shop_transaction_id unless the shop and
            integration partner manage separate transaction IDs, such as in PSP
            (payment service provider) integrations. This field must be included
            in at least one of the following requests: authorization or capture.
            This ID can be displayed in settlement reports. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-transaction-id-1234
          maxLength: 50
          minLength: 1
        payment_details:
          $ref: '#/components/schemas/PaymentDetailsFullResponseDto'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodDto'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        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](/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/ShopLookupResponseDto'
      required:
        - _links
        - created
        - ratepay_transaction_id
    LookupTransactionLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        authorizations:
          type: array
          description: >-
            List of additional authorization resources belonging to this
            transaction.
          items:
            $ref: '#/components/schemas/IncrementalAuthorizationSelfLink'
        cancellations:
          type: array
          description: List of cancellation resources belonging to this transaction.
          items:
            $ref: '#/components/schemas/CancellationSelfLink'
        captures:
          type: array
          description: List of capture resources belonging to this transaction.
          items:
            $ref: '#/components/schemas/CaptureSelfLink'
        refunds:
          type: array
          description: List of refund resources belonging to this transaction.
          items:
            $ref: '#/components/schemas/RefundSelfLink'
        self:
          $ref: '#/components/schemas/TransactionSelfLink'
      required:
        - authorizations
        - cancellations
        - captures
        - refunds
        - self
    LookupTransactionMinimalResponseDto:
      type: object
      description: Includes only minimal set of attributes plus links to related resources.
      properties:
        _links:
          $ref: '#/components/schemas/LookupTransactionLinks'
        authorization_expires:
          type: string
          format: date-time
          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).
          example: '2025-04-02T16:15:18.823+02:00'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        decline:
          $ref: '#/components/schemas/DeclineDto'
        payment_details:
          $ref: '#/components/schemas/PaymentDetailsMinimalResponseDto'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        result:
          $ref: '#/components/schemas/TransactionStatus'
      required:
        - _links
        - created
        - ratepay_transaction_id
        - result
    MerchantDto:
      type: 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.
      properties:
        merchant_id:
          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](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in the payment API 2.0 for more details.
          example: ratepay-merchant-id-123
          maxLength: 255
          minLength: 1
        merchant_name:
          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.
          example: Merchant XYZ
          maxLength: 255
          minLength: 1
    OptionsDto:
      type: object
      description: The options controlling transaction processing.
      properties:
        sales_channel:
          type: string
          description: The sales channel the transaction originates from.
          enum:
            - WEBSHOP
            - POINT_OF_SALE
            - PHONE_OR_MAIL
          example: POINT_OF_SALE
    PaymentDetailsFullResponseDto:
      type: object
      description: >-
        Provides details about the payment to be either executed by the buyer or
        Ratepay depending on selected payment method.
      properties:
        debit_bank_account:
          $ref: '#/components/schemas/BankDetailsRequestDto'
        deposit_bank_account:
          $ref: '#/components/schemas/BankDetailsResponseDto'
        ratepay_payment_references:
          type: array
          description: List of payment references and the shop they belong to.
          items:
            $ref: '#/components/schemas/PaymentReferenceDto'
    PaymentDetailsMinimalResponseDto:
      type: object
      description: >-
        Provides details about the payment to be either executed by the buyer or
        Ratepay depending on selected payment method.
      properties:
        deposit_bank_account:
          $ref: '#/components/schemas/BankDetailsResponseDto'
        ratepay_payment_references:
          type: array
          description: List of payment references and the shop they belong to.
          items:
            $ref: '#/components/schemas/PaymentReferenceDto'
    PaymentDetailsMinimalResponseLegacyDto:
      type: object
      description: >-
        Provides details about the payment to be executed by the buyer
        (generated by Ratepay).
      properties:
        deposit_bank_account:
          $ref: '#/components/schemas/BankDetailsResponseDto'
        ratepay_payment_reference:
          type: string
          deprecated: true
          description: >-
            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
          maxLength: 127
          minLength: 1
          pattern: '[A-Za-z0-9 /-+]{1,127}'
        ratepay_payment_references:
          type: array
          description: List of payment references and the shop they belong to.
          items:
            $ref: '#/components/schemas/PaymentReferenceDto'
    PaymentDetailsRequestDto:
      type: object
      description: >-
        Provides details about the payment to be executed by Ratepay. Applicable
        only in case of transfer-type SEPA_DIRECT_DEBIT.
      properties:
        debit_bank_account:
          $ref: '#/components/schemas/BankDetailsRequestDto'
      required:
        - debit_bank_account
    PaymentMethodDto:
      type: object
      description: The payment method selected by the buyer.
      properties:
        payment_option:
          type: string
          description: The payment option the buyer selected.
          enum:
            - OPEN_INVOICE
            - PAY_NOW
          example: OPEN_INVOICE
        transfer_type:
          type: string
          description: The transfer type the buyer selected.
          enum:
            - BANK_TRANSFER
            - SEPA_DIRECT_DEBIT
          example: BANK_TRANSFER
      required:
        - payment_option
        - transfer_type
    PaymentReferenceDto:
      type: object
      description: List of payment references and the shop they belong to.
      properties:
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        ratepay_payment_reference:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 1
          pattern: '[A-Za-z0-9 /-+]{1,127}'
      required:
        - partner_shop_id
        - ratepay_payment_reference
    PersonDto:
      type: object
      description: >-
        The person that wants to place the transaction. This implies a B2C
        transaction. Either provide a person or company but not both.
      properties:
        date_of_birth:
          type: string
          format: date
          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).
          example: '1971-05-19'
        first_name:
          type: string
          description: The first name of the person.
          example: Heinz
          maxLength: 100
          minLength: 1
        last_name:
          type: string
          description: The last name of the person.
          example: Steeger
          maxLength: 100
          minLength: 1
        title:
          type: string
          description: The title of the person.
          example: Dr.
          maxLength: 45
          minLength: 1
      required:
        - date_of_birth
        - first_name
        - last_name
    PickUpBoxDto:
      type: object
      description: The information of the pick up box.
      properties:
        carrier_name:
          type: string
          description: The name of the parcel carrier.
          example: DHL
          maxLength: 127
          minLength: 1
        city:
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
          example: Berlin
          maxLength: 100
          minLength: 2
        country_code:
          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
          pattern: '[A-Z]{2}'
        location_id:
          type: string
          description: The ID of pick up location with the carrier.
          example: Packstation 985
          maxLength: 127
          minLength: 1
        recipient_account_id:
          type: string
          description: >-
            The ID of the receiver with the carrier. It is optional only for
            country_code AT, otherwise it is required.
          example: '445522299'
          maxLength: 127
          minLength: 1
        zip_code:
          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'
          maxLength: 10
          minLength: 1
      required:
        - city
        - country_code
        - location_id
        - zip_code
    PickUpShopDto:
      type: object
      description: The information of the pick up shop.
      properties:
        city:
          type: string
          description: >-
            The city of the address. Must be at least 2 non whitespace
            characters.
          example: Berlin
          maxLength: 100
          minLength: 2
        country_code:
          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
          pattern: '[A-Z]{2}'
        location_name:
          type: string
          description: The name of the pick up shop.
          example: Kiosk am Stadtpark
          maxLength: 127
          minLength: 1
        street:
          type: string
          description: The name of the street.
          example: Fichtenweg
          maxLength: 100
          minLength: 1
        street_addition:
          type: string
          description: Additional information about the address.
          maxLength: 50
          minLength: 1
        street_number:
          type: string
          description: The number describing where the building is located in the street.
          example: 2b
          maxLength: 30
          minLength: 1
        zip_code:
          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'
          maxLength: 10
          minLength: 1
      required:
        - city
        - country_code
        - street
        - zip_code
    RefundCreateRejectedDeclineDto:
      type: object
      properties:
        category:
          type: string
          description: >-
            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
          example: UNPROCESSABLE_OPERATION
        reasons:
          type: array
          description: >-
            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.
          example:
            - REFUND_AMOUNT_TOO_HIGH
          items:
            type: string
            description: >-
              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
            example: '["REFUND_AMOUNT_TOO_HIGH"]'
      required:
        - category
    RefundCreateRejectedErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/RefundCreateRejectedDeclineDto'
      required:
        - decline
    RefundFullResponseDto:
      type: object
      description: >-
        This response is returned if representation header is specified.
        Response includes all attributes of refund.
      properties:
        _links:
          $ref: '#/components/schemas/RefundLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        gross_amount:
          type: number
          description: Amount to refund given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of refunded items.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: refund-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        ratepay_refund_id:
          type: string
          description: >-
            ID of confirmed refund (generated by Ratepay). Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: 9FkZsddr-MaFFFx7gAs_
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        special_items:
          type: array
          description: List of refunded special items, 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'
      required:
        - _links
        - created
        - gross_amount
        - ratepay_refund_id
    RefundLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/RefundSelfLink'
      required:
        - self
    RefundMinimalResponseDto:
      type: object
      description: >-
        Includes only minimal set of attributes generated by Ratepay during
        refund creation.
      properties:
        _links:
          $ref: '#/components/schemas/RefundLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        ratepay_refund_id:
          type: string
          description: >-
            ID of confirmed refund generated by Ratepay. Get an [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: 9FkZsddr-MaFFFx7gAs_
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - created
        - ratepay_refund_id
    RefundRequestDto:
      type: object
      properties:
        gross_amount:
          type: number
          description: Amount to refund given in currency of original transaction.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of refunded items.
          items:
            $ref: '#/components/schemas/ItemDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: refund-id-1234
          maxLength: 255
          minLength: 0
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API. This field is required in case of marketplace
            transaction.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        special_items:
          type: array
          description: List of refunded special items, 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'
      required:
        - gross_amount
    RefundSelfLink:
      type: object
      description: The self relation identifying the refund resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/refunds/9FkZsddr-MaFFFx7gAs_
      required:
        - href
    ResourceNotFoundDeclineDto:
      type: object
      description: Information about why transaction was not accepted and declined.
      properties:
        category:
          type: string
          description: >-
            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
          example: RESOURCE_NOT_FOUND
        reasons:
          type: array
          description: >-
            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.
          example:
            - TRANSACTION_NOT_FOUND
          items:
            type: string
            description: >-
              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
            example: '["TRANSACTION_NOT_FOUND"]'
      required:
        - category
        - reasons
    ResourceNotFoundErrorResponseDto:
      type: object
      properties:
        decline:
          $ref: '#/components/schemas/ResourceNotFoundDeclineDto'
      required:
        - decline
    RiskDto:
      type: object
      description: The risk associated with the buyer's device. Can be empty.
      properties:
        reasons:
          type: array
          description: List of reasons for the estimated risk.
          example:
            - HIGH_RISK_DEVICE_BEHAVIOR
          items:
            type: string
            description: List of reasons for the estimated risk.
            enum:
              - LOW_RISK_DEVICE
              - LIMITED_TRUST
              - HIGH_RISK_DEVICE_REPUTATION
              - HIGH_RISK_DEVICE_BEHAVIOR
              - HIGH_RISK_IP_REPUTATION
              - HIGH_RISK_IP_BEHAVIOR
            example: '["HIGH_RISK_DEVICE_BEHAVIOR"]'
            maxLength: 255
            minLength: 1
        score:
          type: integer
          description: A numerical value for the estimated risk.
          example: 123
          maximum: 1000
          minimum: 1
    ScreenDto:
      type: object
      description: The dimensions of the buyer's screen.
      properties:
        height:
          type: integer
          description: The height of the buyer's screen in pixel.
          example: 1080
          maximum: 2147483647
          minimum: 0
        width:
          type: integer
          description: The width of the buyer's screen in pixel.
          example: 1920
          maximum: 2147483647
          minimum: 0
    ShippingInformationLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/ShippingInformationSelfLink'
      required:
        - self
    ShippingInformationMinimalResponseDto:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/ShippingInformationLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        ratepay_shipping_information_id:
          type: string
          description: >-
            ID of added shipping information generated by Ratepay. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: HR1iyZYradbGbvOQzZ79
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - created
        - ratepay_shipping_information_id
    ShippingInformationRequestDto:
      type: object
      properties:
        carrier_name:
          type: string
          description: Name of carrier responsible for shipment.
          enum:
            - DHL
            - POST_AUSTRIA
            - UPS
            - DPD
            - SWISS_POST
            - GLS
            - ASENDIA
            - HERMES_LOGISTICS
            - FEDEX
            - OTHER_WITH_TRACKING
            - OTHER_WITHOUT_TRACKING
          example: DHL
        tracking_number:
          type: string
          description: >-
            Tracking number for delivery. This field is mandatory for each
            carrier_name except: `OTHER_WITHOUT_TRACKING`
          example: tracking-123456789
          maxLength: 127
          minLength: 1
      required:
        - carrier_name
    ShippingInformationSelfLink:
      type: object
      description: The self relation identifying the shipping information resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN/shipping-information/HR1iyZYradbGbvOQzZ79
      required:
        - href
    ShopBasketDto:
      type: object
      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](/docs/developer/api_integration/payment_2.0/basket_validation/)
        for additional details.
      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](/docs/developer/api_integration/payment_2.0/basket_validation/)
            for additional details.
          example: 67.6
          exclusiveMinimum: true
          minimum: 0
          multipleOf: 0.01
        items:
          type: array
          description: List of items contained in the transaction.
          items:
            $ref: '#/components/schemas/ItemDto'
          maxItems: 2147483647
          minItems: 1
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
        shop_merchant_id:
          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](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in the payment API 2.0 for more details.
          example: ratepay-merchant-id-123
          maxLength: 255
          minLength: 1
        shop_transaction_id:
          type: string
          description: >
            The transaction ID generated by the shop (i.e. Shop Order ID). Use
            the same value as partner_transaction_id unless the shop and
            integration partner manage separate transaction IDs, such as in PSP
            integrations. **This field must be included in at least one of the
            following requests: authorization or capture.** This ID must be
            known to the buyer and is used for buyer communication, e.g.
            correspondences and buyer support.
          example: shop-transaction-id-1234
          maxLength: 127
          minLength: 1
        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'
      required:
        - gross_amount
        - items
        - partner_shop_id
        - shop_transaction_id
    ShopDto:
      type: object
      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.
      properties:
        correspondence_settings:
          $ref: '#/components/schemas/CorrespondenceSettingsDto'
        legal:
          $ref: '#/components/schemas/ShopLegalDto'
        merchant:
          $ref: '#/components/schemas/MerchantDto'
        merchant_category_code:
          type: string
          description: >-
            The branch of industry of the shop. Must conform to [ISO
            18245](https://www.iso.org/standard/79450.html).
          example: '5499'
          pattern: '[0-9]{4}'
        name:
          type: string
          description: The name of the shop. May differ from legal name.
          example: fruits and more
          maxLength: 255
          minLength: 2
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
      required:
        - legal
        - merchant_category_code
        - name
        - partner_shop_id
    ShopLegalDto:
      type: object
      description: Legal information about the shop.
      properties:
        commercial_register_number:
          type: string
          description: The registration number the shop is filed under.
          example: HRB 12345FF
          maxLength: 12
          minLength: 2
        legal_form:
          type: string
          description: >-
            The legal form as which the shop is registered, e.g. Ltd., GmbH,
            GbR, etc.
          example: GmbH
          maxLength: 255
          minLength: 2
        name:
          type: string
          description: The name of the shop as which it is registered.
          example: Fruits and more GmbH
          maxLength: 255
          minLength: 2
      required:
        - commercial_register_number
        - legal_form
        - name
    ShopLookupResponseDto:
      type: object
      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.
      properties:
        merchant_category_code:
          type: string
          description: >-
            The branch of industry of the shop. Must conform to [ISO
            18245](https://www.iso.org/standard/79450.html).
          example: '5499'
          pattern: '[0-9]{4}'
        partner_shop_id:
          type: string
          description: >-
            The shop ID provided upfront by Ratepay or generated by the partner
            in PSP (payment service providers) scenarios. Get an [overview of
            key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-shop-id-1
          maxLength: 255
          minLength: 1
      required:
        - merchant_category_code
        - partner_shop_id
    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.
          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'
          items:
            type: string
            description: >-
              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"]
          maxItems: 5
          minItems: 1
        formal_tone:
          type: string
          description: Formality level for the buyer correspondences.
          enum:
            - FORMAL
            - INFORMAL
          example: INFORMAL
        name_format:
          type: string
          description: >-
            Specifies how to visualize the buyer's name after the salutation in
            the buyer correspondences.
          enum:
            - EMPTY
            - FIRST_NAME
            - LAST_NAME
            - FIRST_LAST_NAME
          example: FIRST_LAST_NAME
        salutation:
          type: string
          description: >-
            Word for salutation in the buyer correspondences in this language,
            e.g. Hi, Hello, Hallo, Guten Tag, etc.
          example: Hello
          maxLength: 2147483647
          minLength: 1
        transaction_type:
          type: string
          description: Specifies how to call the transaction in buyer correspondences.
          enum:
            - ORDER
            - BOOKING
          example: ORDER
    SlangsDto:
      type: object
      description: Language settings for buyer correspondences.
      properties:
        de:
          $ref: '#/components/schemas/SlangDto'
        en:
          $ref: '#/components/schemas/SlangDto'
        fr:
          $ref: '#/components/schemas/SlangDto'
        nl:
          $ref: '#/components/schemas/SlangDto'
    SpecialItemDto:
      type: object
      description: List of special items to add, e.g. shipping costs or discounts.
      example:
        article_number: SHIPPING_001
        category: shipping
        description: Standard shipping via DHL
        gross_total_price: 5.95
        gross_unit_price: 5.95
        name: Shipping costs
        net_total_price: 5
        net_unit_price: 5
        quantity: 1
        tax_rate: 19
        unit: shipment
      properties:
        article_number:
          type: string
          description: >-
            The article number of the item, e.g. SKU. Not allowed to contain
            only whitespaces.
          example: SHIPPING_001
          maxLength: 255
          minLength: 1
          pattern: .*[\S].*
        category:
          type: string
          description: Category for the item.
          example: shipping
          maxLength: 511
          minLength: 0
        description:
          type: string
          description: Description of the item.
          example: Standard shipping via DHL
          maxLength: 511
          minLength: 0
        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
          example: 5.95
          multipleOf: 0.01
        gross_unit_discount:
          type: number
          description: >-
            Gross discount on one item after taxes. Needs to be a negative
            value.
          example: 0
          exclusiveMaximum: false
          maximum: 0
          multipleOf: 0.01
        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.
          example: 5.95
          multipleOf: 0.01
        name:
          type: string
          description: Name of the item.
          example: Shipping costs
          maxLength: 255
          minLength: 1
        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
          example: 5
          multipleOf: 0.01
        net_unit_discount:
          type: number
          description: Net discount on one item before taxes. Needs to be a negative value.
          example: 0
          exclusiveMaximum: false
          maximum: 0
          multipleOf: 0.01
        net_unit_price:
          type: number
          description: Net value of one item before taxes.
          example: 5
          multipleOf: 0.01
        quantity:
          type: number
          description: Ordered quantity of the item.
          example: 1
          exclusiveMinimum: false
          minimum: 0
          multipleOf: 1.e-10
        tax_rate:
          type: number
          description: Tax rate applicable for the item given in percent.
          example: 19
          exclusiveMaximum: true
          exclusiveMinimum: false
          maximum: 1000
          minimum: 0
          multipleOf: 0.01
        type:
          type: string
          description: >-
            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
        unit:
          type: string
          description: Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
          example: shipment
          maxLength: 255
          minLength: 0
      required:
        - gross_unit_price
        - name
        - quantity
        - tax_rate
    TransactionBadRequestErrorDto:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        decline:
          $ref: '#/components/schemas/BadRequestDeclineDto'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        result:
          type: string
          description: >-
            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
      required:
        - _links
        - created
        - decline
        - ratepay_transaction_id
        - result
    TransactionCreateRejectedDeclineDto:
      type: object
      description: Information about why transaction was not accepted and declined.
      properties:
        category:
          type: string
          description: >-
            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
          example: CONTRACT
        reasons:
          type: array
          description: >-
            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.
          example:
            - CURRENCY_NOT_ALLOWED
          items:
            type: string
            description: >-
              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
            example: '["CURRENCY_NOT_ALLOWED"]'
      required:
        - category
    TransactionCreateRejectedErrorResponseDto:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        decline:
          $ref: '#/components/schemas/TransactionCreateRejectedDeclineDto'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
        result:
          type: string
          description: >-
            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
      required:
        - _links
        - created
        - decline
        - ratepay_transaction_id
        - result
    TransactionLinks:
      type: object
      description: >-
        Links related to the resource following specification by
        [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
      properties:
        self:
          $ref: '#/components/schemas/TransactionSelfLink'
      required:
        - self
    TransactionMinimalResponseDto:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        authorization_expires:
          type: string
          format: date-time
          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).
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        payment_details:
          $ref: '#/components/schemas/PaymentDetailsMinimalResponseLegacyDto'
        result:
          $ref: '#/components/schemas/TransactionStatus'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - authorization_expires
        - created
        - ratepay_transaction_id
        - result
    AuthorizationTransactionMinimalResponseDto:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        authorization_expires:
          type: string
          format: date-time
          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).
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        payment_details:
          $ref: '#/components/schemas/PaymentDetailsMinimalResponseLegacyDto'
        result:
          type: string
          description: >-
            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:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - authorization_expires
        - created
        - ratepay_transaction_id
        - result
    TransactionMinimalResponseDtoOtpRequired:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/TransactionLinks'
        authorization_expires:
          type: string
          format: date-time
          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).
        created:
          type: string
          format: date-time
          description: >-
            Timestamp with offset according to [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        payment_details:
          $ref: '#/components/schemas/PaymentDetailsMinimalResponseLegacyDto'
        result:
          type: string
          description: >-
            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:
          $ref: '#/components/schemas/OtpDetailsDto'
        ratepay_transaction_id:
          type: string
          description: >-
            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
          maxLength: 127
          minLength: 20
          pattern: '[A-Za-z0-9-_]{20,127}'
      required:
        - _links
        - authorization_expires
        - created
        - ratepay_transaction_id
        - result
    TransactionRequestDto:
      type: object
      properties:
        authorization_expires:
          type: string
          format: date-time
          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.
          example: '2025-04-02T16:15:18.823+02:00'
        buyer:
          $ref: '#/components/schemas/BuyerDto'
        currency:
          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).
          example: EUR
          pattern: '[A-Z]{3}'
        delivery:
          $ref: '#/components/schemas/DeliveryDto'
        device:
          $ref: '#/components/schemas/DeviceDto'
        options:
          $ref: '#/components/schemas/OptionsDto'
        partner_operation_id:
          type: string
          description: >-
            The unique ID generated by the partner or shop to identify an API
            operation. This ID can be displayed in settlement reports to allow
            relating settlement report items to API operations. Get an [overview
            of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-operation-id-1234
          maxLength: 255
          minLength: 0
        partner_transaction_id:
          type: string
          description: >
            The transaction ID generated by the partner (i.e. Partner Order ID).
            Use the same value as shop_transaction_id unless the shop and
            integration partner manage separate transaction IDs, such as in PSP
            (payment service provider) integrations. **This field must be
            included in at least one of the following requests: authorization or
            capture.** This ID can be displayed in settlement reports. Get an
            [overview of key
            identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)
            used in payment API.
          example: partner-transaction-id-1234
          maxLength: 50
          minLength: 1
        payment_method:
          $ref: '#/components/schemas/PaymentMethodDto'
        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](/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'
      required:
        - buyer
        - currency
        - payment_method
        - shop_baskets
    TransactionSelfLink:
      type: object
      description: The self relation identifying the transaction resource itself.
      properties:
        href:
          type: string
          description: URI pointing to resource itself.
          example: >-
            https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp
      required:
        - href
    UnprocessableOperationNotAllowedForDeclinedTransaction:
      type: object
      properties:
        category:
          type: string
          description: >-
            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
          example: UNPROCESSABLE_OPERATION
        reasons:
          type: array
          description: >-
            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.
          example:
            - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
          items:
            type: string
            description: >-
              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
              - 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
            example: '["NOT_ALLOWED_FOR_DECLINED_TRANSACTION"]'
      required:
        - category
    VatDto:
      type: object
      description: List of value-added tax (VAT) amounts.
      properties:
        net_amount:
          type: number
          description: The net amount before taxes for the given tax rate.
          example: 56.81
          exclusiveMinimum: false
          minimum: 0
          multipleOf: 0.01
        tax_amount:
          type: number
          description: The tax amount for the given tax rate.
          example: 10.79
          exclusiveMinimum: false
          minimum: 0
          multipleOf: 0.01
        tax_rate:
          type: number
          description: Tax rate given as percentage on the net amount.
          example: 19
          exclusiveMaximum: true
          exclusiveMinimum: false
          maximum: 1000
          minimum: 0
          multipleOf: 0.01
    TransactionStatus:
      type: string
      description: >-
        Indicates the outcome of the transaction request. Possible values:
        ACCEPTED – The transaction has been successfully authorized and can
        proceed to capture. DECLINED – The transaction has been rejected; the
        merchant must not proceed with order fulfillment. OTP_REQUIRED – The
        buyer must complete OTP verification before the transaction can be
        finalized.
      enum:
        - ACCEPTED
        - DECLINED
        - OTP_REQUIRED
      example: ACCEPTED
    OtpDetailsDto:
      type: object
      description: >-
        Present only when result = OTP_REQUIRED. Contains OTP validity,
        regeneration timing, localized messages, and verification endpoints.
      properties:
        regeneration_possible_in_seconds:
          type: number
          description: >-
            Time (in seconds) after which the buyer can request a new OTP if
            needed.
          example: 60
        time_to_live_in_seconds:
          type: number
          description: Duration (in seconds) for which the OTP remains valid before expiry.
          example: 120
        message:
          $ref: '#/components/schemas/MessageDto'
        links:
          $ref: '#/components/schemas/LinksDto'
    MessageDto:
      type: object
      properties:
        en:
          type: string
          description: >-
            Buyer-facing message confirming OTP send, intended for display in
            the checkout experience.
          example: The code has been sent to your phone number .
        de:
          type: string
          description: >-
            Buyer-facing message confirming OTP send, intended for display in
            the checkout experience.
          example: Der Code wurde an Ihre Telefonnummer  gesendet.
    LinksDto:
      type: object
      properties:
        regenerate:
          type: string
          description: Endpoint to request generation of a new OTP code.
          example: /2fa/v1/public/regenerate/scwBgARW-nE93I7_ywhp
        verify:
          type: string
          description: Endpoint to verify the OTP code entered by the buyer.
          example: /2fa/v1/public/verify/scwBgARW-nE93I7_ywhp
  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 and [Request OAuth
        token](/apis/authentication/openapi/authentication_api/createoauthtoken/)
        for details on the audience to use.
      scheme: bearer
      type: http
