openapi: '3.0.0'
info:
  version: 2.0.0
  title: Payment API
  description: |
    Paytrail Payment API
  contact:
    name: Paytrail
    url: https://github.com/paytrail/api-documentation/issues
servers:
  - url: https://services.paytrail.com
tags:
  - name: payments
    description: Create, fetch or refund payments
  - name: token payments
    description: Tokenize payment cards and issue payments on tokens
  - name: payment reports
    description: Request a payment report
  - name: settlements
    description: List settlement IDs
paths:
  /payments:
    post:
      tags:
        - payments
      summary: Create a new open payment
      description: Create a new open payment, returns a list of available payment methods.
      operationId: createPayment
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: Payment body payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/{transactionId}:
    get:
      tags:
        - payments
      summary: Get a payment by Checkout transaction ID
      description: Get a single payment
      operationId: getPaymentByTransactionId
      parameters:
        - name: transactionId
          in: path
          description: Transaction ID of payment to fetch
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: GET
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      responses:
        '200':
          description: Payment response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Error'

  /payments/{transactionId}/refund:
    post:
      tags:
        - payments
      summary: Refund a payment
      description: |
        Refund a payment by transaction ID. Refund operation is asynchronous. Refund request is validated,
        and if the refund can be done a 201 is returned.
      operationId: refundPaymentByTransactionId
      parameters:
        - name: transactionId
          in: path
          description: Transaction ID of payment to refund
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: Refund payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Refund'
      responses:
        '201':
          description: Refund created succesfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Payment method provider does not support refunds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  #It's recommended to use /payments/{transactionId}/refund instead and provide customer email as a fallback
  /payments/{transactionId}/refund/email:
    post:
      tags:
        - payments
      summary: Refund a payment
      description: |
        Email refunds a payment by transaction ID. If payment provider supports API refunds, API refund will be made instead. Refund operation is asynchronous. Refund request is validated,
        and if the refund can be done a 201 is returned.
      operationId: emailRefundPaymentByTransactionId
      parameters:
        - name: transactionId
          in: path
          description: Transaction ID of payment to refund
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: EmailRefund payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRefund'
      responses:
        '201':
          description: Email refund request received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Used payment method provider does not support email refunds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  /payments/{transactionId}/activate-invoice:
    post:
      tags:
        - payments
      summary: Activate invoice
      description: |
        Manually activate invoice by transaction ID. Can only be used if payment was paid with Collector and is in pending status.
      operationId: activateInvoiceByTransactionId
      parameters:
        - name: transactionId
          in: path
          description: Transaction ID of payment to activate invoice
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      responses:
        '200':
          description: Invoice activated succesfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateInvoiceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Error'

  /merchants/payment-providers:
    get:
      tags:
        - payments
        - providers
      summary: List merchant payment methods
      description: |
        Returns the payment methods available for merchant without creating
        a new payment to the system. Useful for displaying payment provider
        icons during different phases of checkout before finally actually
        creating the payment request when customer decides to pay
      operationId: getPaymentProviders
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: GET
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
        - name: amount
          in: query
          description: |
            Optional amount in minor unit (eg. EUR cents) for the payment providers. Some providers have minimum
            or maximum amounts that can be purchased.
          example: 500
          required: false
          style: form
          schema:
            type: integer
            format: int32
        - name: groups
          in: query
          description: Comma separated list of payment method groups to include in the reply.
          schema:
            type: array
            items:
              type: string
              enum:
                - mobile
                - bank
                - creditcard
                - credit
                - other
          explode: false
          style: form
      responses:
        '200':
          description: Payment methods available
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BasePaymentMethodProvider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'
  /merchants/grouped-payment-providers:
    get:
      tags:
        - payments
        - providers
      summary: List grouped merchant payment methods
      description: |
        Similar to the /merchants/payment-providers, but in addition of a flat
        list of providers, it returns payment group data containing localized
        names, icon URLs and grouped providers, and a localized text
        with a link to the terms of payment.
      operationId: getGroupedPaymentProviders
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: GET
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
        - name: amount
          in: query
          description: |
            Optional amount in minor unit (eg. EUR cents) for the payment providers. Some providers have minimum
            or maximum amounts that can be purchased.
          example: 500
          required: false
          style: form
          schema:
            type: integer
            format: int32
        - name: groups
          in: query
          description: Comma separated list of payment method groups to include in the reply.
          schema:
            type: array
            items:
              type: string
              enum:
                - mobile
                - bank
                - creditcard
                - credit
                - other
          explode: false
          style: form
        - name: language
          in: query
          description: |
            Language code of the language the terms of payment and the payment group names will be localized in.
            Defaults to FI if left undefined
          required: false
          schema:
            type: string
            enum:
              - FI
              - SV
              - EN
          style: form
      responses:
        '200':
          description: Payment methods available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupedPaymentProvidersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /settlements:
    get:
      tags:
        - settlements
      summary: List settlement IDs
      description: |
        Returns settlement IDs
      operationId: listSettlementIds
      parameters:
        - name: startDate
          in: query
          description: Filter out settlements created before given date.
          example: '2019-01-01'
          required: false
          style: form
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter out settlements created after given date.
          example: '2019-01-01'
          required: false
          style: form
          schema:
            type: string
            format: date
        - name: bankReference
          in: query
          description: Only include settlements with the given bank reference
          example: '1234567890-1111'
          required: false
          style: form
          schema:
            type: string
            maxLength: 20
        - name: limit
          in: query
          description: Limit the number of settlement IDs returned
          example: '1'
          required: false
          style: form
          schema:
            type: string
            format: integer
        - name: submerchant
          in: header
          description: Get submerchant's payment report
          example: '695874'
          required: false
          style: simple
          schema:
            type: string
            format: integer
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      responses:
        '200':
          description: List of settlement IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SettlementIdItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Error'

  /tokenization/addcard-form:
    post:
      tags:
        - token payments
      summary: Request a redirect to card addition form
      description: |
        Request a redirect to card addition form. This will redirect user to the card addition form, then back to Checkout servers, and finally to merchant's redirect url.
      operationId: addCardForm
      requestBody:
        description: Add card payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCardFormRequest'
      responses:
        '302':
          description: Redirect to card addition form (or checkout-redirect-cancel-url)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Tokenization not allowed for merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /tokenization/{checkout-tokenization-id}:
    post:
      tags:
        - token payments
      summary: Request a card token for given tokenization id
      description: |
        Use checkout-tokenization-id received from /tokenization/addcard-form redirect to request a token which can be used for payments.
      operationId: requestTokenForTokenizationId
      parameters:
        - name: checkout-tokenization-id
          in: path
          description: Tokenization id received from /tokenization/addcard-form
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: checkout-tokenization-id
          in: header
          description: Tokenization id received from /tokenization/addcard-form
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: Tokenization request payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTokenRequest'
      responses:
        '200':
          description: Tokenization request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenizationRequestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Credit cards and/or AMEX not enabled for merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /payments/token/mit/charge:
    post:
      tags:
        - token payments
      summary: Request merchant initiated transaction charge on token
      description: |
        Request merchant initiated transaction charge on token. This method should be used when charging the customer's card in a context, where the customer is not actively participating in the transaction.
      operationId: tokenMitCharge
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: MIT Charge payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPaymentRequest'
      responses:
        '201':
          description: MIT charge request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/token/mit/authorization-hold:
    post:
      tags:
        - token payments
      summary: Request merchant initiated transaction authorization hold on token
      description: |
        Request merchant initiated transaction authorization hold on token. This method should be used when creating an authorization hold on the customer's card in a context, where the customer is not actively participating in the transaction.
      operationId: tokenMitAuthorizationHold
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: MIT Charge payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPaymentRequest'
      responses:
        '201':
          description: MIT authorization hold request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/token/cit/charge:
    post:
      tags:
        - token payments
      summary: Request customer initiated transaction charge on token
      description: |
        Request customer initiated transaction charge on token. CIT charges can sometimes require further 3DS authentication step-up. See detailed documentation at https://checkoutfinland.github.io/psp-api/#/?id=customer-initiated-transactions-cit
      operationId: tokenCitCharge
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: CIT Charge payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPaymentRequest'
      responses:
        '201':
          description: CIT charge request created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '403':
          description: CIT charge requires 3DS authentication step up. Please redirect user to given URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/token/cit/authorization-hold:
    post:
      tags:
        - token payments
      summary: Request customer initiated transaction authorization hold on token
      description: |
        Request customer initiated transaction authorization hold on token. CIT authorization holds can sometimes require further 3DS authentication step-up. See detailed documentation at https://checkoutfinland.github.io/psp-api/#/?id=customer-initiated-transactions-cit
      operationId: tokenCitAuthorizationHold
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: CIT authorization hold payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPaymentRequest'
      responses:
        '201':
          description: CIT authorization hold request created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '403':
          description: CIT authorization hold requires 3DS authentication step up. Please redirect user to given URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/{transactionId}/token/commit:
    post:
      tags:
        - token payments
      summary: Request committing (charging) of previously created authorization hold on token
      description: |
        Request committing of previously created authorization hold. The final amount committed can either equal or be less than the authorization hold. The committed amount may not exceed the authorization hold. The final items may differ from the ones used when creating the authorization hold.
      operationId: tokenCommit
      parameters:
        - name: transactionId
          in: path
          description: The transaction ID
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: CIT commit payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPaymentRequest'
      responses:
        '201':
          description: CIT authorization hold committed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/{transactionId}/token/revert:
    post:
      tags:
        - token payments
      summary: Revert (removal) of previously created authorization hold on token
      description: |
        Request committing of previously created authorization hold. A successful revert will remove the authorization hold from the payer's bank account.
      operationId: tokenRevert
      parameters:
        - name: transactionId
          in: path
          description: The transaction ID
          required: true
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-transaction-id
          in: header
          description: The same transaction ID as in route
          schema:
            type: string
            format: uuid
            example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: checkout-nonce
          in: header
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
          schema:
            type: string
        - name: platform-name
          in: header
          description: For SaaS services, use the marketing name of the platform (for example, shopify). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, woocommerce-yourcompany). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration.
          schema:
            type: string
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      responses:
        '200':
          description: Authorization hold reverted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMITPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /payments/report:
    post:
      tags:
        - payment reports
      summary: Request a payment report
      description: |
        Request a report of payments to be sent to the given callback url. Callback schema defined in PaymentReportCallbackJSON.
      operationId: requestPaymentReport
      parameters:
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: Payment body payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReportRequest'
      responses:
        '200':
          description: Payment report request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReportRequestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Error'

      callbacks:
        reportReady:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PaymentReportCallbackJSON'
                  application/csv:
                    schema:
                      description: The report as a CSV file
                      type: string
              responses: # Expected responses to the callback message
                '200':
                  description: Your server returns this code if it can accept the callback
                default:
                  description: Your server can not handle callback - will result in re-sending of the report to the given callback url.

  /settlements/{settlementId}/payments/report:
    post:
      tags:
        - payment reports
      summary: Request a report of payments contained in a given settlement
      description: |
        Request a report of payments contained in a given settlement to be sent to the given callback url. Callback schema defined in PaymentReportCallbackJSON.
      operationId: requestPaymentReportBySettlementId
      parameters:
        - name: settlementId
          in: path
          description: Settlement ID
          required: true
          schema:
            type: string
            example: '2397548234'
        - name: checkout-account
          in: header
          description: Merchant ID
          example: 375917
          schema:
            type: integer
            format: int32
        - name: checkout-algorithm
          in: header
          description: HMAC algorithm
          example: sha512
          schema:
            type: string
            enum:
              - sha256
              - sha512
        - name: checkout-method
          in: header
          description: HTTP method of the request
          example: POST
          schema:
            type: string
            enum:
              - GET
              - POST
        - name: checkout-timestamp
          in: header
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          schema:
            type: string
            format: date-time
        - name: signature
          in: header
          description: HMAC signature calculated over the request headers and payload
          schema:
            type: string
      requestBody:
        description: Payment body payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReportBySettlementIdRequest'
      responses:
        '200':
          description: Payment report request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReportRequestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Error'
      callbacks:
        reportReady:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PaymentReportCallbackJSON'
                  application/csv:
                    schema:
                      description: The report as a CSV file
                      type: string
              responses: # Expected responses to the callback message
                '200':
                  description: Your server returns this code if it can accept the callback
                default:
                  description: Your server can not handle callback - will result in re-sending of the report to the given callback url.

components:
  schemas:
    # Payment request payload
    PaymentRequest:
      type: object
      description: Payment request payload
      required:
        - stamp
        - reference
        - amount
        - currency
        - language
        - customer
        - items
        - redirectUrls
      properties:
        stamp:
          type: string
          example: 29858472952
          maxLength: 200
          description: Merchant specific unique stamp
        reference:
          type: string
          example: 9187445
          maxLength: 200
          description: Merchant reference for the payment
        amount:
          type: integer
          format: int64
          example: 1590
          minimum: 0
          maximum: 99999999
          description: Total amount of the payment (sum of items), VAT should be included in amount unless `usePricesWithoutVat` is set to true
        currency:
          type: string
          example: EUR
          enum:
            - EUR
        language:
          type: string
          example: FI
          enum:
            - FI
            - SV
            - EN
          description: Alpha-2 language code for the payment process
        orderId:
          type: string
          maxLength: 60
          description: Order ID. Used for eg. Collector payments order ID. If not given, merchant reference is used instead.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        customer:
          $ref: '#/components/schemas/Customer'
        deliveryAddress:
          $ref: '#/components/schemas/Address'
        invoicingAddress:
          $ref: '#/components/schemas/Address'
        manualInvoiceActivation:
          type: boolean
          example: false
          description: If paid with invoice payment method, the invoice will not be activated automatically immediately. Currently only supported with Collector.
        redirectUrls:
          $ref: '#/components/schemas/Callbacks'
        callbackUrls:
          $ref: '#/components/schemas/Callbacks'
        callbackDelay:
          type: integer
          minimum: 0
          maximum: 900
          example: 60
          description: Callback delay in seconds. If callback URLs and delay are provided, callbacks will be called after the delay.
        groups:
          description: Optionally return only payment methods for selected groups
          type: array
          items:
            type: string
            enum:
              - mobile
              - bank
              - creditcard
              - credit
              - other
        usePricesWithoutVat:
          type: boolean
          example: false
          description: If true, `amount` and `items.unitPrice` should be sent to API without VAT, and final VAT-included prices are calculated by Paytrail's system (with prices rounded to closest cent). Also, when true, items must be included.

    TokenPaymentRequest:
      type: object
      description: Payment request payload
      required:
        - stamp
        - reference
        - amount
        - currency
        - language
        - customer
        - items
        - redirectUrls
        - token
      properties:
        stamp:
          type: string
          example: 29858472952
          maxLength: 200
          description: Merchant specific unique stamp
        reference:
          type: string
          example: 9187445
          maxLength: 200
          description: Merchant reference for the payment
        amount:
          type: integer
          format: int64
          example: 1590
          minimum: 0
          maximum: 99999999
          description: Total amount of the payment (sum of items), VAT included
        currency:
          type: string
          example: EUR
          enum:
            - EUR
        language:
          type: string
          example: FI
          enum:
            - FI
            - SV
            - EN
          description: Alpha-2 language code for the payment process
        orderId:
          type: string
          maxLength: 60
          description: Order ID. Used for eg. Collector payments order ID. If not given, merchant reference is used instead.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        customer:
          $ref: '#/components/schemas/Customer'
        deliveryAddress:
          $ref: '#/components/schemas/Address'
        invoicingAddress:
          $ref: '#/components/schemas/Address'
        redirectUrls:
          $ref: '#/components/schemas/Callbacks'
        callbackUrls:
          $ref: '#/components/schemas/Callbacks'
        callbackDelay:
          type: integer
          minimum: 0
          maximum: 900
          example: 60
          description: Callback delay in seconds. If callback URLs and delay are provided, callbacks will be called after the delay.
        token:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
          description: Payment card token received from request to /tokenization/{checkout-tokenization-id}

    GetTokenRequest:
      type: object
      description: Get token request payload
      required:
        - checkout-tokenization-id
      properties:
        checkout-tokenization-id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426655440000

    Item:
      type: object
      required:
        - unitPrice
        - units
        - vatPercentage
        - productCode
      properties:
        unitPrice:
          type: integer
          format: int64
          example: 1590
          minimum: 0
          maximum: 99999999
          description: Unit price of an item in currency minor unit, eg. EUR cents. VAT should be included in amount unless `usePricesWithoutVat` is set to true.
        units:
          type: integer
          format: int64
          example: 1
          minimum: 1
          maximum: 10000000
          description: Number of units
        vatPercentage:
          type: number
          format: float
          example: 25.5
          minimum: 0
          maximum: 100
          description: Item VAT percentage
        productCode:
          type: string
          example: '#927502759'
          maxLength: 100
          description: Merchant specific product code
        deliveryDate:
          type: string
          format: date
          example: '2018-03-07'
          description: Estimated delivery date
        description:
          type: string
          example: Cat ladder
          maxLength: 1000
          description: Merchant specific product description
        category:
          type: string
          example: shoe
          maxLength: 100
          description: Item product category
        merchant:
          type: string
          example: 375917
          maxLength: 10
          description: Submerchant ID. Required for shop-in-shop payments, leave out from normal payments.
        stamp:
          type: string
          example: 29858472952
          maxLength: 200
          description: Submerchant specific unique stamp. Required for shop-in-shop payments, leave out from normal payments.
        reference:
          type: string
          example: 9187445
          maxLength: 200
          description: Submerchant reference for the item. Required for shop-in-shop payments, leave out from normal payments.
        orderId:
          type: string
          maxLength: 60
          description: Order ID. Used for eg. Collector payments order ID. If not given, merchant reference is used instead.
        commission:
          type: object
          properties:
            merchant:
              type: string
              description: |
                Merchant who get's the commission money. This merchant id can not be deleted, has to be active and
                has to have same reseller with the merchant who initiated/created the webtrade.
              maxLength: 10
            amount:
              type: integer
              format: int32
              description: |
                Commission amount in currency minor unit, eg. EUR cents. VAT not applicable.
                This field is needed only for specific shop-in-shop payments, usually not needed.
              maximum: 99999999

    # Status reporting URLs, either for user browser redirect or server-to-server callback
    # Called on various events
    Callbacks:
      type: object
      required:
        - success
        - cancel
      properties:
        success:
          type: string
          example: 'https://ecom.example.org/success'
          maxLength: 300
          description: |
            URL to call when payment is succesfully paid.
            Can called multiple times; one must ensure idempotency of this endpoint.
        cancel:
          type: string
          example: 'https://ecom.example.org/cancel'
          maxLength: 300
          description: |
            URL to call when payment is cancelled and not fulfilled.
            Can called multiple times; one must ensure idempotency of this endpoint.

    Address:
      type: object
      required:
        - streetAddress
        - postalCode
        - city
        - country
      properties:
        streetAddress:
          type: string
          example: Fake street 123
          maxLength: 200
          description: Street address
        postalCode:
          type: string
          pattern: '^[0-9A-z -]+$'
          example: '00100'
          maxLength: 15
          description: Postal code
        city:
          type: string
          example: Luleå
          maxLength: 200
          description: City
        county:
          type: string
          example: Norrbotten
          maxLength: 200
          description: County or top-level geographic subdivision
        country:
          type: string
          example: SE
          maxLength: 2
          description: Alpha-2 country code

    Customer:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.org
          description: Customer email address
        firstName:
          type: string
          example: John
          description: Customer first name
        lastName:
          type: string
          example: Doe
          description: Customer last name
        phone:
          type: string
          example: +358501234567
          description: Customer phone number
        vatId:
          type: string
          example: FI02454583
          description: Company VAT ID in international format

    TokenCustomerDetails:
      type: object
      required:
        - network_address
        - country_code
      properties:
        network_address:
          type: string
          example: 93.174.192.154
          description: Customer IP address
        country_code:
          type: string
          example: FI
          description: Customer country code

    Card:
      type: object
      required:
        - network_address
        - country_code
      properties:
        type:
          type: string
          description: Card type, for example 'Visa'
          example: Visa
        partial_pan:
          type: string
          description: Last four digits of the card
          example: 0024
        expire_year:
          type: string
          description: Card expiration year
          example: 2023
        expire_month:
          type: string
          description: Card expiration month
          example: 11
        cvc_required:
          type: string
          description: Whether the CVC is required for paying with this card. Can be one of yes, no or not_tested.
          example: no
        bin:
          type: string
          description: First 2 or 6 digits of the card number. (6 MC/VISA, 2 Amex/Diners)
          example: 415301
        funding:
          type: string
          description: credit, debit or unknown
          example: debit
        country_code:
          type: string
          description: e.g. FI
          example: FI
        category:
          type: string
          description: business, prepaid or unknown
          example: unknown
        card_fingerprint:
          type: string
          description: Identifies a specific card number. Cards with the same PAN but different expiry dates will have the same PAN fingerprint. Hex string of length 64.
          example: da6b0df36efd17c0e7f6967b9e440a0c61b6bd3d96b62f14c90155a1fb883597
        pan_fingerprint:
          type: string
          description: Identifies a specific card, including the expiry date. Hex string of length 64.
          example: e858e18daac509247f463292641237d6a74ce44e0971ba2de4a14874928a8805

    CardInfo:
      type: object
      properties:
        partialPan:
          type: string
          description: 'Last digits of payment cards Primary Account Number (PAN)'
          example: '1234'
        countryCode:
          type: string
          description: 'The card issuers ISO 3166-1 alpha-2 country code'
          example: 'FI'
        bin:
          type: string
          description: 'The card issuers Bank Identification Number (BIN)'
          example: '123456'

    # Refund request payload
    # - Normal merchant:
    #   - Only amount required, no need for item level reference
    #     at least for now as we do not create subtrades
    # - SiS merchants:
    #   - Aggregate can do full refund without subtrade level info
    #     by providing just the amount (that matches the original amount)
    #   - Subtrade refunds require the original stamp and reference, and
    #     amount to refund per item
    Refund:
      type: object
      required:
        - callbackUrls
      properties:
        amount:
          type: integer
          format: int64
          example: 1590
          minimum: 1
          description: |
            The amount to refund. Required for normal merchant accounts.
            SiS aggregate can refund the whole purchase by providing just the amount
        refundStamp:
          type: string
          example: 981346945
          maxLength: 200
          description: Merchant specific unique stamp for the refund
        refundReference:
          type: string
          example: 4723652
          maxLength: 200
          description: Merchant reference for the refund
        items:
          type: array
          items:
            $ref: '#/components/schemas/RefundItem'
          description: Item level refund information for SiS refunds.
        callbackUrls:
          $ref: '#/components/schemas/Callbacks'
        email:
          type: string
          format: email
          example: john.doe@example.org
          description: Refund recipient email address as a fallback method if API refund is unsuccessful

    EmailRefund:
      type: object
      required:
        - email
        - callbackUrls
      properties:
        amount:
          type: integer
          format: int64
          example: 1590
          minimum: 1
          description: |
            The amount to refund. Required for normal merchant accounts.
            SiS aggregate can refund the whole purchase by providing just the amount
        items:
          type: array
          items:
            $ref: '#/components/schemas/RefundItem'
          description: Item level refund information for SiS refunds.
        callbackUrls:
          $ref: '#/components/schemas/Callbacks'
        email:
          type: string
          format: email
          example: john.doe@example.org
          description: Refund recipient email address

    RefundItem:
      type: object
      required:
        - amount
        - stamp
        - reference
      properties:
        amount:
          type: integer
          format: int64
          example: 1590
          minimum: 1
          description: Amount to refund
        stamp:
          type: string
          example: 29858472952
          description: Original item stamp
        refundStamp:
          type: string
          example: 7358134945
          maxLength: 200
          description: Merchant specific unique stamp for the refund
        refundReference:
          type: string
          example: 94753246
          maxLength: 200
          description: Merchant reference for the refund

    AddCardFormRequest:
      type: object
      description: Add card form request
      required:
        - checkout-account
        - checkout-algorithm
        - checkout-redirect-success-url
        - checkout-redirect-cancel-url
      properties:
        checkout-account:
          type: integer
          example: 375917
          description: Merchant ID
        checkout-algorithm:
          type: string
          description: HMAC algorithm
          example: sha512
          enum:
            - sha256
            - sha512
        checkout-method:
          type: string
          description: HTTP method of the request
          example: POST
          enum:
            - GET
            - POST
        checkout-nonce:
          type: string
          description: Unique random identifier
          example: 39da40b8-5fb0-499c-869d-35e575b9a6cd
        checkout-timestamp:
          type: string
          description: Current timestamp in ISO 8601 format
          example: '2018-08-08T10:10:59Z'
          format: date-time
        checkout-redirect-success-url:
          type: string
          format: url
          example: https://example.com/redirect-success-handler
          description: Merchant's url for user redirect on successful card addition
        checkout-redirect-cancel-url:
          type: string
          format: url
          example: https://example.com/redirect-failure-handler
          description: Merchant's url for user redirect on failed card addition
        checkout-callback-success-url:
          type: string
          format: url
          example: https://example.com/success-callback
          description: Merchant's url called on successful card addition
        checkout-callback-cancel-url:
          type: string
          format: url
          example: https://example.com/failure-callback
          description: Merchant's url called on failed card addition
        language:
          type: string
          example: FI
          enum:
            - FI
            - SV
            - EN
          description: Alpha-2 language code for the card addition form
        signature:
          type: string
          example: 0634fd04380bbaf5069c8c46a74c7d21df7414888d980c27a16d5e262cb8c9059139c212d0926000faf026e483904cefae2f5e9d9bd5f51fbc2ac4c4de518115
          description: HMAC signature calculated over the request headers and payload

    TokenizationRequestResponse:
      required:
        - token
      properties:
        token:
          type: string
          description: Token used to make authorization holds & charges on card
          example: 123e4567-e89b-12d3-a456-426655440000
        customer:
          $ref: '#/components/schemas/TokenCustomerDetails'
        card:
          $ref: '#/components/schemas/Card'

    PaymentReportRequest:
      type: object
      description: Payment report request
      required:
        - requestType
        - callbackUrl
      properties:
        requestType:
          type: string
          example: json
          description: In which format is the report delivered in
          enum:
            - json
            - csv
        callbackUrl:
          type: string
          format: url
          example: https://example.com/payment-reports/
          description: To which URL is the report delivered to. Callback URLs must use HTTPS
        paymentStatus:
          type: string
          example: default
          description: How are the payments statuses filtered. "Default" includes both paid and settled payments. "Paid" includes paid payments that have not been settled yet. "All" includes everything, for example unpaid or failed payments.
          enum:
            - default
            - all
            - paid
            - settled
          default: default
        startDate:
          type: string
          format: datetime
          example: '2019-01-01T18:00:00'
          description: Filter out payments created before given datetime.
        endDate:
          type: string
          format: datetime
          example: '2019-01-02T20:00:00'
          description: Filter out payments created after given datetime.
        limit:
          type: integer
          example: 1000
          description: Limit the amount of payments included in the report.
          maximum: 50000
          default: 50000
        reportFields:
          type: array
          description: Limit the amount of fields included in the report. By default all fields are included.
          items:
            type: string
            enum:
              [
                entryDate,
                created,
                amount,
                status,
                firstname,
                familyname,
                description,
                reference,
                paymentMethod,
                stamp,
                address,
                postcode,
                postoffice,
                country,
                checkoutReference,
                archiveNumber,
                payerName,
                settlementId,
                settlementDate,
                originalTradeReference,
                vatPercentage,
                vatAmount,
                paymentMethodFee,
                paymentMethodCommission,
                shopInShopCommission,
                shopInShopCommissionVatPercentage,
                shopInShopCommissionVatAmount,
                settlementReference,
                transactionId,
                settlementDueDate,
                companyName,
                vatId,
                refunditems,
                tradeitems,
              ]
        submerchant:
          type: integer
          example: 695874
          description: Get submerchant's payment report
        includeItems:
          type: boolean
          example: true
          description: Include trade items in created payment report

    PaymentRequestResponse:
      type: object
      description: |
        Response for a successful payment request. Mechant ecom site can then either redirect
        the user to the URL given in href, or render the payment provider forms onsite. For
        each payment method an HTML form needs to be rendered using the parameters returned
        for each payment method provider.
      required:
        - transactionId
        - href
        - paymentMethods
      properties:
        transactionId:
          type: string
          format: uuid
          example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: Checkout assigned transaction ID for the payment.
        href:
          type: string
          format: url
          example: https://pay.paytrail.com/pay/93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: Unique URL to hosted payment gateway
        terms:
          type: string
          example: 'By continuing with your payment, you agree to our <a href="https://www.checkout.fi/ehdot-ja-sopimukset/maksuehdot" target="_blank">payment terms & conditions</a>'
          description: Text containing a link to the terms of payment
        groups:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodGroupData'
          description: Contains data about the payment method groups. Contains only the groups found in the response's providers.
        providers:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodProvider'

    TokenMITPaymentResponse:
      type: object
      description: |
        Response for a successful merchant initiated transaction payment request.
      required:
        - transactionId
      properties:
        transactionId:
          type: string
          format: uuid
          example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: Checkout assigned transaction ID for the payment.

    TokenCITPaymentResponse:
      type: object
      description: |
        Response for a successful customer initiated transaction payment request.
      required:
        - transactionId
      properties:
        transactionId:
          type: string
          format: uuid
          example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: Checkout assigned transaction ID for the payment.
        threeDSecureUrl:
          type: string
          format: url
          example: https://some-3ds-provider.com/efa4d1d9-db80-4ea7-a72f-c180ddbcae36
          description: URL for 3DS authentication step-up. If this is returned, merchants needs to redirect customer to this given URL for 3DS authentication.

    PaymentMethodGroupData:
      type: object
      description: ID, name and icon URLs for a payment method group
      required:
        - id
        - name
        - icon
        - svg
      properties:
        id:
          type: string
          example: bank
          description: ID of the group
          enum:
            - mobile
            - bank
            - creditcard
            - credit
        name:
          type: string
          example: Bank payment methods
          description: Localized name of the group
        icon:
          type: string
          format: url
          example: https://static.paytrail.com/static/img/payment-groups/bank.png
          description: URL to the group PNG icon
        svg:
          type: string
          format: url
          example: https://static.paytrail.com/static/img/payment-groups/bank.svg
          description: URL to the group SVG icon (recommended to be used instead if PNG)

    BasePaymentMethodProvider:
      type: object
      required:
        - id
        - name
        - icon
        - group
        - svg
      properties:
        id:
          type: string
          example: osuuspankki
          description: ID of the provider
        name:
          type: string
          example: OP
          description: Display name of the payment method
        svg:
          type: string
          format: url
          example: https://static.paytrail.com/static/img/payment-methods/op-logo.svg
          description: URL to payment method SVG icon (recommended to be used instead if PNG)
        icon:
          type: string
          format: url
          example: https://static.paytrail.com/static/img/op_140x75.png
          description: URL to payment method PNG icon
        group:
          type: string
          example: bank
          enum:
            - mobile
            - bank
            - creditcard
            - credit

    PaymentMethodProvider:
      allOf:
        - $ref: '#/components/schemas/BasePaymentMethodProvider'
        - description: Each payment method provider object describes an HTML form. The payment method parameters need to be posted to defined url in application/x-www-form-urlencoded format.
        - required:
            - name
            - icon
            - url
            - group
            - svg
            - parameters
          properties:
            url:
              type: string
              format: url
              example: https://services.paytrail.com/payments/93ee8d18-10db-410b-92ac-7d6e49369ce3/osuuspankki/redirect
              description: Form action url
            parameters:
              type: array
              items:
                type: object
                required:
                  - name
                  - value
                properties:
                  name:
                    type: string
                    example: VALUUTTALAJI
                    description: Name of the form input
                  value:
                    type: string
                    example: EUR
                    description: Value of the form input

    Payment:
      type: object
      required:
        - transctionId
        - status
        - amount
        - currency
        - stamp
        - reference
        - createdAt
      properties:
        transactionId:
          type: string
          format: uuid
          example: 93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: Transaction ID
        status:
          type: string
          enum:
            - new
            - ok
            - fail
            - pending
            - delayed
            - authorization-hold
          description: Transaction status
        amount:
          type: integer
          format: int64
          example: 1590
        currency:
          type: string
          example: EUR
          enum:
            - EUR
        stamp:
          type: string
          example: 29858472952
        reference:
          type: string
          example: 9187445
        createdAt:
          type: string
          example: '2019-10-30T09:13:00'
        href:
          type: string
          format: url
          example: https://pay.paytrail.com/pay/93ee8d18-10db-410b-92ac-7d6e49369ce3
          description: If transaction is in status 'new', link to the hosted payment gateway
        provider:
          type: string
          example: osuuspankki
          description: If processed, the name of the payment method provider
        filingCode:
          type: string
          description: If paid, the filing code issued by the payment method provider if any
        paidAt:
          type: string
          example: '2019-10-30T09:14:28'
          description: Timestamp when the transaction was paid
        cardInfo:
          $ref: '#/components/schemas/CardInfo'

    # TODO: Once async, response status should be 'pending'
    RefundResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - pending
            - fail
        transactionId:
          type: string
          format: uuid
          description: Checkout transaction ID for the refund
          example: 912b13eb-c8ab-4397-a21a-9e9e1419eebe
        provider:
          type: string
          description: Payment method provider
          example: osuuspankki

    ActivateInvoiceResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - error
        message:
          type: string
          description: Response details
          example: Collector invoice activated

    SettlementIdItem:
      type: object
      description: Settlement ID
      required:
        - id
        - createdAt
        - settledAt
      properties:
        id:
          type: integer
          format: int64
          example: 123456
          description: ID of a settlement
        createdAt:
          type: string
          format: datetime
          example: '2019-01-01T00:00:00+02:00'
          description: When the settlement was formed
        settledAt:
          type: string
          format: datetime
          example: '2019-01-02T04:00:00+02:00'
          description: When the settlement was paid

    PaymentReportBySettlementIdRequest:
      type: object
      description: Payment report request
      required:
        - requestType
        - callbackUrl
      properties:
        requestType:
          type: string
          example: json
          description: In which format is the report delivered in
          enum:
            - json
            - csv
        callbackUrl:
          type: string
          format: url
          example: https://example.com/payment-reports/
          description: To which URL is the report delivered to
        reportFields:
          type: array
          description: Limit the amount of fields included in the report. By default all fields are included.
          items:
            type: string
            enum:
              [
                entryDate,
                created,
                amount,
                status,
                firstname,
                familyname,
                description,
                reference,
                paymentMethod,
                stamp,
                address,
                postcode,
                postoffice,
                country,
                checkoutReference,
                archiveNumber,
                payerName,
                settlementId,
                settlementDate,
                originalTradeReference,
                vatPercentage,
                vatAmount,
                paymentMethodFee,
                paymentMethodCommission,
                shopInShopCommission,
                shopInShopCommissionVatPercentage,
                shopInShopCommissionVatAmount,
                settlementReference,
                transactionId,
                settlementDueDate,
                companyName,
                vatId,
                refunditems,
                tradeitems,
              ]
        submerchant:
          type: integer
          example: 695874
          description: Get submerchant's payment report

    PaymentReportRequestResponse:
      required:
        - requestId
      properties:
        requestId:
          type: string
          description: Request id

    PaymentReportCallbackJSON:
      description: The returned fields can be filtered out by specifying "reportFields" parameter
      properties:
        entryDate:
          type: string
          format: DD-MM-YYYY
          description: When the payment was paid or initialized
          example: '11-06-2019'
        created:
          type: string
          format: HH:mm
          description: Hour and minute of the payment creation
          example: '11:31'
        amount:
          type: number
          format: float
          description: Payment amount in Euros
          example: 15.95
        status:
          type: string
          enum: [New, Paid, waiting for approval, Cancelled, Timeout, Halted, Delayed, Paid and settled]
          description: Payment status
          example: Paid
        firstname:
          type: string
          description: First name
          example: John
        familyname:
          type: string
          description: Last name
          example: Doe
        description:
          type: string
          format: datetime
          description: Payment description
          example: Cat food and rubber boots
        reference:
          type: string
          description: Merchant's reference
          example: 12345-abc
        paymentMethod:
          type: string
          description: Payment method
          example: OP
        stamp:
          type: string
          description: Payment Stamp
          example: CO~1554204687711
        address:
          type: string
          description: Delivery address
          example: Hämeenkatu 16
        postcode:
          type: string
          description: Postal code
          example: '33100'
        postoffice:
          type: string
          description: Post office
          example: Tampere
        country:
          type: string
          description: Country of delivery
          example: Finland
        checkoutReference:
          type: string
          description: Checkout reference
          example: '1031751'
        archiveNumber:
          type: string
          description: Archive number
          example: '81295824808952395'
        payerName:
          type: string
          description: Name from bank
          example: 'DOEJOHN'
        settlementId:
          type: number
          description: Settlement (report) id
          example: 1235678
        settlementDate:
          type: string
          description: When the payment is settled
          format: DD-MM-YYYY
          example: '2019-04-04'
        originalTradeReference:
          type: string
          description: Merchant's reference of the original payment in case of refund
          example: 12345-abc
        vatPercentage:
          type: number
          format: float
          description: Payment VAT percentage
          example: 25.5
        vatAmount:
          type: number
          format: float
          description: Payment VAT amount in Euros
          example: 0.192
        paymentMethodFee:
          type: number
          format: float
          description: Payment method fee in Euros
          example: 0.12
        paymentMethodCommission:
          type: number
          format: float
          description: Payment method commission amount in Euros
          example: 0.024
        shopInShopCommission:
          type: number
          format: float
          description: Payment method commission amount in Euros
          example: 0.8
        shopInShopCommissionVatPercentage:
          type: number
          format: float
          description: Payment method commission VAT percentage
          example: 25.5
        shopInShopCommissionVatAmount:
          type: number
          format: float
          description: Payment method commission VAT amount in Euros
          example: 0.192
        refunditems:
          type: string
          description: Contains a `|` (pipe) -delimited list of *stamp*:*amount* pairs. Pairs are delimited by a `:` (colon). Stamp refers to the payment item's stamp that was refunded.
          example: 'stamp1:400|stamp2:200'
        settlementReference:
          type: string
          description: Settlement reference
          example: '45667372'
        transactionId:
          type: string
          description: Assigned transaction ID for the payment
          example: '5770642a-9a02-4ca2-8eaa-cc6260a78eb6'
        settlementDueDate:
          type: string
          description: When the payment settlement is due
          format: DD-MM-YYYY
          example: '2019-04-10'
        tradeitems:
          type: array
          description: Trade items included in the payment
          items:
            type: object
            properties:
              stamp:
                type: string
                description: Payment item stamp
              amount:
                type: number
                description: Item amount in cents
              description:
                type: string
                description: Item description
              vat:
                type: number
                description: VAT percentage
              code:
                type: string
                description: Product code
              quantity:
                type: number
                description: Quantity
        companyName:
          type: string
          description: Company name
          example: 'Example company'
        vatId:
          type: string
          description: Company VAT ID in international format
          example: 'FI02454583'

    GroupedPaymentProvidersResponse:
      description: List grouped providers response body
      required:
        - terms
        - groups
        - providers
      properties:
        terms:
          type: string
          description: Localized text with a link to payment terms
          example: By continuing with your payment, you agree to our <a href="https://www.checkout.fi/ehdot-ja-sopimukset/maksuehdot" target="_blank">payment terms & conditions</a>
        groups:
          type: array
          description: Payment method group data for all of groups that are included in the query
          items:
            $ref: '#/components/schemas/PaymentMethodGroupDataWithProviders'
        providers:
          type: array
          description: A flat list of payment method providers
          items:
            $ref: '#/components/schemas/PaymentMethodProvider'

    PaymentMethodGroupDataWithProviders:
      allOf:
        - $ref: '#/components/schemas/PaymentMethodGroupData'
        - description: Localized name, icon and providers data for single payment method group
        - required:
            - id
            - name
            - icon
            - svg
            - providers
          properties:
            providers:
              type: array
              items:
                $ref: '#/components/schemas/PaymentMethodProvider'

    Error:
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
          description: Error description
        meta:
          type: array
          items:
            type: string
          description: Possible detailed error descriptions

  responses:
    BadRequest:
      description: Request did not pass input validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'