multicard 0.1.0

data/lib/multicard/http_client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Multicard
+  class HttpClient
+    def initialize(config)
+      @config = config
+    end
+
+    def get(path, params: {}, headers: {})
+      request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body: {}, headers: {})
+      request(:post, path, body: body, headers: headers)
+    end
+
+    def delete(path, params: {}, headers: {})
+      request(:delete, path, params: params, headers: headers)
+    end
+
+    def get_with_retry(path, params: {}, headers: {}, retries: 2)
+      request_with_retry(:get, path, params: params, headers: headers, retries: retries)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: nil, headers: {})
+      uri = build_uri(path, params)
+      log_request(method, uri.to_s)
+
+      req = build_request(method, uri, body, headers)
+      raw = execute(uri, req)
+
+      log_response(raw)
+      handle_response(raw)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, "Request timed out: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+      raise NetworkError, "Connection failed: #{e.message}"
+    end
+
+    def request_with_retry(method, path, retries: 2, **options)
+      attempts = 0
+      begin
+        request(method, path, **options)
+      rescue NetworkError, RateLimitError, ServerError
+        attempts += 1
+        raise if attempts > retries
+
+        sleep((2**attempts) * 0.5)
+        retry
+      end
+    end
+
+    def build_uri(path, params)
+      uri = URI("#{@config.base_url}#{path}")
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+      uri
+    end
+
+    def build_request(method, uri, body, headers)
+      req_class = case method
+                  when :get then Net::HTTP::Get
+                  when :post then Net::HTTP::Post
+                  when :delete then Net::HTTP::Delete
+                  else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                  end
+
+      req = req_class.new(uri)
+      req['Accept'] = 'application/json'
+      req['Content-Type'] = 'application/json'
+      headers.each { |key, value| req[key] = value }
+      req.body = body.to_json if body
+      req
+    end
+
+    def execute(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+      http.request(req)
+    end
+
+    def handle_response(raw)
+      status = raw.code.to_i
+      body = parse_body(raw)
+      raise_api_error(status, body) unless status.between?(200, 299)
+
+      Response.new(http_status: status, body: body, headers: response_headers(raw))
+    end
+
+    def parse_body(raw)
+      JSON.parse(raw.body || '', symbolize_names: true)
+    rescue JSON::ParserError
+      { raw: raw.body }
+    end
+
+    def response_headers(raw)
+      headers = {}
+      raw.each_header { |key, value| headers[key] = value }
+      headers
+    end
+
+    def raise_api_error(status, body)
+      error_code = body.dig(:error, :code)
+      error_details = body.dig(:error, :details)
+      error_class = ERROR_MAP[error_code] || error_class_for_status(status)
+
+      raise error_class.new(
+        error_details,
+        http_status: status,
+        error_code: error_code,
+        error_details: error_details,
+        response_body: body
+      )
+    end
+
+    def error_class_for_status(status)
+      case status
+      when 401 then AuthenticationError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 400..499 then ValidationError
+      when 500..599 then ServerError
+      else Error
+      end
+    end
+
+    def log_request(method, url)
+      return unless @config.logger
+
+      @config.logger.info("[Multicard] #{method.to_s.upcase} #{url}")
+    end
+
+    def log_response(raw)
+      return unless @config.logger
+
+      @config.logger.info("[Multicard] #{raw.code}")
+    end
+  end
+end

data/lib/multicard/resources/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Multicard
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(path, params = {})
+        @client.authenticated_request(:get, path, params: params)
+      end
+
+      def post(path, body = {})
+        @client.authenticated_request(:post, path, body: body)
+      end
+
+      def delete(path, params = {})
+        @client.authenticated_request(:delete, path, params: params)
+      end
+
+      def default_store_id
+        @client.config.store_id
+      end
+
+      # Encode a path segment to prevent path traversal (../) or special characters.
+      def encode_path(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+    end
+  end
+end

data/lib/multicard/resources/cards.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Cards < Base
+      # --- Form-based card binding ---
+
+      # Create a card binding session (returns a link for the user).
+      #
+      # @param options [Hash] optional params
+      # @return [Response] with binding URL and session_id
+      def create_binding_link(**options)
+        post('/card/bind/session', options)
+      end
+
+      # Check binding session status.
+      #
+      # @param session_id [String] binding session ID
+      # @return [Response]
+      def binding_status(session_id)
+        get("/card/bind/status/#{encode_path(session_id)}")
+      end
+
+      # --- API-based card binding (PCI DSS required) ---
+
+      # Send SMS OTP for card binding.
+      #
+      # @param card_number [String] card number
+      # @param card_expiry [String] card expiry (MMYY)
+      # @return [Response]
+      def add(card_number:, card_expiry:)
+        post('/card/add', { number: card_number, expiry: card_expiry })
+      end
+
+      # Confirm card binding with SMS code.
+      #
+      # @param otp_code [String] SMS OTP code
+      # @param params [Hash] additional params
+      # @return [Response]
+      def confirm_binding(otp_code:, **params)
+        post('/card/bind/confirm', { code: otp_code, **params })
+      end
+
+      # --- Common operations ---
+
+      # Get card info by token.
+      #
+      # @param token [String] card token
+      # @return [Response]
+      def retrieve(token)
+        get("/card/#{encode_path(token)}")
+      end
+
+      # Check a card number (validate).
+      #
+      # @param card_number [String] card number
+      # @return [Response]
+      def check(card_number)
+        get("/card/check/#{encode_path(card_number)}")
+      end
+
+      # Verify card ownership via PINFL (personal ID).
+      #
+      # @param token [String] card token
+      # @param pinfl [String] personal identification number
+      # @return [Response]
+      def verify_pinfl(token:, pinfl:)
+        post('/card/verify/pinfl', { token: token, pinfl: pinfl })
+      end
+
+      # Revoke (unbind) a card token.
+      #
+      # @param token [String] card token
+      # @return [Response]
+      def revoke(token)
+        delete("/card/#{encode_path(token)}")
+      end
+    end
+  end
+end

data/lib/multicard/resources/holds.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Holds < Base
+      # Create a hold (pre-authorization).
+      #
+      # @param card_token [String] card token
+      # @param amount [Integer] amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @param store_id [Integer, nil] register ID
+      # @return [Response]
+      def create(card_token:, amount:, invoice_id:, store_id: nil, **options)
+        post('/hold', {
+          card: { token: card_token },
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          **options
+        }.compact)
+      end
+
+      # Confirm a hold (block funds on card).
+      #
+      # @param hold_id [String] hold ID
+      # @param otp_code [String, nil] SMS OTP code if required
+      # @return [Response]
+      def confirm(hold_id, otp_code: nil)
+        body = otp_code ? { code: otp_code } : {}
+        post("/hold/#{encode_path(hold_id)}/confirm", body)
+      end
+
+      # Capture (debit) held funds. Full or partial.
+      #
+      # @param hold_id [String] hold ID
+      # @param amount [Integer, nil] partial capture amount (nil = full capture)
+      # @return [Response]
+      def capture(hold_id, amount: nil)
+        body = amount ? { amount: amount } : {}
+        post("/hold/#{encode_path(hold_id)}/charge", body)
+      end
+
+      # Retrieve hold info.
+      #
+      # @param hold_id [String] hold ID
+      # @return [Response]
+      def retrieve(hold_id)
+        get("/hold/#{encode_path(hold_id)}")
+      end
+
+      # Cancel a hold (release blocked funds).
+      #
+      # @param hold_id [String] hold ID
+      # @return [Response]
+      def cancel(hold_id)
+        delete("/hold/#{encode_path(hold_id)}")
+      end
+    end
+  end
+end

data/lib/multicard/resources/invoices.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Invoices < Base
+      # Create an invoice (hosted checkout page).
+      #
+      # @param amount [Integer] amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @param callback_url [String] webhook URL
+      # @param store_id [Integer, nil] register ID (falls back to config.store_id)
+      # @param options [Hash] additional params (description, lifetime, return_url, etc.)
+      # @return [Response]
+      def create(amount:, invoice_id:, callback_url:, store_id: nil, **options)
+        post('/payment/invoice', {
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          callback_url: callback_url,
+          **options
+        }.compact)
+      end
+
+      # Retrieve invoice info.
+      #
+      # @param invoice_id [String] invoice ID
+      # @return [Response]
+      def retrieve(invoice_id)
+        get("/invoice/#{encode_path(invoice_id)}")
+      end
+
+      # Cancel an unpaid invoice.
+      #
+      # @param invoice_id [String] invoice ID
+      # @return [Response]
+      def cancel(invoice_id)
+        delete("/invoice/#{encode_path(invoice_id)}")
+      end
+
+      # Generate a Quick Pay link (Payme, Click, Uzum QR, etc.).
+      #
+      # @param invoice_id [String] invoice ID
+      # @param service [String] payment service name
+      # @return [Response]
+      def quick_pay(invoice_id:, service:)
+        post('/invoice/quick-pay', {
+               invoice_id: invoice_id,
+               service: service
+             })
+      end
+    end
+  end
+end

data/lib/multicard/resources/payments.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Payments < Base
+      # Pay by saved card token.
+      #
+      # @param card_token [String] card token from binding
+      # @param amount [Integer] amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @param store_id [Integer, nil] register ID
+      # @param callback_url [String, nil] webhook URL
+      # @param ofd [Array<Hash>, nil] fiscal receipt items
+      # @return [Response]
+      def create_by_token(card_token:, amount:, invoice_id:, store_id: nil,
+                          callback_url: nil, ofd: nil, **options)
+        post('/payment/token', {
+          card: { token: card_token },
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          callback_url: callback_url,
+          ofd: ofd,
+          **options
+        }.compact)
+      end
+
+      # Pay by card number (requires PCI DSS).
+      #
+      # @param card_number [String] card number
+      # @param card_expiry [String] card expiry (MMYY or MM/YY)
+      # @param amount [Integer] amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @return [Response]
+      def create_by_card(card_number:, card_expiry:, amount:, invoice_id:, store_id: nil,
+                         callback_url: nil, ofd: nil, **options)
+        post('/payment/card', {
+          card: { number: card_number, expiry: card_expiry },
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          callback_url: callback_url,
+          ofd: ofd,
+          **options
+        }.compact)
+      end
+
+      # Split payment across multiple recipients.
+      #
+      # @param card_token [String] card token
+      # @param amount [Integer] total amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @param split [Array<Hash>] split recipients [{type:, amount:, details:, recipient:}]
+      # @return [Response]
+      def create_split(card_token:, amount:, invoice_id:, split:, store_id: nil,
+                       callback_url: nil, ofd: nil, **options)
+        post('/payment/split', {
+          card: { token: card_token },
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          callback_url: callback_url,
+          split: split,
+          ofd: ofd,
+          **options
+        }.compact)
+      end
+
+      # Pay via wallet app (Payme, Click, Uzum, etc.).
+      #
+      # @param service [String] wallet service name
+      # @param amount [Integer] amount in tiyin
+      # @param invoice_id [String] your order ID
+      # @return [Response]
+      def create_wallet(service:, amount:, invoice_id:, store_id: nil,
+                        callback_url: nil, ofd: nil, **options)
+        post('/payment/app', {
+          service: service,
+          amount: amount,
+          store_id: store_id || default_store_id,
+          invoice_id: invoice_id,
+          callback_url: callback_url,
+          ofd: ofd,
+          **options
+        }.compact)
+      end
+
+      # Confirm a payment (submit OTP code if required).
+      #
+      # @param payment_id [String] payment ID
+      # @param otp_code [String, nil] SMS confirmation code
+      # @return [Response]
+      def confirm(payment_id, otp_code: nil)
+        body = otp_code ? { code: otp_code } : {}
+        post("/payment/#{encode_path(payment_id)}/confirm", body)
+      end
+
+      # Retrieve payment info.
+      #
+      # @param payment_id [String] payment ID (UUID)
+      # @return [Response]
+      def retrieve(payment_id)
+        get("/payment/#{encode_path(payment_id)}")
+      end
+
+      # Full refund.
+      #
+      # @param payment_id [String] payment ID (UUID)
+      # @return [Response]
+      def refund(payment_id)
+        delete("/payment/#{encode_path(payment_id)}")
+      end
+
+      # Partial refund.
+      #
+      # @param payment_id [String] payment ID (UUID)
+      # @param amount [Integer] refund amount in tiyin
+      # @return [Response]
+      def partial_refund(payment_id, amount:)
+        post("/payment/#{encode_path(payment_id)}/refund/partial", { amount: amount })
+      end
+
+      # Submit a fiscal receipt link.
+      #
+      # @param payment_id [String] payment ID (UUID)
+      # @param fiscal_url [String] URL of the fiscal receipt
+      # @return [Response]
+      def send_fiscal_link(payment_id, fiscal_url:)
+        post("/payment/#{encode_path(payment_id)}/fiscal", { fiscal_url: fiscal_url })
+      end
+    end
+  end
+end

data/lib/multicard/resources/payouts.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Payouts < Base
+      # Create a payout to a card.
+      #
+      # @param card_number [String] recipient card number
+      # @param amount [Integer] amount in tiyin
+      # @param options [Hash] additional params
+      # @return [Response]
+      def create(card_number:, amount:, **options)
+        post('/payout', {
+               card_number: card_number,
+               amount: amount,
+               **options
+             })
+      end
+
+      # Confirm a payout.
+      #
+      # @param payout_id [String] payout ID
+      # @return [Response]
+      def confirm(payout_id)
+        post("/payout/#{encode_path(payout_id)}/confirm")
+      end
+
+      # Retrieve payout info.
+      #
+      # @param payout_id [String] payout ID
+      # @return [Response]
+      def retrieve(payout_id)
+        get("/payout/#{encode_path(payout_id)}")
+      end
+    end
+  end
+end

data/lib/multicard/resources/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Multicard
+  module Resources
+    class Registry < Base
+      # Get payment registry (list of processed payments).
+      #
+      # @param filters [Hash] filter params (date_from, date_to, status, etc.)
+      # @return [Response]
+      def payments(**filters)
+        get('/payments/registry', filters)
+      end
+
+      # Get payout history.
+      #
+      # @param filters [Hash] filter params
+      # @return [Response]
+      def payouts(**filters)
+        get('/payout/history', filters)
+      end
+
+      # Get application info.
+      #
+      # @return [Response]
+      def application_info
+        get('/app/info')
+      end
+
+      # Get merchant banking details.
+      #
+      # @return [Response]
+      def merchant_details
+        get('/merchant/details')
+      end
+    end
+  end
+end

data/lib/multicard/response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Multicard
+  class Response
+    attr_reader :http_status, :body, :headers
+
+    def initialize(http_status:, body:, headers: {})
+      @http_status = http_status
+      @body = body
+      @headers = headers
+    end
+
+    def success?
+      body[:success] == true
+    end
+
+    def data
+      body[:data]
+    end
+
+    def error_code
+      body.dig(:error, :code)
+    end
+
+    def error_details
+      body.dig(:error, :details)
+    end
+
+    def [](key)
+      data&.[](key)
+    end
+  end
+end

data/lib/multicard/signature.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Multicard
+  class Signature
+    # Verify a webhook callback signature.
+    #
+    # @param params [Hash] webhook parameters (:store_id, :invoice_id, :amount, :sign)
+    # @param secret [String] application secret
+    # @return [Boolean]
+    def self.verify(params, secret:)
+      store_id = params[:store_id].to_s
+      invoice_id = params[:invoice_id].to_s
+      amount = normalize_amount(params[:amount].to_s)
+      sign = params[:sign].to_s
+
+      return false if sign.empty?
+
+      expected = Digest::MD5.hexdigest("#{store_id}#{invoice_id}#{amount}#{secret}")
+      secure_compare(expected.downcase, sign.downcase)
+    end
+
+    # Constant-time string comparison to prevent timing attacks.
+    #
+    # Regular == short-circuits on the first mismatched byte, so an attacker
+    # can measure response time and brute-force the signature byte by byte.
+    # XOR-ing every pair and OR-accumulating makes execution time depend only
+    # on string length, not content.
+    #
+    # We implement this inline instead of using Rack::Utils.secure_compare
+    # to keep the gem dependency-free (no Rack requirement).
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
+    end
+
+    # Normalize amount: remove trailing ".0" / ".00" / ".000" etc.
+    #
+    # Multicard callbacks may send amounts as "50000", "50000.0", or "50000.00".
+    # The signature is always computed against the integer form (no decimals).
+    #
+    # Only trailing zeros are stripped (not arbitrary decimals like "50000.10")
+    # because Multicard amounts are in tiyin (1/100 of UZS) — always integers.
+    # Non-zero decimal digits would indicate a bug in the callback, not valid data.
+    def self.normalize_amount(amount)
+      amount.sub(/\.0+\z/, '')
+    end
+
+    private_class_method :secure_compare, :normalize_amount
+  end
+end