openapi: "3.0.2" # it seems swagger editor does not support yet 3.1.0?
info:
  version: 1.0.0
  title: Transaction Service
  description: |
    The Transaction Service is responsible for creating transaction intents (= QR Codes) and transactions.
    ## Change Log:
    - 1.7.0 (2025-07-11):
      - decommissioned Card and error codes related to card validation
      - renamed TransactionDeclineReason.DisallowedByConfig to DisallowedByTestInProductionConfig
      - extended TransactionDeclineReason with DisallowedByProcessingConfig
    - 1.6.0 (2025-01-22):
      - Updated create transaction from intent API
      - Extended error codes for:
        - create transaction from intent API
        - create reversal transaction API
        - create refund transaction API
      - Extended TransactionDeclineReason, TransactionIntentDeclineReason, CustomerPermissionDeniedReason
    - 1.5.0 (2024-01-03):
      - Added create transaction from intent API
      - Added reverse transaction API
    - 1.0.0 (2023-01-29):
      - Initial version

    ## Source
    [Download openapi yaml](transaction-service-v1.x.x-ext2.yaml)
  contact:
    name: Tech Support
    email: techsupport@zastrpay.com
    url: https://zastrpay.com
servers:
  - url: https://host.com/transaction-service/v1
tags:
  - name: transaction-intent
    description: Transaction Intent
    x-displayName: Transaction Intent

  - name: transaction-intent-event
    description: Transaction Intent Event
    x-displayName: Transaction Intent Event

  - name: transaction-event
    description: Transaction Event
    x-displayName: Transaction Event

  - name: transaction
    description: Transaction
    x-displayName: Transaction

  - name: reversal
    description: Reversal
    x-displayName: Reversal

  - name: refund
    description: Refund
    x-displayName: Refund

security:
  - ApiKeyAuth: []

paths:
  /transaction-intents/{transactionIntentId}:
    parameters:
      - name: transactionIntentId
        in: path
        required: true
        description: The id of the transaction intent which should be returned.
        schema:
          type: string
          format: uuid
          example: a8ad0bb3-9457-4b9f-95ae-21e16cf6c873
    get:
      tags:
        - transaction-intent
      summary: Returns a single transaction intent's data
      operationId: getTransactionIntent
      responses:
        "200":
          description: Successful operation
          headers:
            Location:
              description: The relative URI of the transaction intent.
              schema:
                type: string
            ETag:
              description: The current version identifier of the transaction intent.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionIntent"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - Validation
        "404":
          description: Transaction intent not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - TransactionIntentNotFound
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred

  /transaction-intents:
    get:
      tags:
        - transaction-intent
      summary: Get a filtered list of transaction intents
      operationId: getTransactionIntents
      parameters:
        - name: queryType
          in: query
          schema:
            type: string
            enum:
              - ByFromToCreatedOn
              - ByCustomer
              - ActiveByCustomerAndMerchant
            default: ByFromToCreatedOn
        - name: createdon_gte
          in: query
          required: false
          description: The min creation datetime of the entries to be returned, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
          schema:
            type: string
            format: date-time
            example: 2019-01-31T11:59:59Z
        - name: createdon_lte
          in: query
          required: false
          description: The max creation datetime of the entries to be returned, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
          schema:
            type: string
            format: date-time
            example: 2019-01-31T11:59:59Z
        - name: _limit
          in: query
          required: false
          description: The count of items to be returned (page size)
          schema:
            type: number
            default: 10
        - name: _order
          in: query
          required: false
          description: The sort order of items to be returned
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: customerId
          in: query
          required: false
          description: The customerId of the transaction intents to be returned. Required if the query type is ByCustomer*
          schema:
            type: string
            format: uuid
        - name: merchantId
          in: query
          required: false
          description: The customerId of the transaction intents to be returned. Required if the query type is ActiveByCustomerAndMerchant
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/TransactionIntent"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - Validation
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred

  /transactions/{transactionId}/from-intent:
    put:
      tags:
        - transaction
      summary: Creates a new transaction from a transaction intent
      operationId: createTransactionFromIntent
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The id of the transaction which should be returned.
          schema:
            type: string
            format: uuid
            example: a8ad0bb3-9457-4b9f-95ae-21e16cf6c873
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewTransactionFromIntent"
      responses:
        "201":
          description: Successful response. Transaction has been created.
          headers:
            Location:
              description: The relative URI of the transaction.
              schema:
                type: string
            ETag:
              description: The current version identifier of the transaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - Validation
                          - InvalidTransition
                          - InvalidState
                          - InsufficientFunds
                          - CustomerNotFound
                          - DistributorNotFound
                          - InvalidTransactionType
                          - InvalidTriggeredBy
                          - TransactionIntentNotFound
                          - InvalidTransactionIntentState
        "409":
          description: Transaction intent was updated in the meantime, get and retry
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - EntityVersionMismatch
                          - DuplicateEntity
        "422":
          description: Transaction could not be processed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - LimitAmountThresholdExceeded
                          - LimitTimeThresholdExceeded
                          - OneOrMoreLimitThresholdsExceeded
                          - LimitAccountSetNotFound
                          - CustomerPermissionDenied
                          - MissingTransactionSignature
                          - MissingTransactionProofOfIdentity
                          - DistributorNotActive
                          - PinValidationFailed
                          - TanValidationFailed
                          - CardNotFound
                          - MissingPin
                          - MissingTan
                          - CardHolderMismatch
                          - TransactionDisallowedByTestInProductionConfig
                          - TransactionDisallowedByProcessingConfig
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - GeneralErrorOccurred

  /transaction-intent-events/subscriptions/{eventSubscriptionId}:
    put:
      tags:
        - transaction-intent-event
      summary: Subscribe to Transaction Intent events
      operationId: subscribeToTransactionIntentEvents
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription, which can be used for unsubscribing later on.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/NewEventSubscription"
                - type: object
                  properties:
                    eventTypes:
                      description: the list of event types to which subscriber would like to listen for
                      type: array
                      minItems: 1
                      items:
                        $ref: "#/components/schemas/TransactionIntentEventType"
                  required:
                    - callbackUrl
                    - apiKey
                    - eventTypes
      responses:
        "201":
          description: Subscription created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EventSubscription"
                  - type: object
                    properties:
                      eventTypes:
                        type: array
                        items:
                          $ref: "#/components/schemas/TransactionIntentEventType"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - Validation
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred
      # callbacks:
      #   onEvent:
      #     "{$request.body#/callbackUrl}":
      #       post:
      #         requestBody:
      #           description: Contents of the callback message
      #           required: true
      #           content:
      #             application/json:
      #               schema:
      #                 $ref: "#/components/schemas/TransactionIntentEvent"
      #         responses:
      #           "200":
      #             description: Your server returns this code if it accepts the callback
    patch:
      tags:
        - transaction-intent-event
      summary: Update the subscription to Transaction Intent events
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription, which can be used for unsubscribing later on.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/UpdateEventSubscription"
                - type: object
                  properties:
                    eventTypes:
                      description: the list of event types to which subscriber would like to listen for
                      type: array
                      minItems: 1
                      items:
                        $ref: "#/components/schemas/TransactionIntentEventType"
                  required:
                    - callbackUrl
                    - apiKey
                    - eventTypes
      responses:
        "200":
          description: Webhook updated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EventSubscription"
                  - type: object
                    properties:
                      eventTypes:
                        type: array
                        items:
                          $ref: "#/components/schemas/TransactionIntentEventType"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - Validation
        "403":
          description: Operation forbidden
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - InvalidTriggeredBy

        "404":
          description: Subscription not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SubscriptionNotFound

        "409":
          description: Subscription was updated in the meantime, get and retry
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - EntityVersionMismatch
                          - DuplicateEntity
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred
    delete:
      tags:
        - transaction-intent-event
      summary: Unsubscribe from Transaction Intent events
      operationId: unsubscribeFromTransactionIntentEvents
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription to be unsubscribed.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      responses:
        "200":
          description: Webhook deleted
        "403":
          description: Operation forbidden
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - InvalidTriggeredBy
        "404":
          description: Subscription not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SubscriptionNotFound
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred

  /transaction-events/subscriptions/{eventSubscriptionId}:
    put:
      tags:
        - transaction-event
      summary: Subscribe to Transaction events
      operationId: subscribeToTransactionEvents
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription, which can be used for unsubscribing later on.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventSubscription"
                - type: object
                  properties:
                    eventTypes:
                      description: the list of event types to which subscriber would like to listen for
                      type: array
                      minItems: 1
                      items:
                        $ref: "#/components/schemas/TransactionEventType"
                  required:
                    - callbackUrl
                    - apiKey
                    - eventTypes
      responses:
        "201":
          description: Subscription created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EventSubscription"
                  - type: object
                    properties:
                      eventTypes:
                        type: array
                        items:
                          $ref: "#/components/schemas/TransactionEventType"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - Validation
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred
      # callbacks:
      #   onEvent:
      #     "{$request.body#/callbackUrl}":
      #       post:
      #         requestBody:
      #           description: Contents of the callback message
      #           required: true
      #           content:
      #             application/json:
      #               schema:
      #                 $ref: "#/components/schemas/TransactionEvent"
      #         responses:
      #           "200":
      #             description: Your server returns this code if it accepts the callback
    patch:
      tags:
        - transaction-event
      summary: Update a subscription to Transaction events
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription, which can be used for unsubscribing later on.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/UpdateEventSubscription"
                - type: object
                  properties:
                    eventTypes:
                      description: the list of event types to which subscriber would like to listen for
                      type: array
                      minItems: 1
                      items:
                        $ref: "#/components/schemas/TransactionEventType"
                  required:
                    - callbackUrl
                    - apiKey
                    - eventTypes
      responses:
        "200":
          description: Webhook updated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EventSubscription"
                  - type: object
                    properties:
                      eventTypes:
                        type: array
                        items:
                          $ref: "#/components/schemas/TransactionEventType"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - Validation
        "403":
          description: Operation forbidden
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - InvalidTriggeredBy

        "404":
          description: Subscription not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SubscriptionNotFound

        "409":
          description: Subscription was updated in the meantime, get and retry
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - EntityVersionMismatch
                          - DuplicateEntity
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - GeneralErrorOccurred
    delete:
      tags:
        - transaction-event
      summary: Unsubscribe from Transaction events
      operationId: unsubscribeFromTransactionEvents
      parameters:
        - name: eventSubscriptionId
          in: path
          required: true
          description: The unique id of this subscription to be unsubscribed.
          schema:
            type: string
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
      responses:
        "200":
          description: Webhook deleted
        "403":
          description: Operation forbidden
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - InvalidTriggeredBy
        "404":
          description: Subscription not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SubscriptionNotFound
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - GeneralErrorOccurred

  /transactions/{transactionId}/reversals/{reversalTransactionId}:
    put:
      tags: [reversal]
      summary: Creates a new reversal transaction
      operationId: createReversalTransaction
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The id of the transaction which should be returned.
          schema:
            type: string
            format: uuid
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
        - name: reversalTransactionId
          in: path
          required: true
          description: The id of the reversal transaction which should be returned.
          schema:
            type: string
            format: uuid
            example: 000aaaaa-8888-bbbb-aabb-44444444444
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewReversalTransaction"
      responses:
        "201":
          description: Successful response
          headers:
            Location:
              description: The relative URI of the transaction.
              schema:
                type: string
            ETag:
              description: The current version identifier of the transaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - Validation
                          - InvalidTransition
                          - InvalidState
                          - InsufficientFunds
                          - CustomerNotFound
                          - DistributorNotFound
                          - InvalidTransactionType
                          - OriginalTransactionNotFound
                          - InvalidOriginalTransactionState
                          - SucceededOrBeingProcessedReversalsExistAlready
                          - InvalidOriginalTransactionType
                          - InvalidTriggeredBy
                          - NotOnSameBusinessDayAsOriginalTransaction
        "409":
          description: Transaction was updated in the meantime, get and retry
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - EntityVersionMismatch
                          - DuplicateEntity
        "422":
          description: Transaction could not be processed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - LimitAmountThresholdExceeded
                          - LimitTimeThresholdExceeded
                          - OneOrMoreLimitThresholdsExceeded
                          - LimitAccountSetNotFound
                          - CustomerPermissionDenied
                          - MissingTransactionSignature
                          - MissingTransactionProofOfIdentity
                          - DistributorNotActive
                          - PinValidationFailed
                          - TanValidationFailed
                          - CardNotFound
                          - MissingPin
                          - MissingTan
                          - CardHolderMismatch
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - GeneralErrorOccurred

  # /transactions/{transactionId}/reversals:
  #   parameters:
  #     - name: transactionId
  #       in: path
  #       required: true
  #       description: The id of the transaction which should be returned.
  #       schema:
  #         type: string
  #         format: uuid
  #         example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
  #   get:
  #     tags: [reversal]
  #     summary: Returns the reversal transactions for a given (original) transaction
  #     operationId: getReversalTransactions
  #     responses:
  #       "200":
  #         description: Successful response
  #         content:
  #           application/json:
  #             schema:
  #               items:
  #                 type: array
  #                 items:
  #                   $ref: "#/components/schemas/Transaction"
  #       "400":
  #         description: Validation failed
  #         content:
  #           application/json:
  #             schema:
  #               allOf:
  #                 - $ref: "#/components/schemas/Error"
  #                 - type: object
  #                   properties:
  #                     code:
  #                       type: string
  #                       x-extensible-enum:
  #                         - Validation
  #       "500":
  #         description: Unexpected technical error
  #         content:
  #           application/json:
  #             schema:
  #               allOf:
  #                 - $ref: "#/components/schemas/Error"
  #                 - type: object
  #                   properties:
  #                     code:
  #                       type: string
  #                       x-extensible-enum:
  #                         - GeneralErrorOccurred

  /transactions/{transactionId}/refunds/{refundTransactionId}:
    put:
      tags: [refund]
      summary: Creates a new refund transaction
      operationId: createRefundTransaction
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The id of the transaction which should be returned.
          schema:
            type: string
            format: uuid
            example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
        - name: refundTransactionId
          in: path
          required: true
          description: The id of the refund transaction which should be returned.
          schema:
            type: string
            format: uuid
            example: 000aaaaa-8888-bbbb-aabb-44444444444
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewRefundTransaction"
      responses:
        "201":
          description: Successful response
          headers:
            Location:
              description: The relative URI of the transaction.
              schema:
                type: string
            ETag:
              description: The current version identifier of the transaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - Validation
                          - InvalidTransition
                          - InvalidState
                          - InsufficientFunds
                          - CustomerNotFound
                          - DistributorNotFound
                          - InvalidTransactionType
                          - OriginalTransactionNotFound
                          - InvalidOriginalTransactionState
                          - SucceededOrBeingProcessedRefundsExistAlready
                          - InvalidOriginalTransactionType
                          - InvalidTriggeredBy
                          - NotOnSameBusinessDayAsOriginalTransaction
        "409":
          description: Transaction was updated in the meantime, get and retry
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - EntityVersionMismatch
                          - DuplicateEntity
        "422":
          description: Transaction could not be processed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - LimitAmountThresholdExceeded
                          - LimitTimeThresholdExceeded
                          - OneOrMoreLimitThresholdsExceeded
                          - LimitAccountSetNotFound
                          - CustomerPermissionDenied
                          - MissingTransactionSignature
                          - MissingTransactionProofOfIdentity
                          - DistributorNotActive
                          - PinValidationFailed
                          - TanValidationFailed
                          - CardNotFound
                          - MissingPin
                          - MissingTan
                          - CardHolderMismatch
        "500":
          description: Unexpected technical error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      code:
                        type: string
                        x-extensible-enum:
                          - GeneralErrorOccurred

  # /transactions/{transactionId}/refunds:
  #   parameters:
  #     - name: transactionId
  #       in: path
  #       required: true
  #       description: The id of the transaction which should be returned.
  #       schema:
  #         type: string
  #         format: uuid
  #         example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
  #   get:
  #     tags: [refund]
  #     summary: Returns the refund transactions for a given (original) transaction
  #     operationId: getRefundTransactions
  #     responses:
  #       "200":
  #         description: Successful response
  #         content:
  #           application/json:
  #             schema:
  #               items:
  #                 type: array
  #                 items:
  #                   $ref: "#/components/schemas/Transaction"
  #       "400":
  #         description: Validation failed
  #         content:
  #           application/json:
  #             schema:
  #               allOf:
  #                 - $ref: "#/components/schemas/Error"
  #                 - type: object
  #                   properties:
  #                     code:
  #                       type: string
  #                       x-extensible-enum:
  #                         - Validation
  #       "500":
  #         description: Unexpected technical error
  #         content:
  #           application/json:
  #             schema:
  #               allOf:
  #                 - $ref: "#/components/schemas/Error"
  #                 - type: object
  #                   properties:
  #                     code:
  #                       type: string
  #                       x-extensible-enum:
  #                         - GeneralErrorOccurred

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

  schemas:
    ExternalReference:
      type: string
      description: A reference to a transaction in an external system e.g. bank transfer.
      pattern: '^[\d\p{L}]([\d\p{L}\-\. ]{0,48}[\d\p{L}])$'
      minLength: 1
      maxLength: 50
      example: 234abc22-33de-4444-5555-222222222222

    PosDevice:
      type: object
      description: The device at which the transaction was triggered
      required:
        - id
        - type
      properties:
        id:
          type: string
          maxLength: 50
          description: The unique id of the device
          example: Till_12345
        type:
          type: string
          enum:
            - Till
            - Terminal
            - Mobile
          description: The type of the device
        appInstallationId:
          type: string
          format: uuid
          description: The unique id of the app installation on the device

    TriggerSource:
      type: object
      description: |
        The entry point via which the customer was registered or her/his data was updated

        For DistributorB2B the following details are mandatory: distributorId, shopId, posDevice (id, type), operatorId

        For MerchantB2B the following details are mandatory: merchantId

        For PosApp the following details are mandatory: distributorId, shopId, posDevice (id, type, appInstallationId), operatorId

        For Admin the following details are mandatory: operatorId

        For System there are no mandatory fields
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - DistributorB2B
            - MerchantB2B
            - PosApp
            - Admin
            - System
        distributorId:
          type: string
          format: uuid
          description: The distributor at which the transaction got created/modified, in case the type is DistributorB2B
          example: 333ddddd-2222-aaff-ccbb-333333333333
        shopId:
          description: The distributor's shop at which the transaction got created/modified
          anyOf:
            - type: string
              description: Arbitrary string if type is DistributorB2B
              example: Shop1
            - type: string
              format: uuid
              description: Id reference in uuid format if type is PosApp
              example: 63308c65-cf2e-42cd-907e-ac8d7942b59f
        posDevice:
          $ref: "#/components/schemas/PosDevice"
        operatorId:
          description: The cashier/operator who performed the transaction
          anyOf:
            - type: string
              description: Arbitrary string if type is DistributorB2B
              example: E3112
            - type: string
              format: uuid
              description: Id reference in uuid format if type is Admin or PosApp
              example: 7c4bfb7c-52fe-41b1-a64f-1ca894831d4b
        customerId:
          type: string
          description: The customer who performed the transaction, in case the type is SelfServicePortal
          example: 333ddddd-2222-aaff-ccbb-333333333333
        merchantId:
          type: string
          description: The merchant who performed the transaction, in case the type is SelfServicePortal
          example: 333ddddd-2222-aaff-ccbb-444444444444

    TransactionType:
      type: string
      description: The type of the transaction, defining which other transaction properties are mandatory, e.g. PassthroughDeposit requires customerId, merchantId, documents, card
      enum:
        - PassthroughDeposit
        - PassthroughWithdrawal
        - CustomerToMerchantTransfer
        - CustomerToMerchantPassthrough
        - MerchantToCustomerTransfer
        - MerchantToCustomerPassthrough

    TransactionState:
      type: string
      description: The current(last) state of the transaction.
      enum:
        - Declined #in case Customer Flags are not allowing to perform the trx, or Distributor is Blocked, etc.
        - Completed
        - Cancelled

    TransactionDeclineReason:
      type: string
      description: Available if state is Declined
      enum:
        - DistributorNotActive
        - CustomerPermissionDenied
        - MissingTransactionProofOfIdentity
        - InsufficientFunds
        - LimitAmountThresholdExceeded
        - LimitTimeThresholdExceeded
        - OneOrMoreLimitThresholdsExceeded
        - LimitAccountSetNotFound
        - DisallowedByTestInProductionConfig
        - DisallowedByProcessingConfig

    TransactionStatus:
      type: string
      description: The overall status/outcome of the transaction.
      enum:
        - BeingProcessed
        - Succeeded
        - Failed

    TransactionIntentDeclineReason:
      type: string
      description: Available if state is Declined
      enum:
        - MaxApprovalAttemptsReached
        - CustomerPermissionDenied
        - LimitAmountThresholdExceeded
        - LimitTimeThresholdExceeded
        - OneOrMoreLimitThresholdsExceeded
        - LimitAccountSetNotFound
        - MerchantNotFound

    TransactionIntentFinalizeReason:
      type: string
      description: Available if state is Finalized
      enum:
        - TransactionCompleted
        - TransactionDeclined
        - TransactionCancelled

    TransactionIntentPendingApprovalReason:
      type: string
      description: Available if state is PendingApproval
      enum:
        - UnsuccessfulAttempt
        - CodeReset

    TransactionIntentState:
      type: string
      description: The current(last) state of the transaction intent.
      enum:
        - Created
        - PendingApproval
        - Declined
        - Pending
        - Expired
        - Cancelled
        - Finalized

    TransactionIntentType:
      type: string
      description: The type of the transaction intent, this corresponds to the type of the transaction created from the intent
      enum:
        - PassthroughDeposit
        - PassthroughWithdrawal
        - CustomerToMerchantPassthrough
        - MerchantToCustomerPassthrough

    TransactionIntent:
      type: object
      required:
        - id
        - amount
        - currency
        - customerId
        - merchantId
        - state
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The id of the transaction
          example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
        amount:
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 10000
          description: The amount of the transaction
          example: 100.00
        currency:
          type: string
          enum:
            - EUR
          description: The currency code as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217).
          example: EUR
        customerId:
          type: string
          format: uuid
          description: The unique id of the customer participating in the transaction. Available if type is *Passthrough*
          example: 111abc22-33de-4444-5555-111111111111
        # merchantId:
        #   type: string
        #   format: uuid
        #   description: The unique id of the merchant participating in the transaction. Available if type is *Passthrough* or MerchantPayment*
        #   example: 222abc22-33de-4444-5555-222222222222
        type:
          $ref: "#/components/schemas/TransactionIntentType"
        state:
          $ref: "#/components/schemas/TransactionIntentState"
        # stateDetails:
        #   type: object
        #   description: State-specific additional attributes, e.g. declineReason for Declined state
        #   properties:
        #     declineReason:
        #       $ref: "#/components/schemas/TransactionIntentDeclineReason"
        #     pendingApprovalReason:
        #       $ref: "#/components/schemas/TransactionIntentPendingApprovalReason"
        #     finalizeReason:
        #       $ref: "#/components/schemas/TransactionIntentFinalizeReason"
        # externalReference:
        #   $ref: "#/components/schemas/ExternalReference"
        # createdBy:
        #   $ref: "#/components/schemas/TriggerSource"
        createdOn:
          type: string
          description: The server-generated timestamp of the initial creation of the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
          format: date-time
          example: 2019-01-31T11:50:59Z
        # lastModifiedBy:
        #   $ref: "#/components/schemas/TriggerSource"
        # lastModifiedOn:
        #   type: string
        #   format: date-time
        #   description: The server-generated timestamp of the last update to the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
        #   example: 2019-01-31T11:59:59Z

    DocumentType:
      type: string
      description: The type of the document
      x-extensible-enum:
        - TransactionSignature
        - TransactionProofOfIdentity

    Document:
      type: object
      description: Contains metadata of a document
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The id of an already uploaded document returned by the C2D Document Service
          example: 70000c85-c211-4c04-843c-125bebbb4cd6
        type:
          $ref: "#/components/schemas/DocumentType"

    NewTransactionFromIntent:
      type: object
      properties:
        transactionIntentId:
          type: string
          format: uuid
          description: The id of the transaction intent which should be used for creation of the transaction.
        documents:
          type: array
          description: A collection of documents' metadata required for the specific transaction.
          items:
            $ref: "#/components/schemas/Document"

    TransactionDescription:
      type: string
      minLength: 1
      maxLength: 100
      description: A short text describing the purpose of the transaction
      pattern: '^[\p{L}0-9''\.\-\\!\$\%\&\/\\\(\)\[\]\{\}\=\?\+\*\#\;\,\:_\"]{1,100}$'
      example: Load into gaming account

    ScaRequired:
      type: string
      description: Defines if the transaction is subject to PSD2 SCA based on transaction.createdBy.posDevice.type and customer.scaWhitelisted flag
      x-extensible-enum:
        - Required
        - NotRequired
        - Exempt

    AuthMethod:
      type: string
      description: Defines what authentication is required for the transaction. Depends on scaRequired, customer, transaction.type and transaction.createdBy.posDevice.type.
      x-extensible-enum:
        - Pin
        - Tan
        - Signature
        - FaceToFace
        - ProofOfIdentity
        - SmsOtp

    CustomerPermissionDeniedReason:
      type: string
      description: The reason for CustomerPermissionDenied declineReason
      x-extensible-enum:
        - CustomerRegistrationFailed
        - InitialCustomerVerificationMissing
        - CustomerPendingInternalReview
        - ValidCustomerPOIRequired
        - ValidCustomerPOARequired
        - CustomerAccountClosedByCustomerRequest
        - CustomerAccountClosedDueToFailedKYC
        - DuplicateCustomerAccountClosed
        - ValidCustomerSOFRequired
        - ValidCustomerSOWRequired
        - CustomerAccountClosed
        - CustomerAccountClosedDueToTechnicalIssue
        - CustomerAccountClosedDueToCustomerDeceased
        - CustomerAccountClosedTestAccount
        - CustomerAccountClosedDormant
        - CustomerAccountClosedSofSowUncooperative

    LimitThresholdExceededReason:
      type: string
      description: The reason for LimitAmountThresholdExceeded, LimitTimeThresholdExceeded or OneOrMoreLimitThresholdsExceeded declineReason
      x-extensible-enum:
        - CustomerPendingInternalReview
        - ValidCustomerPOIRequired
        - ValidCustomerPOARequired
        - ValidCustomerSOFRequired
        - ValidCustomerSOWRequired
        - CustomerInformationRevalidationRequired

    MergedToCustomerId:
      type: string
      format: uuid
      description: In case customerPermissionDeniedReason = DuplicateCustomerAccountClosed, the customerId to which the currently attempted customer was merged to
      example: 51589099-7ad6-48cd-ac41-22b2ebd2c8a3

    Transaction:
      type: object
      required:
        - type
        - amount
        - currency
        - customerId
        - distributorId
      properties:
        id:
          type: string
          format: uuid
          description: The id of the transaction
          example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
        type:
          $ref: "#/components/schemas/TransactionType"
        amount:
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 10000
          description: The amount of the transaction
          example: 100.00
        currency:
          type: string
          x-extensible-enum:
            - EUR
          description: The currency code as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217).
          example: EUR
        customerId:
          type: string
          format: uuid
          description: The unique id of the customer participating in the transaction. Available if type is *Passthrough*
          example: 111abc22-33de-4444-5555-111111111111
        # merchantId:
        #   type: string
        #   format: uuid
        #   description: The unique id of the merchant participating in the transaction. Available if type is Passthrough* or MerchantPayment*
        #   example: 222abc22-33de-4444-5555-222222222222
        description:
          $ref: "#/components/schemas/TransactionDescription"
        # transactionIntentId:
        #   type: string
        #   format: uuid
        #   description: The id of the transaction intent used to create this transaction. Available if type is Passthrough* and CreatedBy.Type is PosApp
        #   example: e5505c74-a6fb-4762-b1cf-13487926c5ad
        referenceTransactionId:
          type: string #for Reversal/Refund only
          format: uuid
          description: The id of another existing transaction referenced by the current one. Available if type is *Reversal or *Refund
          example: 56c7c679-3019-4a56-94c7-b043bacf0dda
        state:
          $ref: "#/components/schemas/TransactionState"
        status:
          $ref: "#/components/schemas/TransactionStatus"
        # documents:
        #   type: array
        #   description: A collection of documents' metadata supplied by the customer at registration
        #   items:
        #     $ref: "#/components/schemas/Document"
        # createdBy:
        #   $ref: "#/components/schemas/TriggerSource"
        createdOn:
          type: string
          description: The server-generated timestamp of the initial creation of the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
          format: date-time
          example: 2019-01-31T11:50:59Z
        # lastModifiedBy:
        #   $ref: "#/components/schemas/TriggerSource"
        # lastModifiedOn:
        #   type: string
        #   format: date-time
        #   description: The server-generated timestamp of the last update to the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
        #   example: 2019-01-31T11:59:59Z
        # scaRequired:
        #   $ref: "#/components/schemas/ScaRequired"
        # authMethods:
        #   type: array
        #   description: The list of applied authentication methods
        #   items:
        #     $ref: "#/components/schemas/AuthMethod"
        # cardId:
        #   type: string
        #   format: uuid
        #   description: The id of the customer card. Presented when AuthMethods contain Pin or Pin and Tan
        #   example: 70000c85-c211-4c04-843c-125bebbb4cd6
        # stateDetails:
        #   type: object
        #   description: State-specific additional attributes, e.g. declineReason for Declined state
        #   properties:
        #     declineReason:
        #       $ref: "#/components/schemas/TransactionDeclineReason"
        #     customerPermissionDeniedReason:
        #       $ref: "#/components/schemas/CustomerPermissionDeniedReason"
        #     limitThresholdExceededReason:
        #       $ref: "#/components/schemas/LimitThresholdExceededReason"
        #     mergedToCustomerId:
        #       $ref: "#/components/schemas/MergedToCustomerId"
        distributorId:
          type: string
          format: uuid
          description: The unique id of the distributor the account balance of whom will be affected. Available if type is DistributorPayment*
          example: 222abc22-33de-4444-5555-222222222222
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
        # postedOn:
        #   type: string
        #   description: The Posting Date or external timestamp of the transaction, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. Used for MerchantPayment* and DistributorPayment* transaction types only.
        #   format: date-time
        #   example: 2019-01-31T23:59:59Z

    Error:
      type: object
      description: Contains details about the error
      properties:
        code:
          type: string
          description: The type of error
          enum:
            - Validation
            - EntityVersionMismatch
            - InvalidTransition
            - DuplicateEntity
            - CustomerNotFound
            - MerchantNotFound
            - MerchantNotActive
            - InvalidTriggeredBy
            - GeneralErrorOccurred
            - TransactionIntentNotFound
            - SubscriptionNotFound
        message:
          type: string
          description: A short text describing the error
        moreInfo:
          type: string
          description: A link to the online documentation describing the error in detail
          example: https://developer.example.com/ExampleService/v1.0/errors/validation
        correlationId:
          type: string
          description: Identifies the conversation within which the error got generated
          example: ce8056cd-ae4d-4f2d-87de-7562c92f92cc
        details:
          type: object
          description: Contains additional details of the error
          properties:
            validationErrorReasons:
              type: array
              description: A collection of Validation error details
              items:
                $ref: "#/components/schemas/ValidationErrorReason"
      required:
        - code
        - message

    NewEventSubscription:
      type: object
      description: Represents a client subscription to a server event feed, whereby the server will call the client's callback for every event item
      properties:
        callbackUrl:
          description: callback url that will be called by server for every subscribed event
          type: string
          format: uri
          example: https://myserver.com/send/callback/here
        apiKey:
          description: Sent back in the x-api-key header of the callback
          type: string
          pattern: ^[A-z0-9=+\/\-:_]{1,128}$
          example: 4EFRLXTFHJKmYKIE7yIsOk7EuLh6Gmh9aBF1FVO4
      required:
        - apiKey
        - callbackUrl

    UpdateEventSubscription:
      type: object
      description: Represents a client subscription to a server event feed, whereby the server will call the client's callback for every event item
      properties:
        callbackUrl:
          description: callback url that will be called by server for every subscribed event
          type: string
          format: uri
          example: https://myserver.com/send/callback/here
        apiKey:
          description: Sent back in the x-api-key header of the callback
          type: string
          pattern: ^[A-z0-9=+\/\-:_]{1,128}$
          example: 4EFRLXTFHJKmYKIE7yIsOk7EuLh6Gmh9aBF1FVO4
      required:
        - apiKey
        - callbackUrl

    EventSubscription:
      type: object
      description: Represents a client subscription to a server event feed, whereby the server will call the client's callback for every event item
      properties:
        id:
          type: string
          format: uuid
          description: Unique id of the subscription
          example: 6d245f63-fdfc-4a6b-a351-bc0b03260dcd
        callbackUrl:
          description: callback url that will be called by server for every subscribed event
          type: string
          format: uri
          example: https://myserver.com/send/callback/here
      required:
        - id
        - callbackUrl

    TransactionEventType:
      type: string
      description: The type of the event, defining also the attributes of which entity are to be found in the data property
      enum:
        - TransactionDeclined
        - TransactionCancelled
        - TransactionCompleted

    TransactionEvent:
      type: object
      description: Fired when a transaction state has changed
      allOf:
        - $ref: "#/components/schemas/EventMetadata"
        - type: object
          properties:
            type:
              $ref: "#/components/schemas/TransactionEventType"
            data:
              type: object
              required:
                - id
                - type
                - amount
                - currency
                - createdOn
                - state
                - status
              properties:
                id:
                  type: string
                  format: uuid
                  description: The id of the transaction
                  example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
                amount:
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
                  description: The amount of the transaction. For deposits the maximum is 10.000,00
                  example: 100.00
                currency:
                  type: string
                  enum:
                    - EUR
                  description: The currency code as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217).
                  example: EUR
                customerId:
                  type: string
                  format: uuid
                  description: The unique id of the customer participating in the transaction.
                  example: 111abc22-33de-4444-5555-111111111111
                merchantId:
                  type: string
                  format: uuid
                  description: The unique id of the merchant participating in the transaction.
                  example: 222abc22-33de-4444-5555-222222222222
                distributorId:
                  type: string
                  format: uuid
                  description: The distributor at which the transaction got created/modified. Available only to merchants which have been configured to receive it.
                  example: 333ddddd-2222-aaff-ccbb-333333333333
                type:
                  $ref: "#/components/schemas/TransactionType"
                state:
                  $ref: "#/components/schemas/TransactionState"
                stateDetails:
                  type: object
                  description: State-specific additional attributes, e.g. declineReason for Declined state
                  properties:
                    declineReason:
                      $ref: "#/components/schemas/TransactionDeclineReason"
                status:
                  $ref: "#/components/schemas/TransactionStatus"
                externalReference:
                  $ref: "#/components/schemas/ExternalReference"
                createdOn:
                  type: string
                  description: The server-generated timestamp of the initial creation of the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
                  format: date-time
                  example: 2019-01-31T11:50:59Z
                lastModifiedOn:
                  type: string
                  format: date-time
                  description: The server-generated timestamp of the last update to the transaction record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
                  example: 2019-01-31T11:59:59Z

    TransactionIntentEventType:
      type: string
      description: The type of the event, defining also the attributes of which entity are to be found in the data property
      enum:
        - TransactionIntentDeclined
        - TransactionIntentCancelled
        - TransactionIntentExpired
        - TransactionIntentFinalized

    TransactionIntentEvent:
      type: object
      description: Fired when a transaction intent state has changed
      allOf:
        - $ref: "#/components/schemas/EventMetadata"
        - type: object
          properties:
            type:
              $ref: "#/components/schemas/TransactionIntentEventType"
            data:
              type: object
              required:
                - id
                - type
                - amount
                - currency
                - customerId
                - merchantId
                - createdOn
                - state
              properties:
                id:
                  type: string
                  format: uuid
                  description: The id of the transaction intent
                  example: 40c7fe9f-3bf9-464a-8d3a-937db20f5dae
                amount:
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
                  description: The amount of the transaction intent. For deposits the maximum is 10.000,00
                  example: 100.00
                currency:
                  type: string
                  enum:
                    - EUR
                  description: The currency code as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217).
                  example: EUR
                customerId:
                  type: string
                  format: uuid
                  description: The unique id of the customer participating in the transaction intent.
                  example: 111abc22-33de-4444-5555-111111111111
                merchantId:
                  type: string
                  format: uuid
                  description: The unique id of the merchant participating in the transaction intent.
                  example: 222abc22-33de-4444-5555-222222222222
                type:
                  $ref: "#/components/schemas/TransactionIntentType"
                state:
                  $ref: "#/components/schemas/TransactionIntentState"
                stateDetails:
                  type: object
                  description: State-specific additional attributes, e.g. declineReason for Declined state
                  properties:
                    declineReason:
                      $ref: "#/components/schemas/TransactionIntentDeclineReason"
                    finalizeReason:
                      $ref: "#/components/schemas/TransactionIntentFinalizeReason"
                externalReference:
                  $ref: "#/components/schemas/ExternalReference"
                createdOn:
                  type: string
                  description: The server-generated timestamp of the initial creation of the transaction intent record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
                  format: date-time
                  example: 2019-01-31T11:50:59Z
                lastModifiedOn:
                  type: string
                  format: date-time
                  description: The server-generated timestamp of the last update to the transaction intent record, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time
                  example: 2019-01-31T11:59:59Z

    EventMetadata:
      description: base set of context attributes that describe event
      type: object
      required:
        - specversion
        - id
        - source
      properties:
        specversion:
          type: string
          description: |
            The version of the CloudEvents specification which the event uses.
            This enables the interpretation of the context.
            Compliant event producers MUST use a value of 1.0 when referring to this version of the specification.
          example: 1.0
        id:
          type: string
          format: uuid
          description: The unique id of the event.
          example: 111abc22-33de-4444-5555-111111111111
        source:
          type: string
          description: Identifies the context in which an event happened
          example: /transaction-service
        time:
          type: string
          format: date-time
          description: Timestamp of when the occurrence happened.
          example: 2019-01-31T11:59:59Z
        datacontenttype:
          type: string
          description: Content type of data value
          example: application/json

    ValidationErrorReason:
      type: object
      description: Contains Validation error metadata
      required:
        - errorMessage
      properties:
        fieldName:
          type: string
          description: name of filed that failed validation
          example: customerId
        errorMessage:
          type: string
          description: error message
          example: Value must not be empty

    NewReversalTransaction:
      type: object
      required:
        - triggeredBy
      properties:
        description:
          type: string
          maxLength: 100
          description: A short text describing the purpose of the transaction
          example: Load into gaming account
        triggeredBy:
          $ref: "#/components/schemas/TriggerSource"
        # autoComplete:
        #   type: boolean
        #   default: true
        #   description: Defines whether the transaction should be automatically completed (Pending->Committed->Completed) or only initiated (Pending->Committed), in case it participates in 2PC. Default value is true.
        externalReference:
          $ref: "#/components/schemas/ExternalReference"

    NewRefundTransaction:
      type: object
      required:
        - triggeredBy
      properties:
        description:
          type: string
          maxLength: 100
          description: A short text describing the purpose of the transaction
          example: Load into gaming account
        triggeredBy:
          $ref: "#/components/schemas/TriggerSource"
        # autoComplete:
        #   type: boolean
        #   default: true
        #   description: Defines whether the transaction should be automatically completed (Pending->Committed->Completed) or only initiated (Pending->Committed), in case it participates in 2PC. Default value is true.
        externalReference:
          $ref: "#/components/schemas/ExternalReference"

x-webhooks: # change to webhooks once openapi version is changed to 3.1.0
  transactionIntentEvent:
    post:
      summary: Transaction Intent Event
      description: Transaction Intent Event
      operationId: handleTransactionIntentEvent
      tags:
        - transaction-intent-event
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionIntentEvent"
      responses:
        "204":
          description: Return a 204 status to indicate that the data was received successfully

  transactionEvent:
    post:
      summary: Transaction Event
      description: Transaction Event
      operationId: handleTransactionEvent
      tags:
        - transaction-event
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionEvent"
      responses:
        "204":
          description: Return a 204 status to indicate that the data was received successfully
