openapi: 3.0.0
info:
  title: payment-api
  version: '1.2'
servers:
  - url: https://api.paymentic.com/v1_2
  - url: https://api.sandbox.paymentic.com/v1_2
paths:
  /payment/points/{pointId}/channels:
    get:
      tags:
        - point
      summary: Get point channels
      operationId: 4440c7d0cf469183eaa800d67c45f4dc
      parameters:
        - $ref: '#/components/parameters/pointId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GetPointChannelsResource'
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/ping:
    get:
      tags:
        - system
      summary: Ping the API
      operationId: 39ab5ac9557446445aea21805f23dda6
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      message:
                        type: string
                        example: pong
                      environment:
                        type: string
                        enum:
                          - production
                          - sandbox
                        example: sandbox
                      tokenId:
                        type: string
                        example: 2a77157f-7a73-413d-90a1-cd1263533d61
                      clientId:
                        type: string
                        example: 72b631fe
                      version:
                        type: string
                        example: '1.2'
                      scopes:
                        type: array
                        items:
                          type: string
                        example:
                          - '*'
                    type: object
                type: object
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
  /payment/points/{pointId}/transactions/{transactionId}/capture:
    patch:
      tags:
        - transactions
      summary: Capture PAID transaction
      operationId: e15f9e30656b212946ba2a8bf43ac240
      parameters:
        - $ref: '#/components/parameters/pointId'
        - $ref: '#/components/parameters/transactionId'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties: {}
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotActiveExceptionSchema'
                  - $ref: >-
                      #/components/schemas/TransactionInvalidStatusExceptionSchema
                  - $ref: >-
                      #/components/schemas/TransactionAlreadyCapturedExceptionSchema
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/points/{pointId}/transactions:
    get:
      tags:
        - transactions
      summary: List transactions
      operationId: 47fcd32c7ec5775954074ce2835dcb86
      parameters:
        - $ref: '#/components/parameters/pointId'
        - name: filter[status]
          in: query
          required: false
          schema:
            type: string
            example: PAID
        - name: filter[amount]
          in: query
          required: false
          schema:
            type: string
            example: '100.50'
        - name: filter[externalReferenceId]
          in: query
          required: false
          schema:
            type: string
            example: EXT-REF-123
        - name: filter[orderId]
          in: query
          required: false
          schema:
            type: string
            example: ORD-12345
        - name: filter[customerName]
          in: query
          required: false
          schema:
            type: string
            example: John Doe
        - name: filter[customerEmail]
          in: query
          required: false
          schema:
            type: string
            format: email
            example: john@example.com
        - name: filter[blikId]
          in: query
          required: false
          schema:
            type: string
            example: BLIK123
        - name: filter[cardBin]
          in: query
          required: false
          schema:
            type: string
            maxLength: 6
            minLength: 6
            example: '411111'
        - name: filter[providerId]
          in: query
          required: false
          schema:
            type: string
            example: blik
        - name: filter[createdAt]
          in: query
          description: 'Date range in format: YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ'
          required: false
          schema:
            type: string
            example: 2024-01-01T00:00:00Z,2024-12-31T23:59:59Z
        - name: filter[paidAt]
          in: query
          description: 'Date range in format: YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ'
          required: false
          schema:
            type: string
            example: 2024-01-01T00:00:00Z,2024-12-31T23:59:59Z
        - name: query[full]
          in: query
          description: Full-text search across all searchable fields
          required: false
          schema:
            type: string
            example: John
        - name: query[customerName]
          in: query
          description: Search by customer name
          required: false
          schema:
            type: string
            example: John Doe
        - name: query[customerEmail]
          in: query
          description: Search by customer email
          required: false
          schema:
            type: string
            format: email
            example: john@example.com
        - name: query[title]
          in: query
          description: Search by transaction title
          required: false
          schema:
            type: string
            example: 'Order #12345'
        - name: page[number]
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            example: 1
        - name: page[size]
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            example: 25
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GetTransactionsResource'
                  pagination:
                    properties:
                      page:
                        type: integer
                        example: 1
                      pageSize:
                        type: integer
                        example: 25
                      total:
                        type: integer
                        example: 320
                      totalPages:
                        type: integer
                        example: 13
                      from:
                        type: integer
                        example: 1
                        nullable: true
                      to:
                        type: integer
                        example: 25
                        nullable: true
                      links:
                        properties:
                          first:
                            type: string
                            format: url
                            nullable: true
                          prev:
                            type: string
                            format: url
                            nullable: true
                          next:
                            type: string
                            format: url
                            nullable: true
                          last:
                            type: string
                            format: url
                            nullable: true
                        type: object
                    type: object
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
    post:
      tags:
        - transactions
      summary: Create payment transaction
      operationId: a43d6ee9bf688e298d9bc13df5f0cfb4
      parameters:
        - $ref: '#/components/parameters/pointId'
      requestBody:
        description: Create payment transaction
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransactionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CreateTransactionResource'
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotActiveExceptionSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/points/{pointId}/transactions/{transactionId}:
    get:
      tags:
        - transactions
      summary: Get transaction details
      operationId: 8d28ff009955ff4e6df523b67e8f08af
      parameters:
        - $ref: '#/components/parameters/pointId'
        - $ref: '#/components/parameters/transactionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/GetTransactionDetailsResource'
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/TransactionNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/points/{pointId}/transactions/{transactionId}/blik:
    post:
      tags:
        - blik
      summary: Process BLIK transaction
      description: Process a BLIK payment transaction using a 6-digit code
      operationId: 5e10aa570d230a1e6e763b2fdf64227f
      parameters:
        - $ref: '#/components/parameters/pointId'
        - $ref: '#/components/parameters/transactionId'
      requestBody:
        description: BLIK transaction processing data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessBlikTransactionRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProcessBlikTransactionResource'
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: >-
                      #/components/schemas/TransactionInvalidStatusExceptionSchema
                  - $ref: '#/components/schemas/TransactionMissingDataExceptionSchema'
                  - $ref: '#/components/schemas/ProviderNotSupportedExceptionSchema'
                  - $ref: >-
                      #/components/schemas/TransactionBlikProcessingErrorExceptionSchema
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/TransactionNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/points/{pointId}/transactions/{transactionId}/refunds:
    post:
      tags:
        - refunds
      summary: Create transaction refund
      operationId: 3f4669f12ac01ee6d936530b9ea612f0
      parameters:
        - $ref: '#/components/parameters/pointId'
        - $ref: '#/components/parameters/transactionId'
      requestBody:
        description: Create transaction refund
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransactionRefundRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CreateTransactionRefundResource'
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotActiveExceptionSchema'
                  - $ref: '#/components/schemas/PointRefundsDisabledExceptionSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
  /payment/points/{pointId}/transactions/{transactionId}/refunds/{refundId}:
    get:
      tags:
        - refunds
      summary: Get transaction refund details
      operationId: 9a121f305155ab41366670e2fc26a6fa
      parameters:
        - $ref: '#/components/parameters/pointId'
        - $ref: '#/components/parameters/transactionId'
        - $ref: '#/components/parameters/refundId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/GetRefundDetailsResource'
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotActiveExceptionSchema'
                  - $ref: '#/components/schemas/PointRefundsDisabledExceptionSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PointNotFoundExceptionSchema'
                  - $ref: '#/components/schemas/NotFoundHttpExceptionSchema'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedHttpExceptionSchema'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionSchema'
components:
  schemas:
    CreateTransactionRequest:
      required:
        - amount
        - title
      properties:
        amount:
          description: Amount in minor precision with up to 2 decimals
          type: string
          format: decimal
          example: '123.45'
        currency:
          description: ISO 4217 3-letter currency code. Defaults to PLN when omitted.
          type: string
          default: PLN
          maxLength: 3
          minLength: 3
          enum:
            - PLN
            - EUR
          example: PLN
          nullable: true
        title:
          type: string
          maxLength: 64
          minLength: 5
          example: 'Order #12345'
        description:
          type: string
          maxLength: 128
          nullable: true
        externalReferenceId:
          type: string
          maxLength: 64
          nullable: true
        redirect:
          properties:
            success:
              type: string
              format: uri
              maxLength: 255
              nullable: true
            failure:
              type: string
              format: uri
              maxLength: 255
              nullable: true
          type: object
          nullable: true
        customer:
          oneOf:
            - $ref: '#/components/schemas/CustomerDataSchema'
          nullable: true
          type: object
        order:
          oneOf:
            - $ref: '#/components/schemas/OrderDataSchema'
          nullable: true
          type: object
        billingAddress:
          oneOf:
            - $ref: '#/components/schemas/CustomerFullDataSchema'
          nullable: true
        shippingAddress:
          oneOf:
            - $ref: '#/components/schemas/CustomerFullDataSchema'
          nullable: true
        cart:
          type: array
          items:
            properties:
              name:
                type: string
                maxLength: 64
                nullable: true
              quantity:
                type: integer
                minimum: 1
                nullable: true
              unitPrice:
                type: string
                format: decimal
                nullable: true
              type:
                type: string
                default: PRODUCT
                enum:
                  - PRODUCT
                  - SHIPPING
                  - DISCOUNT
                  - SURCHARGE
                  - GIFT_CARD
                nullable: true
              productType:
                type: string
                enum:
                  - PHYSICAL
                  - DIGITAL
                  - SERVICE
                  - VIRTUAL
                nullable: true
              sku:
                type: string
                maximum: 64
                nullable: true
            type: object
          nullable: true
        paymentMethod:
          type: string
          enum:
            - BLIK
            - PBL
            - BNPL
            - CARD
            - MOBILE_WALLET
          example: CARD
          nullable: true
        paymentChannel:
          type: string
          example: null
          nullable: true
        allowedPaymentMethods:
          description: >-
            Whitelist of payment methods (optionally narrowed to a specific
            channel) that the gateway will present to the customer. Cannot be
            combined with hiddenPaymentMethods, paymentMethod or paymentChannel.
            When paymentChannel is null, all channels of that method are
            allowed.
          type: array
          items:
            required:
              - paymentMethod
            properties:
              paymentMethod:
                type: string
                enum:
                  - BLIK
                  - PBL
                  - BNPL
                  - CARD
                  - MW
                  - PAYSAFE
                example: BLIK
              paymentChannel:
                type: string
                example: blik-level0
                nullable: true
            type: object
          nullable: true
        hiddenPaymentMethods:
          description: >-
            List of payment methods (optionally narrowed to a specific channel)
            that the gateway will hide from the customer. Cannot be combined
            with allowedPaymentMethods, paymentMethod or paymentChannel. When
            paymentChannel is null, all channels of that method are hidden.
          type: array
          items:
            required:
              - paymentMethod
            properties:
              paymentMethod:
                type: string
                enum:
                  - BLIK
                  - PBL
                  - BNPL
                  - CARD
                  - MW
                  - PAYSAFE
                example: BNPL
              paymentChannel:
                type: string
                example: null
                nullable: true
            type: object
          nullable: true
        createRegistration:
          description: >-
            If true, store customer payment instrument for recurring
            transactions.
          type: boolean
          nullable: true
        whitelabel:
          type: boolean
          nullable: true
        autoCapture:
          type: boolean
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
      type: object
    ProcessBlikTransactionRequest:
      required:
        - type
        - code
      properties:
        type:
          description: BLIK transaction type
          type: string
          enum:
            - CODE
            - ALIAS
          example: CODE
        code:
          description: 6-digit BLIK code (required when type is CODE)
          type: string
          maxLength: 6
          minLength: 6
          pattern: ^\d{6}$
          example: '777123'
        alias:
          description: Alias data
          required:
            - value
          properties:
            value:
              description: Alias value
              type: string
              maxLength: 64
              example: new-alias-123
            label:
              description: Alias label
              type: string
              maxLength: 35
              example: joh...eo@ex...le.com
            appId:
              description: Alias app ID
              type: string
              maxLength: 64
              example: my-app-id
          type: object
      type: object
    CreateTransactionRefundRequest:
      required:
        - amount
        - title
      properties:
        amount:
          description: Amount in minor precision with up to 2 decimals
          type: string
          format: decimal
          example: '123.45'
        reason:
          description: Reason for refund
          type: string
          maxLength: 64
          nullable: true
        externalReferenceId:
          description: External reference ID
          type: string
          maxLength: 64
      type: object
    GetPointChannelsResource:
      properties:
        id:
          description: Channel ID
          type: string
          example: mbank
          nullable: false
        available:
          description: Whether the channel is available for use
          type: boolean
          example: true
          nullable: false
        method:
          description: Payment method
          type: string
          example: PBL
          nullable: false
        name:
          description: Channel name
          type: string
          example: mBank
          nullable: false
        image:
          description: Channel image
          properties:
            default:
              description: Default channel image
              type: string
              format: url
              example: https://example.com/image.png
              nullable: true
          type: object
        amount:
          description: Minimum and maximum transaction amount
          properties:
            minimum:
              description: Minimum transaction amount
              type: string
              format: decimal
              example: '10.00'
              nullable: false
            maximum:
              description: Maximum transaction amount
              type: string
              format: decimal
              example: '10000.00'
              nullable: false
          type: object
        aliases:
          description: Channel aliases
          type: array
          items:
            type: string
          nullable: true
        currencies:
          description: Supported currencies
          type: array
          items:
            type: string
          nullable: false
        commission:
          description: Commission settings
          properties:
            value:
              description: Commission value
              type: string
              format: decimal
              example: '1.65'
              nullable: true
            minimum:
              description: Minimum commission amount
              type: string
              format: decimal
              example: '0.30'
              nullable: true
            fixed:
              description: Whether commission is fixed
              type: string
              format: decimal
              example: '2.50'
              nullable: true
          type: object
        authorization:
          description: Authorization settings
          properties:
            type:
              description: Authorization type
              type: array
              items:
                type: string
                enum:
                  - REDIRECT
                  - MULTI_FACTOR
                  - SCAN_CODE
                  - APP_NOTIFICATION
          type: object
        paymentType:
          description: Payment type
          type: string
          enum:
            - INSTANT
            - PRE_AUTHORIZATION
            - OFFLINE
          example: INSTANT
          nullable: false
        compliance:
          description: Compliance items for the channel
          type: array
          items:
            properties:
              id:
                description: Compliance item identifier
                type: string
                example: info_gdpr
              type:
                description: Compliance type
                type: string
                enum:
                  - DISPLAYABLE
                  - ACCEPTABLE
                example: DISPLAYABLE
              required:
                type: boolean
                example: false
              checked:
                type: boolean
                example: false
                nullable: true
              content:
                properties:
                  text:
                    type: string
                    example: Administratorem Twoich danych jest Paymentic...
                  html:
                    type: string
                    example: Administratorem Twoich danych jest <b>Paymentic</b>...
                  markdown:
                    type: string
                    example: Administratorem Twoich danych jest **Paymentic**...
                type: object
              links:
                type: array
                items:
                  properties:
                    id:
                      type: string
                      example: privacy_policy
                    label:
                      type: string
                      example: Polityka prywatności
                    url:
                      type: string
                      format: url
                      example: https://example.com/pp.pdf
                  type: object
            type: object
          nullable: true
        enablingAt:
          description: Channel enabling date
          type: string
          format: date-time
          nullable: true
        disablingAt:
          description: Channel disabling date
          type: string
          format: date-time
          nullable: true
      type: object
    CreateTransactionRefundResource:
      properties:
        id:
          $ref: '#/components/parameters/refundId'
        status:
          $ref: '#/components/schemas/RefundStatusSchema'
      type: object
    GetRefundDetailsResource:
      properties:
        id:
          $ref: '#/components/parameters/refundId'
        status:
          $ref: '#/components/schemas/RefundStatusSchema'
        amount:
          description: Refund amount as a string-encoded decimal
          type: string
          example: '123.45'
        reason:
          description: Reason for refund
          type: string
          maxLength: 64
          nullable: true
        externalReferenceId:
          description: External reference ID
          type: string
          maxLength: 64
          nullable: true
        createdAt:
          description: Refund creation timestamp
          type: string
          format: date-time
          nullable: true
        updatedAt:
          description: Refund update timestamp
          type: string
          format: date-time
          nullable: true
      type: object
    CreateTransactionResource:
      properties:
        id:
          description: Transaction ID
          type: string
          example: ABCD-123-XYZ-9876
          nullable: false
        redirectUrl:
          description: Transaction URL
          type: string
          format: url
          example: https://pay.paymentic.com/ABCD-123-XYZ-9876?token=...
          nullable: false
        whitelabel:
          type: object
          example: null
          nullable: true
      type: object
    GetTransactionDetailsResource:
      properties:
        id:
          $ref: '#/components/parameters/transactionId'
        status:
          $ref: '#/components/schemas/TransactionStatusSchema'
        amount:
          description: Transaction amount as a string-encoded decimal
          type: string
          example: '123.45'
          nullable: false
        currency:
          description: ISO 4217 currency code
          type: string
          example: PLN
          nullable: false
        title:
          type: string
          example: 'Order #12345'
          nullable: false
        commission:
          type: string
          example: '1.23'
          nullable: true
        description:
          type: string
          example: 'Payment for order #12345'
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerDataSchema'
        order:
          $ref: '#/components/schemas/OrderDataSchema'
        billingAddress:
          oneOf:
            - $ref: '#/components/schemas/CustomerFullDataSchema'
          nullable: true
        shippingAddress:
          oneOf:
            - $ref: '#/components/schemas/CustomerFullDataSchema'
          nullable: true
        externalReferenceId:
          type: string
          example: EXT-REF-123
          nullable: true
        redirect:
          properties:
            success:
              type: string
              format: url
              example: https://merchant.example/success
              nullable: true
            failure:
              type: string
              format: url
              example: https://merchant.example/failure
              nullable: true
          type: object
          nullable: false
        paymentMethod:
          type: string
          example: VISA
          nullable: true
        paymentChannel:
          type: string
          example: null
          nullable: true
        whitelabel:
          type: boolean
          example: false
          nullable: false
        cart:
          type: array
          items:
            $ref: '#/components/schemas/CartItemSchema'
          nullable: true
        autoCapture:
          type: boolean
          example: true
          nullable: false
        isCaptured:
          type: boolean
          example: false
          nullable: false
        capturedAt:
          type: string
          format: date-time
          nullable: true
        paidAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
      type: object
    GetTransactionsResource:
      properties:
        id:
          $ref: '#/components/schemas/TransactionIdSchema'
        status:
          $ref: '#/components/schemas/TransactionStatusSchema'
        amount:
          description: Transaction amount as a string-encoded decimal
          type: string
          example: '123.45'
          nullable: false
        title:
          type: string
          example: 'Order #12345'
          nullable: false
        commission:
          type: string
          example: '1.23'
          nullable: true
        customerName:
          type: string
          example: John Doe
          nullable: true
        customerEmail:
          type: string
          format: email
          example: john@example.com
          nullable: true
        externalReferenceId:
          type: string
          example: EXT-REF-123
          nullable: true
        paymentMethod:
          type: string
          example: BLIK
          nullable: true
        paymentChannel:
          type: string
          example: blik-psp
          nullable: true
        orderId:
          type: string
          example: ORD-12345
          nullable: true
        blikId:
          type: string
          example: BLIK123
          nullable: true
        cardBin:
          type: string
          example: '411111'
          nullable: true
        paidAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
      type: object
    ProcessBlikTransactionResource:
      properties:
        actionId:
          description: Unique identifier for the BLIK action
          type: string
          format: ulid
          example: 01kaqf5trc82bk6cqqanjcjwnq
        alias:
          description: BLIK alias information
          type: object
          example: null
          nullable: true
      type: object
    MethodNotAllowedHttpExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: METHOD_NOT_ALLOWED
              message:
                type: string
                example: 'Method not allowed for '
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#METHOD_NOT_ALLOWED
              details:
                properties:
                  allowedMethods:
                    type: array
                    items:
                      type: string
                      example: GET
                type: object
            type: object
      type: object
    NotFoundHttpExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: PATH_NOT_FOUND
              message:
                type: string
                example: The path / could not be found
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#PATH_NOT_FOUND
              details:
                type: object
                example: null
                nullable: true
            type: object
      type: object
    PointNotActiveExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: POINT_NOT_ACTIVE
              message:
                type: string
                example: Point not active.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#POINT_NOT_ACTIVE
              details:
                type: object
                example: null
            type: object
      type: object
    PointNotFoundExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: POINT_NOT_FOUND
              message:
                type: string
                example: Point not found.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#POINT_NOT_FOUND
              details:
                type: object
                example: null
            type: object
      type: object
    PointRefundsDisabledExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: POINT_REFUNDS_DISABLED
              message:
                type: string
                example: Point refunds disabled.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#POINT_REFUNDS_DISABLED
              details:
                type: object
                example: null
            type: object
      type: object
    ProviderNotSupportedExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: PROVIDER_NOT_SUPPORTED
              message:
                type: string
                example: Provider not supported
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#PROVIDER_NOT_SUPPORTED
              details:
                type: object
                example: null
            type: object
      type: object
    TransactionAlreadyCapturedExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: TRANSACTION_ALREADY_CAPTURED
              message:
                type: string
                example: Transaction already captured.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#TRANSACTION_ALREADY_CAPTURED
              details:
                type: object
                example: null
            type: object
      type: object
    TransactionBlikProcessingErrorExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: TRANSACTION_BLIK_PROCESSING_ERROR
              message:
                type: string
                example: Transaction BLIK processing error.
              docsUrl:
                type: string
                example: >-
                  https://docs.paymentic.com/errors#TRANSACTION_BLIK_PROCESSING_ERROR
              details:
                properties:
                  blikErrorCode:
                    type: string
                    example: DECLINED
                type: object
            type: object
      type: object
    TransactionInvalidStatusExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: TRANSACTION_INVALID_STATUS
              message:
                type: string
                example: Transaction invalid status.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#TRANSACTION_INVALID_STATUS
              details:
                type: object
                example: null
            type: object
      type: object
    TransactionMissingDataExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: TRANSACTION_MISSING_DATA
              message:
                type: string
                example: Transaction missing data.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#TRANSACTION_MISSING_DATA
              details:
                properties:
                  field:
                    type: string
                    example: customer.email
                type: object
            type: object
      type: object
    TransactionNotFoundExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: TRANSACTION_NOT_FOUND
              message:
                type: string
                example: Transaction not found.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#TRANSACTION_NOT_FOUND
              details:
                type: object
                example: null
            type: object
      type: object
    ValidationExceptionSchema:
      properties:
        errors:
          type: array
          items:
            properties:
              code:
                type: string
                example: VALIDATION_ERROR
              message:
                type: string
                example: The selected pointId is invalid.
              docsUrl:
                type: string
                example: https://docs.paymentic.com/errors#VALIDATION_ERROR
              details:
                properties:
                  field:
                    type: string
                    example: pointId
                  messages:
                    type: array
                    items:
                      type: string
                      example: The selected pointId is invalid.
                type: object
            type: object
      type: object
    CartItemSchema:
      properties:
        name:
          type: string
          maxLength: 64
          example: Harry Potter
          nullable: true
        quantity:
          type: integer
          minimum: 1
          example: 1
          nullable: true
        unitPrice:
          type: string
          format: decimal
          example: '19.99'
          nullable: true
      type: object
    CustomerDataSchema:
      properties:
        name:
          type: string
          maxLength: 64
          pattern: ^[\p{L}' -]+$
          example: John Doe
          nullable: true
        email:
          type: string
          maxLength: 64
          example: john.doe@example.com
          nullable: true
        emailVerified:
          type: boolean
          nullable: true
        phone:
          type: string
          maxLength: 64
          example: '+48123456789'
          nullable: true
        phoneVerified:
          type: boolean
          nullable: true
        country:
          description: ISO 3166-1 alpha-2
          type: string
          maxLength: 2
          minLength: 2
          example: PL
          nullable: true
        locale:
          description: ISO 639-1 alpha-2
          type: string
          maxLength: 2
          minLength: 2
          nullable: true
        ip:
          type: string
          maxLength: 64
          nullable: true
        userAgent:
          type: string
          maxLength: 128
          nullable: true
        fingerprint:
          type: string
          maxLength: 64
          nullable: true
      type: object
    CustomerFullDataSchema:
      properties:
        firstName:
          type: string
          maxLength: 64
          minLength: 2
          pattern: /^[\p{L}'-]+$/u
          example: John
          nullable: true
        lastName:
          type: string
          maxLength: 64
          minLength: 2
          pattern: /^[\p{L}'-]+$/u
          example: Doe
          nullable: true
        street:
          type: string
          maxLength: 64
          example: ul. Kowalska
          nullable: true
        buildingNumber:
          type: string
          maxLength: 16
          example: '26'
          nullable: true
        flat:
          type: string
          maxLength: 16
          nullable: true
        city:
          type: string
          maxLength: 64
          example: Bielsko-Biała
          nullable: true
        region:
          type: string
          maxLength: 64
          nullable: true
        postalCode:
          type: string
          maxLength: 16
          example: 43-316
          nullable: true
        state:
          type: string
          maxLength: 64
          nullable: true
        country:
          type: string
          format: ISO-3166-1 alpha-2
          maxLength: 2
          minLength: 2
          example: PL
          nullable: true
        company:
          type: string
          maxLength: 64
          nullable: true
      type: object
    OrderDataSchema:
      properties:
        id:
          type: string
          maxLength: 64
          nullable: true
        shippingMethod:
          type: string
          enum:
            - VIRTUAL
            - TRACKED_DELIVERY
            - UNTRACKED_DELIVERY
            - IN_STORE_PICKUP
            - PARCEL_PICKUP
            - LOCKER_PICKUP
            - HYBRID
            - OTHER
          nullable: true
        trackingNumber:
          type: string
          nullable: true
        customerType:
          type: string
          enum:
            - B2B
            - B2C
          nullable: true
      type: object
    PointIdSchema:
      type: string
      pattern: ^[0-9a-f]{8}$
      example: b8e6e2fc
    RefundIdSchema:
      type: string
      maxLength: 11
      minLength: 11
      pattern: ^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{3}$
      example: AB1-AB2-AB3
    RefundStatusSchema:
      type: string
      enum:
        - CREATED
        - ACCEPTED
        - PENDING
        - DONE
        - REJECTED
        - CANCELLED
    TransactionIdSchema:
      type: string
      maxLength: 14
      minLength: 14
      pattern: ^[A-Z0-9]{4}-[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{4}$
      example: ABC1-AB2-AB3-ABC4
    TransactionStatusSchema:
      type: string
      enum:
        - CREATED
        - PENDING
        - PAID
        - FAILED
        - EXPIRED
  parameters:
    pointId:
      name: pointId
      in: path
      description: Point ID
      required: true
      schema:
        $ref: '#/components/schemas/PointIdSchema'
    refundId:
      name: refundId
      in: path
      description: Refund ID
      required: true
      schema:
        type: string
        pattern: ^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{3}$
      example: AB1-AB2-AB3
    transactionId:
      name: transactionId
      in: path
      description: Transaction ID
      required: true
      schema:
        $ref: '#/components/schemas/TransactionIdSchema'
    Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        example: application/json
    X-Paymentic-Event:
      name: X-Paymentic-Event
      in: header
      required: true
      schema:
        type: string
        enum:
          - PAYMENT.TRANSACTION_STATUS_CHANGED
          - PAYMENT.REFUND_STATUS_CHANGED
          - PAYMENT.BLIK_ALIAS_STATUS_CHANGED
    X-Paymentic-Notification-Id:
      name: X-Paymentic-Notification-Id
      in: header
      required: true
      schema:
        type: string
        format: ulid
        example: 01j96yn02bhbv8j1jjtk36zn2t
    X-Paymentic-Signature:
      name: X-Paymentic-Signature
      in: header
      required: true
      schema:
        type: string
        example: >-
          5Fil+PpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ==
    X-Paymentic-Time:
      name: X-Paymentic-Time
      in: header
      required: true
      schema:
        type: string
        format: date-time
        example: '2025-01-01T12:00:00+00:00'
    User-Agent:
      name: User-Agent
      in: header
      required: true
      schema:
        type: string
        example: Paymentic/1.2
  securitySchemes:
    bearerToken:
      type: apiKey
      name: Authorization
      in: header
tags:
  - name: point
    description: point
  - name: system
    description: system
  - name: transactions
    description: transactions
  - name: blik
    description: blik
  - name: refunds
    description: refunds
