openapi: 3.0.3
info:
  title: Session service API
  description: This is an API reference for the Session service.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /sessions:
    post:
      summary: Create a session
      description: >-
        The Session service API enables the creation of transaction sessions,
        supporting various transaction methods such as card payments and
        alternative payment methods (APMs). It facilitates seamless integration
        for payment processing by generating a session that securely collects
        payment details and initiates transactions. This service ensures secure
        and efficient payment flows, improving the user experience across
        multiple payment channels.
      operationId: create-session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
components:
  schemas:
    CreateSessionRequest:
      type: object
      required:
        - merchant
        - site
        - amounts
        - merchantTransactionId
      properties:
        merchant:
          type: string
          description: Your unique merchant identifier, as assigned by PXP.
          example: MERCHANT-1
          maxLength: 20
        site:
          type: string
          description: Your unique site identifier, as assigned by PXP.
          example: SITE-1
          maxLength: 20
        merchantTransactionId:
          type: string
          description: A unique identifier for this transaction.
          example: TRANSACTION-1
          maxLength: 50
        sessionTimeout:
          type: integer
          description: The duration of the session, in minutes.
          example: 120
          minimum: 1
        clientId:
          type: string
          description: The client identifier for the session.
          example: CLIENT-123
          nullable: true
        amounts:
          type: object
          required:
            - currencyCode
            - transactionValue
          properties:
            currencyCode:
              type: string
              description: >-
                The currency code associated with the transaction, in ISO 4217
                format.
              example: EUR
              minLength: 3
              maxLength: 3
            transactionValue:
              type: number
              description: >-
                The transaction amount. The numbers after the decimal will be
                zero padded if they are less than the expected `currencyCode`
                exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or
                BHD 1.3 = 1.300. The transaction will be rejected if numbers
                after the decimal are greater than the expected `currencyCode`
                exponent (e.g., GBP 1.234), or if a decimal is supplied when the
                `currencyCode` of the exponent does not require it (e.g., JPY
                1.0).
              example: 30.32
              minimum: 0
    CreateSessionResponse:
      type: object
      required:
        - sessionId
        - hmacKey
        - encryptionKey
        - sessionExpiry
      properties:
        sessionId:
          type: string
          format: uuid
          description: The unique identifier for the created session.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        hmacKey:
          type: string
          description: The HMAC key generated for securing session communications.
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
        encryptionKey:
          type: string
          description: >-
            A key used for encrypting sensitive session data during
            communication.
          example: k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z
        sessionExpiry:
          type: string
          format: date-time
          description: >-
            The timestamp indicating when the session will expire, in ISO 8601
            format.
          example: '2025-05-19T13:39:20.3843454Z'
        allowedFundingTypes:
          type: object
          description: Details about the funding types allowed for this session.
          properties:
            cards:
              description: The cards allowed for this session.
              type: array
              items:
                type: string
                enum:
                  - AmericanExpress
                  - Diners
                  - Mastercard
                  - Visa
              example:
                - AmericanExpress
                - Diners
                - Mastercard
                - Visa
            wallets:
              $ref: '#/components/schemas/CreateSessionWallets'
    CreateSessionWallets:
      type: object
      description: Details about the wallets allowed for this session.
      properties:
        paypal:
          $ref: '#/components/schemas/CreateSessionPaypalSettings'
        applePay:
          $ref: '#/components/schemas/CreateSessionApplePaySettings'
    CreateSessionPaypalSettings:
      type: object
      description: The PayPal configuration settings.
      properties:
        allowedFundingOptions:
          type: array
          items:
            type: string
          description: The list of allowed funding options for PayPal.
        merchantId:
          type: string
          nullable: true
          description: The PayPal merchant identifier.
    CreateSessionApplePaySettings:
      type: object
      description: The Apple Pay configuration settings.
      properties:
        merchantId:
          type: string
          description: The Apple Pay merchant identifier.
      required:
        - merchantId
