qpay-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc257f4bb9cb15d977730172bacef5f3a8541626115dab42d5e4aacb211f60cd
+  data.tar.gz: 4f41766daa7f8b795db58f60134484eddfa4a554c081172d93ea8ef106fcc3a6
+SHA512:
+  metadata.gz: 9796ce71359a8402226a70b0193426289e0d53e57b3d932119f6d090c9857151563f3fbe1a28885b3979fca79d9d87fce04e4a9650a1b2f20123bfb04a6e32e4
+  data.tar.gz: 399a6092fe9bfa1bd9f1cfba6da767cd8d6348b0d784ae147874591727d330943fbd819347a9335678865bb60cf2de4a80b4ee04bf9a90a61790bea5d43b4cc5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 QPay Ruby SDK Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/qpay/client.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module QPay
+  class Client
+    include Endpoints::Auth
+    include Endpoints::Invoices
+    include Endpoints::Payments
+    include Endpoints::Ebarimt
+
+    TOKEN_BUFFER_SECONDS = 30
+
+    # Creates a new QPay client.
+    #
+    # @param config [QPay::Config] the configuration object
+    # @param faraday [Faraday::Connection, nil] optional custom Faraday connection
+    def initialize(config:, faraday: nil)
+      @config = config
+      @mutex = Mutex.new
+      @access_token = nil
+      @refresh_token = nil
+      @expires_at = 0
+      @refresh_expires_at = 0
+
+      @http = faraday || Faraday.new do |f|
+        f.options.timeout = 30
+        f.options.open_timeout = 10
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    private
+
+    def ensure_token
+      now = Time.now.to_i
+
+      can_refresh = false
+      refresh_tok = nil
+
+      @mutex.synchronize do
+        # Access token still valid
+        if @access_token && now < @expires_at - TOKEN_BUFFER_SECONDS
+          return
+        end
+
+        can_refresh = @refresh_token && !@refresh_token.empty? && now < @refresh_expires_at - TOKEN_BUFFER_SECONDS
+        refresh_tok = @refresh_token
+      end
+
+      # Try refresh first
+      if can_refresh
+        begin
+          token = do_refresh_token_http(refresh_tok)
+          store_token(token)
+          return
+        rescue QPay::Error
+          # Refresh failed, fall through to get new token
+        end
+      end
+
+      # Both expired or no tokens, get new token
+      token = get_token_request
+      store_token(token)
+    end
+
+    def store_token(token)
+      @mutex.synchronize do
+        @access_token = token.access_token
+        @refresh_token = token.refresh_token
+        @expires_at = token.expires_in
+        @refresh_expires_at = token.refresh_expires_in
+      end
+    end
+
+    def do_request(method, path, body: nil)
+      ensure_token
+
+      url = "#{@config.base_url}#{path}"
+      access_tok = @mutex.synchronize { @access_token }
+
+      response = @http.run_request(method.downcase.to_sym, url, body, {}) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.headers["Authorization"] = "Bearer #{access_tok}"
+      end
+
+      handle_response(response)
+    end
+
+    def do_basic_auth_request(method, path)
+      url = "#{@config.base_url}#{path}"
+
+      response = @http.run_request(method.downcase.to_sym, url, nil, {}) do |req|
+        req.headers["Authorization"] = "Basic #{basic_auth_credentials}"
+      end
+
+      body = response.body
+
+      unless response.success?
+        parsed = parse_json(body)
+        code = parsed["error"]
+        message = parsed["message"] || body
+        raise QPay::Error.new(
+          status_code: response.status,
+          code: code.nil? || code.empty? ? status_text(response.status) : code,
+          message: message.nil? || message.empty? ? body : message,
+          raw_body: body
+        )
+      end
+
+      parsed = parse_json(body)
+      build_token_response(parsed)
+    end
+
+    def handle_response(response)
+      body = response.body
+
+      unless response.success?
+        parsed = parse_json(body)
+        code = parsed["error"]
+        message = parsed["message"]
+        raise QPay::Error.new(
+          status_code: response.status,
+          code: code.nil? || code.empty? ? status_text(response.status) : code,
+          message: message.nil? || message.empty? ? body : message,
+          raw_body: body
+        )
+      end
+
+      return nil if body.nil? || body.empty?
+
+      parse_json(body)
+    end
+
+    def serialize(obj)
+      hash = obj.to_h.compact.transform_keys { |k| camelize_key(k) }
+      deep_serialize(hash).to_json
+    end
+
+    def deep_serialize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), result|
+          result[k] = deep_serialize(v)
+        end
+      when Array
+        obj.map { |item| deep_serialize(item) }
+      when Struct
+        deep_serialize(obj.to_h.compact.transform_keys { |k| camelize_key(k) })
+      else
+        obj
+      end
+    end
+
+    # Converts Ruby snake_case keys to the JSON keys expected by QPay API.
+    # Most keys are simple snake_case, but some need special handling.
+    KEY_MAP = {
+      "qpay_short_url" => "qPay_shortUrl",
+      "obj_id" => "object_id",
+    }.freeze
+
+    def camelize_key(key)
+      str = key.to_s
+      KEY_MAP.fetch(str, str)
+    end
+
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def basic_auth_credentials
+      require "base64"
+      Base64.strict_encode64("#{@config.username}:#{@config.password}")
+    end
+
+    def status_text(code)
+      Rack::Utils::HTTP_STATUS_CODES[code] || "Unknown Status"
+    rescue NameError
+      # Rack not available, use basic mapping
+      HTTP_STATUS_TEXTS.fetch(code, "Unknown Status")
+    end
+
+    HTTP_STATUS_TEXTS = {
+      200 => "OK",
+      201 => "Created",
+      204 => "No Content",
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      409 => "Conflict",
+      422 => "Unprocessable Entity",
+      429 => "Too Many Requests",
+      500 => "Internal Server Error",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+    }.freeze
+  end
+end

data/lib/qpay/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module QPay
+  class Config
+    attr_accessor :base_url, :username, :password, :invoice_code, :callback_url
+
+    def initialize(base_url:, username:, password:, invoice_code:, callback_url:)
+      @base_url = base_url
+      @username = username
+      @password = password
+      @invoice_code = invoice_code
+      @callback_url = callback_url
+    end
+
+    # Loads configuration from environment variables.
+    # Raises ArgumentError if any required variable is missing.
+    def self.from_env
+      mapping = {
+        "QPAY_BASE_URL" => :base_url,
+        "QPAY_USERNAME" => :username,
+        "QPAY_PASSWORD" => :password,
+        "QPAY_INVOICE_CODE" => :invoice_code,
+        "QPAY_CALLBACK_URL" => :callback_url,
+      }
+
+      values = {}
+      missing = []
+
+      mapping.each do |env_var, key|
+        val = ENV[env_var]
+        if val.nil? || val.empty?
+          missing << env_var
+        else
+          values[key] = val
+        end
+      end
+
+      unless missing.empty?
+        raise ArgumentError, "required environment variable(s) not set: #{missing.join(", ")}"
+      end
+
+      new(**values)
+    end
+  end
+end

data/lib/qpay/endpoints/auth.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module QPay
+  module Endpoints
+    module Auth
+      # Authenticates with QPay using Basic Auth and returns a new token pair.
+      # Also stores the token for subsequent requests.
+      #
+      # @return [QPay::TokenResponse]
+      def get_token
+        token = get_token_request
+        store_token(token)
+        token
+      end
+
+      # Uses the current refresh token to obtain a new access token.
+      #
+      # @return [QPay::TokenResponse]
+      def refresh_token
+        refresh_tok = @mutex.synchronize { @refresh_token }
+        token = do_refresh_token_http(refresh_tok)
+        store_token(token)
+        token
+      end
+
+      private
+
+      def get_token_request
+        do_basic_auth_request("POST", "/v2/auth/token")
+      end
+
+      def do_refresh_token_http(refresh_tok)
+        url = "#{@config.base_url}/v2/auth/refresh"
+        response = @http.post(url) do |req|
+          req.headers["Authorization"] = "Bearer #{refresh_tok}"
+        end
+
+        handle_token_response(response)
+      end
+
+      def handle_token_response(response)
+        body = response.body
+
+        unless response.success?
+          parsed = parse_json(body)
+          raise QPay::Error.new(
+            status_code: response.status,
+            code: parsed["error"],
+            message: parsed["message"] || body,
+            raw_body: body
+          )
+        end
+
+        parsed = parse_json(body)
+        build_token_response(parsed)
+      end
+
+      def build_token_response(data)
+        QPay::TokenResponse.new(
+          token_type: data["token_type"],
+          refresh_expires_in: data["refresh_expires_in"],
+          refresh_token: data["refresh_token"],
+          access_token: data["access_token"],
+          expires_in: data["expires_in"],
+          scope: data["scope"],
+          not_before_policy: data["not-before-policy"],
+          session_state: data["session_state"]
+        )
+      end
+    end
+  end
+end

data/lib/qpay/endpoints/ebarimt.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module QPay
+  module Endpoints
+    module Ebarimt
+      # Creates an ebarimt (electronic tax receipt) for a payment.
+      # POST /v2/ebarimt_v3/create
+      #
+      # @param request [QPay::CreateEbarimtRequest]
+      # @return [QPay::EbarimtResponse]
+      def create_ebarimt(request)
+        data = do_request("POST", "/v2/ebarimt_v3/create", body: serialize(request))
+        build_ebarimt_response(data)
+      end
+
+      # Cancels an ebarimt by payment ID.
+      # DELETE /v2/ebarimt_v3/{id}
+      #
+      # @param payment_id [String]
+      # @return [QPay::EbarimtResponse]
+      def cancel_ebarimt(payment_id)
+        data = do_request("DELETE", "/v2/ebarimt_v3/#{payment_id}")
+        build_ebarimt_response(data)
+      end
+
+      private
+
+      def build_ebarimt_response(data)
+        return nil if data.nil?
+
+        items = (data["barimt_items"] || []).map do |item|
+          QPay::EbarimtItem.new(
+            id: item["id"],
+            barimt_id: item["barimt_id"],
+            merchant_product_code: item["merchant_product_code"],
+            tax_product_code: item["tax_product_code"],
+            bar_code: item["bar_code"],
+            name: item["name"],
+            unit_price: item["unit_price"],
+            quantity: item["quantity"],
+            amount: item["amount"],
+            city_tax_amount: item["city_tax_amount"],
+            vat_amount: item["vat_amount"],
+            note: item["note"],
+            created_by: item["created_by"],
+            created_date: item["created_date"],
+            updated_by: item["updated_by"],
+            updated_date: item["updated_date"],
+            status: item["status"]
+          )
+        end
+
+        histories = (data["barimt_histories"] || []).map do |h|
+          QPay::EbarimtHistory.new(
+            id: h["id"],
+            barimt_id: h["barimt_id"],
+            ebarimt_receiver_type: h["ebarimt_receiver_type"],
+            ebarimt_receiver: h["ebarimt_receiver"],
+            ebarimt_register_no: h["ebarimt_register_no"],
+            ebarimt_bill_id: h["ebarimt_bill_id"],
+            ebarimt_date: h["ebarimt_date"],
+            ebarimt_mac_address: h["ebarimt_mac_address"],
+            ebarimt_internal_code: h["ebarimt_internal_code"],
+            ebarimt_bill_type: h["ebarimt_bill_type"],
+            ebarimt_qr_data: h["ebarimt_qr_data"],
+            ebarimt_lottery: h["ebarimt_lottery"],
+            ebarimt_lottery_msg: h["ebarimt_lottery_msg"],
+            ebarimt_error_code: h["ebarimt_error_code"],
+            ebarimt_error_msg: h["ebarimt_error_msg"],
+            ebarimt_response_code: h["ebarimt_response_code"],
+            ebarimt_response_msg: h["ebarimt_response_msg"],
+            note: h["note"],
+            barimt_status: h["barimt_status"],
+            barimt_status_date: h["barimt_status_date"],
+            ebarimt_sent_email: h["ebarimt_sent_email"],
+            ebarimt_receiver_phone: h["ebarimt_receiver_phone"],
+            tax_type: h["tax_type"],
+            created_by: h["created_by"],
+            created_date: h["created_date"],
+            updated_by: h["updated_by"],
+            updated_date: h["updated_date"],
+            status: h["status"]
+          )
+        end
+
+        QPay::EbarimtResponse.new(
+          id: data["id"],
+          ebarimt_by: data["ebarimt_by"],
+          g_wallet_id: data["g_wallet_id"],
+          g_wallet_customer_id: data["g_wallet_customer_id"],
+          ebarimt_receiver_type: data["ebarimt_receiver_type"],
+          ebarimt_receiver: data["ebarimt_receiver"],
+          ebarimt_district_code: data["ebarimt_district_code"],
+          ebarimt_bill_type: data["ebarimt_bill_type"],
+          g_merchant_id: data["g_merchant_id"],
+          merchant_branch_code: data["merchant_branch_code"],
+          merchant_terminal_code: data["merchant_terminal_code"],
+          merchant_staff_code: data["merchant_staff_code"],
+          merchant_register_no: data["merchant_register_no"],
+          g_payment_id: data["g_payment_id"],
+          paid_by: data["paid_by"],
+          object_type: data["object_type"],
+          obj_id: data["object_id"],
+          amount: data["amount"],
+          vat_amount: data["vat_amount"],
+          city_tax_amount: data["city_tax_amount"],
+          ebarimt_qr_data: data["ebarimt_qr_data"],
+          ebarimt_lottery: data["ebarimt_lottery"],
+          note: data["note"],
+          barimt_status: data["barimt_status"],
+          barimt_status_date: data["barimt_status_date"],
+          ebarimt_sent_email: data["ebarimt_sent_email"],
+          ebarimt_receiver_phone: data["ebarimt_receiver_phone"],
+          tax_type: data["tax_type"],
+          merchant_tin: data["merchant_tin"],
+          ebarimt_receipt_id: data["ebarimt_receipt_id"],
+          created_by: data["created_by"],
+          created_date: data["created_date"],
+          updated_by: data["updated_by"],
+          updated_date: data["updated_date"],
+          status: data["status"],
+          barimt_items: items,
+          barimt_transactions: data["barimt_transactions"] || [],
+          barimt_histories: histories
+        )
+      end
+    end
+  end
+end

data/lib/qpay/endpoints/invoices.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module QPay
+  module Endpoints
+    module Invoices
+      # Creates a detailed invoice with full options.
+      # POST /v2/invoice
+      #
+      # @param request [QPay::CreateInvoiceRequest]
+      # @return [QPay::InvoiceResponse]
+      def create_invoice(request)
+        data = do_request("POST", "/v2/invoice", body: serialize(request))
+        build_invoice_response(data)
+      end
+
+      # Creates a simple invoice with minimal fields.
+      # POST /v2/invoice
+      #
+      # @param request [QPay::CreateSimpleInvoiceRequest]
+      # @return [QPay::InvoiceResponse]
+      def create_simple_invoice(request)
+        data = do_request("POST", "/v2/invoice", body: serialize(request))
+        build_invoice_response(data)
+      end
+
+      # Creates an invoice with ebarimt (tax) information.
+      # POST /v2/invoice
+      #
+      # @param request [QPay::CreateEbarimtInvoiceRequest]
+      # @return [QPay::InvoiceResponse]
+      def create_ebarimt_invoice(request)
+        data = do_request("POST", "/v2/invoice", body: serialize(request))
+        build_invoice_response(data)
+      end
+
+      # Cancels an existing invoice by ID.
+      # DELETE /v2/invoice/{id}
+      #
+      # @param invoice_id [String]
+      # @return [void]
+      def cancel_invoice(invoice_id)
+        do_request("DELETE", "/v2/invoice/#{invoice_id}")
+        nil
+      end
+
+      private
+
+      def build_invoice_response(data)
+        return nil if data.nil?
+
+        urls = (data["urls"] || []).map do |u|
+          QPay::Deeplink.new(
+            name: u["name"],
+            description: u["description"],
+            logo: u["logo"],
+            link: u["link"]
+          )
+        end
+
+        QPay::InvoiceResponse.new(
+          invoice_id: data["invoice_id"],
+          qr_text: data["qr_text"],
+          qr_image: data["qr_image"],
+          qpay_short_url: data["qPay_shortUrl"],
+          urls: urls
+        )
+      end
+    end
+  end
+end

data/lib/qpay/endpoints/payments.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module QPay
+  module Endpoints
+    module Payments
+      # Retrieves payment details by payment ID.
+      # GET /v2/payment/{id}
+      #
+      # @param payment_id [String]
+      # @return [QPay::PaymentDetail]
+      def get_payment(payment_id)
+        data = do_request("GET", "/v2/payment/#{payment_id}")
+        build_payment_detail(data)
+      end
+
+      # Checks if a payment has been made for an invoice.
+      # POST /v2/payment/check
+      #
+      # @param request [QPay::PaymentCheckRequest]
+      # @return [QPay::PaymentCheckResponse]
+      def check_payment(request)
+        data = do_request("POST", "/v2/payment/check", body: serialize(request))
+        build_payment_check_response(data)
+      end
+
+      # Returns a list of payments matching the given criteria.
+      # POST /v2/payment/list
+      #
+      # @param request [QPay::PaymentListRequest]
+      # @return [QPay::PaymentListResponse]
+      def list_payments(request)
+        data = do_request("POST", "/v2/payment/list", body: serialize(request))
+        build_payment_list_response(data)
+      end
+
+      # Cancels a payment (card transactions only).
+      # DELETE /v2/payment/cancel/{id}
+      #
+      # @param payment_id [String]
+      # @param request [QPay::PaymentCancelRequest, nil]
+      # @return [void]
+      def cancel_payment(payment_id, request: nil)
+        do_request("DELETE", "/v2/payment/cancel/#{payment_id}", body: request ? serialize(request) : nil)
+        nil
+      end
+
+      # Refunds a payment (card transactions only).
+      # DELETE /v2/payment/refund/{id}
+      #
+      # @param payment_id [String]
+      # @param request [QPay::PaymentRefundRequest, nil]
+      # @return [void]
+      def refund_payment(payment_id, request: nil)
+        do_request("DELETE", "/v2/payment/refund/#{payment_id}", body: request ? serialize(request) : nil)
+        nil
+      end
+
+      private
+
+      def build_card_transactions(items)
+        (items || []).map do |ct|
+          QPay::CardTransaction.new(
+            card_merchant_code: ct["card_merchant_code"],
+            card_terminal_code: ct["card_terminal_code"],
+            card_number: ct["card_number"],
+            card_type: ct["card_type"],
+            is_cross_border: ct["is_cross_border"],
+            amount: ct["amount"],
+            transaction_amount: ct["transaction_amount"],
+            currency: ct["currency"],
+            transaction_currency: ct["transaction_currency"],
+            date: ct["date"],
+            transaction_date: ct["transaction_date"],
+            status: ct["status"],
+            transaction_status: ct["transaction_status"],
+            settlement_status: ct["settlement_status"],
+            settlement_status_date: ct["settlement_status_date"]
+          )
+        end
+      end
+
+      def build_p2p_transactions(items)
+        (items || []).map do |pt|
+          QPay::P2PTransaction.new(
+            transaction_bank_code: pt["transaction_bank_code"],
+            account_bank_code: pt["account_bank_code"],
+            account_bank_name: pt["account_bank_name"],
+            account_number: pt["account_number"],
+            status: pt["status"],
+            amount: pt["amount"],
+            currency: pt["currency"],
+            settlement_status: pt["settlement_status"]
+          )
+        end
+      end
+
+      def build_payment_detail(data)
+        return nil if data.nil?
+
+        QPay::PaymentDetail.new(
+          payment_id: data["payment_id"],
+          payment_status: data["payment_status"],
+          payment_fee: data["payment_fee"],
+          payment_amount: data["payment_amount"],
+          payment_currency: data["payment_currency"],
+          payment_date: data["payment_date"],
+          payment_wallet: data["payment_wallet"],
+          transaction_type: data["transaction_type"],
+          object_type: data["object_type"],
+          obj_id: data["object_id"],
+          next_payment_date: data["next_payment_date"],
+          next_payment_datetime: data["next_payment_datetime"],
+          card_transactions: build_card_transactions(data["card_transactions"]),
+          p2p_transactions: build_p2p_transactions(data["p2p_transactions"])
+        )
+      end
+
+      def build_payment_check_response(data)
+        return nil if data.nil?
+
+        rows = (data["rows"] || []).map do |row|
+          QPay::PaymentCheckRow.new(
+            payment_id: row["payment_id"],
+            payment_status: row["payment_status"],
+            payment_amount: row["payment_amount"],
+            trx_fee: row["trx_fee"],
+            payment_currency: row["payment_currency"],
+            payment_wallet: row["payment_wallet"],
+            payment_type: row["payment_type"],
+            next_payment_date: row["next_payment_date"],
+            next_payment_datetime: row["next_payment_datetime"],
+            card_transactions: build_card_transactions(row["card_transactions"]),
+            p2p_transactions: build_p2p_transactions(row["p2p_transactions"])
+          )
+        end
+
+        QPay::PaymentCheckResponse.new(
+          count: data["count"],
+          paid_amount: data["paid_amount"],
+          rows: rows
+        )
+      end
+
+      def build_payment_list_response(data)
+        return nil if data.nil?
+
+        rows = (data["rows"] || []).map do |row|
+          QPay::PaymentListItem.new(
+            payment_id: row["payment_id"],
+            payment_date: row["payment_date"],
+            payment_status: row["payment_status"],
+            payment_fee: row["payment_fee"],
+            payment_amount: row["payment_amount"],
+            payment_currency: row["payment_currency"],
+            payment_wallet: row["payment_wallet"],
+            payment_name: row["payment_name"],
+            payment_description: row["payment_description"],
+            qr_code: row["qr_code"],
+            paid_by: row["paid_by"],
+            object_type: row["object_type"],
+            obj_id: row["object_id"]
+          )
+        end
+
+        QPay::PaymentListResponse.new(
+          count: data["count"],
+          rows: rows
+        )
+      end
+    end
+  end
+end

data/lib/qpay/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module QPay
+  class Error < StandardError
+    attr_reader :status_code, :code, :raw_body
+
+    def initialize(status_code:, code: nil, message: nil, raw_body: nil)
+      @status_code = status_code
+      @code = code
+      @raw_body = raw_body
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(msg)
+      "qpay: #{@code} - #{msg} (status #{@status_code})"
+    end
+  end
+
+  # Returns [QPay::Error, true] if the error is a QPay::Error, [nil, false] otherwise.
+  def self.qpay_error?(err)
+    if err.is_a?(QPay::Error)
+      [err, true]
+    else
+      [nil, false]
+    end
+  end
+
+  # Error code constants
+  ACCOUNT_BANK_DUPLICATED              = "ACCOUNT_BANK_DUPLICATED"
+  ACCOUNT_SELECTION_INVALID            = "ACCOUNT_SELECTION_INVALID"
+  AUTHENTICATION_FAILED                = "AUTHENTICATION_FAILED"
+  BANK_ACCOUNT_NOTFOUND                = "BANK_ACCOUNT_NOTFOUND"
+  BANK_MCC_ALREADY_ADDED               = "BANK_MCC_ALREADY_ADDED"
+  BANK_MCC_NOT_FOUND                   = "BANK_MCC_NOT_FOUND"
+  CARD_TERMINAL_NOTFOUND               = "CARD_TERMINAL_NOTFOUND"
+  CLIENT_NOTFOUND                      = "CLIENT_NOTFOUND"
+  CLIENT_USERNAME_DUPLICATED           = "CLIENT_USERNAME_DUPLICATED"
+  CUSTOMER_DUPLICATE                   = "CUSTOMER_DUPLICATE"
+  CUSTOMER_NOTFOUND                    = "CUSTOMER_NOTFOUND"
+  CUSTOMER_REGISTER_INVALID            = "CUSTOMER_REGISTER_INVALID"
+  EBARIMT_CANCEL_NOTSUPPERDED          = "EBARIMT_CANCEL_NOTSUPPERDED"
+  EBARIMT_NOT_REGISTERED               = "EBARIMT_NOT_REGISTERED"
+  EBARIMT_QR_CODE_INVALID              = "EBARIMT_QR_CODE_INVALID"
+  INFORM_NOTFOUND                      = "INFORM_NOTFOUND"
+  INPUT_CODE_REGISTERED                = "INPUT_CODE_REGISTERED"
+  INPUT_NOTFOUND                       = "INPUT_NOTFOUND"
+  INVALID_AMOUNT                       = "INVALID_AMOUNT"
+  INVALID_OBJECT_TYPE                  = "INVALID_OBJECT_TYPE"
+  INVOICE_ALREADY_CANCELED             = "INVOICE_ALREADY_CANCELED"
+  INVOICE_CODE_INVALID                 = "INVOICE_CODE_INVALID"
+  INVOICE_CODE_REGISTERED              = "INVOICE_CODE_REGISTERED"
+  INVOICE_LINE_REQUIRED                = "INVOICE_LINE_REQUIRED"
+  INVOICE_NOTFOUND                     = "INVOICE_NOTFOUND"
+  INVOICE_PAID                         = "INVOICE_PAID"
+  INVOICE_RECEIVER_DATA_ADDRESS_REQUIRED  = "INVOICE_RECEIVER_DATA_ADDRESS_REQUIRED"
+  INVOICE_RECEIVER_DATA_EMAIL_REQUIRED    = "INVOICE_RECEIVER_DATA_EMAIL_REQUIRED"
+  INVOICE_RECEIVER_DATA_PHONE_REQUIRED    = "INVOICE_RECEIVER_DATA_PHONE_REQUIRED"
+  INVOICE_RECEIVER_DATA_REQUIRED          = "INVOICE_RECEIVER_DATA_REQUIRED"
+  MAX_AMOUNT_ERR                       = "MAX_AMOUNT_ERR"
+  MCC_NOTFOUND                         = "MCC_NOTFOUND"
+  MERCHANT_ALREADY_REGISTERED          = "MERCHANT_ALREADY_REGISTERED"
+  MERCHANT_INACTIVE                    = "MERCHANT_INACTIVE"
+  MERCHANT_NOTFOUND                    = "MERCHANT_NOTFOUND"
+  MIN_AMOUNT_ERR                       = "MIN_AMOUNT_ERR"
+  NO_CREDENDIALS                       = "NO_CREDENDIALS"
+  OBJECT_DATA_ERROR                    = "OBJECT_DATA_ERROR"
+  P2P_TERMINAL_NOTFOUND                = "P2P_TERMINAL_NOTFOUND"
+  PAYMENT_ALREADY_CANCELED             = "PAYMENT_ALREADY_CANCELED"
+  PAYMENT_NOT_PAID                     = "PAYMENT_NOT_PAID"
+  PAYMENT_NOTFOUND                     = "PAYMENT_NOTFOUND"
+  PERMISSION_DENIED                    = "PERMISSION_DENIED"
+  QRACCOUNT_INACTIVE                   = "QRACCOUNT_INACTIVE"
+  QRACCOUNT_NOTFOUND                   = "QRACCOUNT_NOTFOUND"
+  QRCODE_NOTFOUND                      = "QRCODE_NOTFOUND"
+  QRCODE_USED                          = "QRCODE_USED"
+  SENDER_BRANCH_DATA_REQUIRED          = "SENDER_BRANCH_DATA_REQUIRED"
+  TAX_LINE_REQUIRED                    = "TAX_LINE_REQUIRED"
+  TAX_PRODUCT_CODE_REQUIRED            = "TAX_PRODUCT_CODE_REQUIRED"
+  TRANSACTION_NOT_APPROVED             = "TRANSACTION_NOT_APPROVED"
+  TRANSACTION_REQUIRED                 = "TRANSACTION_REQUIRED"
+end

data/lib/qpay/models.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module QPay
+  # --- Auth ---
+
+  TokenResponse = Struct.new(
+    :token_type, :refresh_expires_in, :refresh_token,
+    :access_token, :expires_in, :scope,
+    :not_before_policy, :session_state,
+    keyword_init: true
+  )
+
+  # --- Common nested types ---
+
+  Address = Struct.new(
+    :city, :district, :street, :building,
+    :address, :zipcode, :longitude, :latitude,
+    keyword_init: true
+  )
+
+  SenderBranchData = Struct.new(
+    :register, :name, :email, :phone, :address,
+    keyword_init: true
+  )
+
+  SenderStaffData = Struct.new(
+    :name, :email, :phone,
+    keyword_init: true
+  )
+
+  InvoiceReceiverData = Struct.new(
+    :register, :name, :email, :phone, :address,
+    keyword_init: true
+  )
+
+  Account = Struct.new(
+    :account_bank_code, :account_number, :iban_number,
+    :account_name, :account_currency, :is_default,
+    keyword_init: true
+  )
+
+  Transaction = Struct.new(
+    :description, :amount, :accounts,
+    keyword_init: true
+  )
+
+  InvoiceLine = Struct.new(
+    :tax_product_code, :line_description, :line_quantity,
+    :line_unit_price, :note, :discounts, :surcharges, :taxes,
+    keyword_init: true
+  )
+
+  EbarimtInvoiceLine = Struct.new(
+    :tax_product_code, :line_description, :barcode,
+    :line_quantity, :line_unit_price, :note,
+    :classification_code, :taxes,
+    keyword_init: true
+  )
+
+  TaxEntry = Struct.new(
+    :tax_code, :discount_code, :surcharge_code,
+    :description, :amount, :note,
+    keyword_init: true
+  )
+
+  Deeplink = Struct.new(
+    :name, :description, :logo, :link,
+    keyword_init: true
+  )
+
+  # --- Invoice ---
+
+  CreateInvoiceRequest = Struct.new(
+    :invoice_code, :sender_invoice_no, :sender_branch_code,
+    :sender_branch_data, :sender_staff_data, :sender_staff_code,
+    :invoice_receiver_code, :invoice_receiver_data, :invoice_description,
+    :enable_expiry, :allow_partial, :minimum_amount,
+    :allow_exceed, :maximum_amount, :amount,
+    :callback_url, :sender_terminal_code, :sender_terminal_data,
+    :allow_subscribe, :subscription_interval, :subscription_webhook,
+    :note, :transactions, :lines,
+    keyword_init: true
+  )
+
+  CreateSimpleInvoiceRequest = Struct.new(
+    :invoice_code, :sender_invoice_no, :invoice_receiver_code,
+    :invoice_description, :sender_branch_code, :amount, :callback_url,
+    keyword_init: true
+  )
+
+  CreateEbarimtInvoiceRequest = Struct.new(
+    :invoice_code, :sender_invoice_no, :sender_branch_code,
+    :sender_staff_data, :sender_staff_code, :invoice_receiver_code,
+    :invoice_receiver_data, :invoice_description, :tax_type,
+    :district_code, :callback_url, :lines,
+    keyword_init: true
+  )
+
+  InvoiceResponse = Struct.new(
+    :invoice_id, :qr_text, :qr_image, :qpay_short_url, :urls,
+    keyword_init: true
+  )
+
+  # --- Payment ---
+
+  Offset = Struct.new(
+    :page_number, :page_limit,
+    keyword_init: true
+  )
+
+  PaymentCheckRequest = Struct.new(
+    :object_type, :obj_id, :offset,
+    keyword_init: true
+  )
+
+  PaymentCheckResponse = Struct.new(
+    :count, :paid_amount, :rows,
+    keyword_init: true
+  )
+
+  PaymentCheckRow = Struct.new(
+    :payment_id, :payment_status, :payment_amount,
+    :trx_fee, :payment_currency, :payment_wallet,
+    :payment_type, :next_payment_date, :next_payment_datetime,
+    :card_transactions, :p2p_transactions,
+    keyword_init: true
+  )
+
+  PaymentDetail = Struct.new(
+    :payment_id, :payment_status, :payment_fee,
+    :payment_amount, :payment_currency, :payment_date,
+    :payment_wallet, :transaction_type, :object_type,
+    :obj_id, :next_payment_date, :next_payment_datetime,
+    :card_transactions, :p2p_transactions,
+    keyword_init: true
+  )
+
+  CardTransaction = Struct.new(
+    :card_merchant_code, :card_terminal_code, :card_number,
+    :card_type, :is_cross_border, :amount,
+    :transaction_amount, :currency, :transaction_currency,
+    :date, :transaction_date, :status,
+    :transaction_status, :settlement_status, :settlement_status_date,
+    keyword_init: true
+  )
+
+  P2PTransaction = Struct.new(
+    :transaction_bank_code, :account_bank_code, :account_bank_name,
+    :account_number, :status, :amount,
+    :currency, :settlement_status,
+    keyword_init: true
+  )
+
+  PaymentListRequest = Struct.new(
+    :object_type, :obj_id, :start_date, :end_date, :offset,
+    keyword_init: true
+  )
+
+  PaymentListResponse = Struct.new(
+    :count, :rows,
+    keyword_init: true
+  )
+
+  PaymentListItem = Struct.new(
+    :payment_id, :payment_date, :payment_status,
+    :payment_fee, :payment_amount, :payment_currency,
+    :payment_wallet, :payment_name, :payment_description,
+    :qr_code, :paid_by, :object_type, :obj_id,
+    keyword_init: true
+  )
+
+  PaymentCancelRequest = Struct.new(
+    :callback_url, :note,
+    keyword_init: true
+  )
+
+  PaymentRefundRequest = Struct.new(
+    :callback_url, :note,
+    keyword_init: true
+  )
+
+  # --- Ebarimt ---
+
+  CreateEbarimtRequest = Struct.new(
+    :payment_id, :ebarimt_receiver_type, :ebarimt_receiver,
+    :district_code, :classification_code,
+    keyword_init: true
+  )
+
+  EbarimtResponse = Struct.new(
+    :id, :ebarimt_by, :g_wallet_id, :g_wallet_customer_id,
+    :ebarimt_receiver_type, :ebarimt_receiver, :ebarimt_district_code,
+    :ebarimt_bill_type, :g_merchant_id, :merchant_branch_code,
+    :merchant_terminal_code, :merchant_staff_code, :merchant_register_no,
+    :g_payment_id, :paid_by, :object_type, :obj_id,
+    :amount, :vat_amount, :city_tax_amount,
+    :ebarimt_qr_data, :ebarimt_lottery, :note,
+    :barimt_status, :barimt_status_date, :ebarimt_sent_email,
+    :ebarimt_receiver_phone, :tax_type, :merchant_tin,
+    :ebarimt_receipt_id, :created_by, :created_date,
+    :updated_by, :updated_date, :status,
+    :barimt_items, :barimt_transactions, :barimt_histories,
+    keyword_init: true
+  )
+
+  EbarimtItem = Struct.new(
+    :id, :barimt_id, :merchant_product_code, :tax_product_code,
+    :bar_code, :name, :unit_price, :quantity,
+    :amount, :city_tax_amount, :vat_amount, :note,
+    :created_by, :created_date, :updated_by, :updated_date, :status,
+    keyword_init: true
+  )
+
+  EbarimtHistory = Struct.new(
+    :id, :barimt_id, :ebarimt_receiver_type, :ebarimt_receiver,
+    :ebarimt_register_no, :ebarimt_bill_id, :ebarimt_date,
+    :ebarimt_mac_address, :ebarimt_internal_code, :ebarimt_bill_type,
+    :ebarimt_qr_data, :ebarimt_lottery, :ebarimt_lottery_msg,
+    :ebarimt_error_code, :ebarimt_error_msg,
+    :ebarimt_response_code, :ebarimt_response_msg,
+    :note, :barimt_status, :barimt_status_date,
+    :ebarimt_sent_email, :ebarimt_receiver_phone, :tax_type,
+    :created_by, :created_date, :updated_by, :updated_date, :status,
+    keyword_init: true
+  )
+end

data/lib/qpay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module QPay
+  VERSION = "1.0.0"
+end

data/lib/qpay.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "qpay/version"
+require_relative "qpay/errors"
+require_relative "qpay/config"
+require_relative "qpay/models"
+require_relative "qpay/endpoints/auth"
+require_relative "qpay/endpoints/invoices"
+require_relative "qpay/endpoints/payments"
+require_relative "qpay/endpoints/ebarimt"
+require_relative "qpay/client"

data/qpay.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/qpay/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "qpay-sdk"
+  spec.version = QPay::VERSION
+  spec.authors = ["Usukhbayar"]
+  spec.email = ["coding.usukh@gmail.com"]
+  spec.license = "MIT"
+
+  spec.summary = "QPay V2 API Ruby SDK"
+  spec.description = "Ruby SDK for QPay V2 payment gateway API with auto token management."
+  spec.homepage = "https://github.com/qpay-sdk/qpay-ruby"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.files = Dir["lib/**/*.rb", "LICENSE", "qpay.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: qpay-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Usukhbayar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Ruby SDK for QPay V2 payment gateway API with auto token management.
+email:
+- coding.usukh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/qpay.rb
+- lib/qpay/client.rb
+- lib/qpay/config.rb
+- lib/qpay/endpoints/auth.rb
+- lib/qpay/endpoints/ebarimt.rb
+- lib/qpay/endpoints/invoices.rb
+- lib/qpay/endpoints/payments.rb
+- lib/qpay/errors.rb
+- lib/qpay/models.rb
+- lib/qpay/version.rb
+- qpay.gemspec
+homepage: https://github.com/qpay-sdk/qpay-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/qpay-sdk/qpay-ruby
+  source_code_uri: https://github.com/qpay-sdk/qpay-ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: QPay V2 API Ruby SDK
+test_files: []