bayarcash 1.0.0

data/lib/bayarcash/fpx_direct_debit.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # FPX Direct Debit constants: application types, payer id types, frequency modes,
+  # and mandate status codes, together with their human-readable labels.
+  class FpxDirectDebit
+    # Application type
+    ENROLMENT   = "01"
+    MAINTENANCE = "02"
+    TERMINATION = "03"
+
+    # Buyer / payer ID type
+    NRIC                  = 1
+    OLD_IC                = 2
+    PASSPORT              = 3
+    BUSINESS_REGISTRATION = 4
+    OTHERS                = 5
+
+    # Frequency mode
+    MODE_DAILY   = "DL"
+    MODE_WEEKLY  = "WK"
+    MODE_MONTHLY = "MT"
+    MODE_YEARLY  = "YR"
+
+    # Status code
+    STATUS_NEW                     = 0
+    STATUS_WAITING_APPROVAL        = 1
+    STATUS_FAILED_BANK_VERIFICATION = 2
+    STATUS_ACTIVE                  = 3
+    STATUS_TERMINATED              = 4
+    STATUS_APPROVED                = 5
+    STATUS_REJECTED                = 6
+    STATUS_CANCELLED               = 7
+    STATUS_ERROR                   = 8
+
+    STATUS_LABELS = {
+      STATUS_NEW                      => "New",
+      STATUS_WAITING_APPROVAL         => "Waiting Approval",
+      STATUS_FAILED_BANK_VERIFICATION => "Bank Verification Failed",
+      STATUS_APPROVED                 => "Approved",
+      STATUS_REJECTED                 => "Rejected",
+      STATUS_CANCELLED                => "Cancelled",
+      STATUS_ERROR                    => "Error",
+      STATUS_ACTIVE                   => "Active",
+      STATUS_TERMINATED               => "Terminated"
+    }.freeze
+
+    # @param status_code [Integer]
+    # @return [String] label for the status, or "UNKNOWN STATUS"
+    def self.get_status_text(status_code)
+      STATUS_LABELS.fetch(status_code.to_i, "UNKNOWN STATUS")
+    end
+
+    # @param application_type [String] one of {ENROLMENT}, {MAINTENANCE}, {TERMINATION}
+    # @return [String, nil]
+    def self.get_application_type_text(application_type)
+      case application_type
+      when ENROLMENT   then "Enrollment"
+      when MAINTENANCE then "Maintenance"
+      when TERMINATION then "Termination"
+      end
+    end
+
+    # @param frequency_mode_code [String] one of {MODE_DAILY}, {MODE_WEEKLY}, {MODE_MONTHLY}, {MODE_YEARLY}
+    # @return [String, nil]
+    def self.get_frequency_mode_text(frequency_mode_code)
+      case frequency_mode_code
+      when MODE_DAILY   then "Daily"
+      when MODE_WEEKLY  then "Weekly"
+      when MODE_MONTHLY then "Monthly"
+      when MODE_YEARLY  then "Yearly"
+      end
+    end
+  end
+end

data/lib/bayarcash/fpx_direct_debit_payment_intent.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # FPX Direct Debit mandate operations (enrolment, maintenance, termination) and
+  # mandate/transaction retrieval.
+  module FpxDirectDebitPaymentIntent
+    # Enrol a new direct-debit mandate.
+    #
+    # @param data [Hash]
+    # @return [Bayarcash::Resources::FpxDirectDebitApplicationResource]
+    def create_fpx_direct_debit_enrollment(data)
+      Bayarcash::Resources::FpxDirectDebitApplicationResource.new(
+        post("mandates", data),
+        self
+      )
+    end
+
+    # Maintain (update) an existing mandate.
+    #
+    # @param mandate_id [String]
+    # @param data [Hash]
+    # @return [Bayarcash::Resources::FpxDirectDebitApplicationResource]
+    def create_fpx_direct_debit_maintenance(mandate_id, data)
+      Bayarcash::Resources::FpxDirectDebitApplicationResource.new(
+        put("mandates/#{mandate_id}", data),
+        self
+      )
+    end
+
+    # Terminate an existing mandate.
+    #
+    # @param mandate_id [String]
+    # @param data [Hash]
+    # @return [Bayarcash::Resources::FpxDirectDebitApplicationResource]
+    def create_fpx_direct_debit_termination(mandate_id, data)
+      Bayarcash::Resources::FpxDirectDebitApplicationResource.new(
+        delete("mandates/#{mandate_id}", data),
+        self
+      )
+    end
+
+    # Retrieve a direct-debit mandate transaction.
+    #
+    # @param id [String]
+    # @return [Bayarcash::Resources::TransactionResource]
+    def get_fpx_direct_debit_transaction(id)
+      Bayarcash::Resources::TransactionResource.new(
+        get("mandates/transactions/#{id}"),
+        self
+      )
+    end
+
+    # Deprecated misspelled alias, kept for backward compatibility.
+    #
+    # @deprecated Use {#get_fpx_direct_debit_transaction} instead.
+    def getfpx_direct_debitransaction(id)
+      get_fpx_direct_debit_transaction(id)
+    end
+
+    # Retrieve a direct-debit mandate.
+    #
+    # @param id [String]
+    # @return [Bayarcash::Resources::FpxDirectDebitResource]
+    def get_fpx_direct_debit(id)
+      Bayarcash::Resources::FpxDirectDebitResource.new(
+        get("mandates/#{id}")
+      )
+    end
+  end
+end

data/lib/bayarcash/makes_http_requests.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # HTTP transport for the Bayarcash API.
+  #
+  # Requests default to form-urlencoded bodies (matching the PHP SDK's Guzzle
+  # `form_params` behaviour). To send a JSON body, pass a payload shaped like
+  # `{ json: {...} }`. Non-2xx responses are mapped to typed errors.
+  module MakesHttpRequests
+    # @return [Faraday::Connection]
+    attr_reader :connection
+
+    # @param uri [String]
+    # @return [Object] decoded response
+    def get(uri)
+      request(:get, uri)
+    end
+
+    # @param uri [String]
+    # @param payload [Hash]
+    # @return [Object] decoded response
+    def post(uri, payload = {})
+      request(:post, uri, payload)
+    end
+
+    # @param uri [String]
+    # @param payload [Hash]
+    # @return [Object] decoded response
+    def put(uri, payload = {})
+      request(:put, uri, payload)
+    end
+
+    # @param uri [String]
+    # @param payload [Hash]
+    # @return [Object] decoded response
+    def delete(uri, payload = {})
+      request(:delete, uri, payload)
+    end
+
+    # Retry a block until it returns a truthy value or the timeout elapses.
+    #
+    # @param timeout [Integer] seconds
+    # @param sleep_seconds [Integer]
+    # @yield the operation to retry
+    # @return [Object] the truthy result
+    # @raise [Bayarcash::TimeoutError] when the timeout elapses
+    def retry_until(timeout, sleep_seconds = 5)
+      start = Time.now.to_i
+
+      loop do
+        output = yield
+        return output if output
+
+        if Time.now.to_i - start < timeout
+          sleep(sleep_seconds)
+        else
+          output = [] if output.nil? || output == false
+          output = [output] unless output.is_a?(Array)
+          raise Bayarcash::TimeoutError.new(output)
+        end
+      end
+    end
+
+    protected
+
+    # Build (or rebuild) the Faraday connection for the current base URI/token/timeout.
+    #
+    # @return [Faraday::Connection]
+    def build_connection
+      @connection = Faraday.new(url: base_uri) do |faraday|
+        faraday.headers["Authorization"] = "Bearer #{@token}"
+        faraday.headers["Accept"] = "application/json"
+        faraday.options.timeout = @timeout if @timeout
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    # Perform a request and decode the response, or map the error.
+    def request(verb, uri, payload = {})
+      payload ||= {}
+
+      response = connection.run_request(verb.to_s.downcase.to_sym, uri, nil, nil) do |req|
+        if json_payload?(payload)
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(payload[:json] || payload["json"])
+        elsif !payload.empty?
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = Bayarcash::Util.build_query(payload)
+        end
+      end
+
+      status = response.status
+      return handle_request_error(response) if status < 200 || status > 299
+
+      parse_body(response.body.to_s)
+    end
+
+    # Map a non-2xx response to a typed error.
+    def handle_request_error(response)
+      body = response.body.to_s
+
+      case response.status
+      when 422
+        parsed = Bayarcash::Util.safe_json(body)
+        raise Bayarcash::ValidationError.new(parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : {})
+      when 404
+        raise Bayarcash::NotFoundError.new
+      when 400
+        raise Bayarcash::FailedActionError, failed_action_message(body)
+      when 429
+        reset = response.headers["x-ratelimit-reset"]
+        raise Bayarcash::RateLimitExceededError.new(reset ? reset.to_i : nil)
+      else
+        raise Bayarcash::Error, body
+      end
+    end
+
+    private
+
+    def json_payload?(payload)
+      payload.is_a?(Hash) && (payload.key?(:json) || payload.key?("json"))
+    end
+
+    def parse_body(body)
+      return body if body.nil? || body.empty?
+
+      parsed = Bayarcash::Util.safe_json(body)
+      return body if parsed.nil?
+      return body if Bayarcash::Util.php_falsy?(parsed)
+
+      parsed
+    end
+
+    def failed_action_message(body)
+      decoded = Bayarcash::Util.safe_json(body)
+      return body unless decoded.is_a?(Hash)
+
+      message = decoded["message"] || decoded["error"] || body
+      message = JSON.generate(message) if message.is_a?(Hash) || message.is_a?(Array)
+      message
+    end
+  end
+end

data/lib/bayarcash/manual_bank_transfer.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # Manual (offline) bank transfer operations.
+  #
+  # These calls hit a different base URL than the versioned API (no /v2 or /v3
+  # segment) and support a multipart `proof_of_payment` file upload.
+  module ManualBankTransfer
+    REQUIRED_MANUAL_TRANSFER_FIELDS = %w[
+      portal_key buyer_name buyer_email order_amount order_no payment_gateway
+      merchant_bank_name merchant_bank_account merchant_bank_account_holder
+      bank_transfer_type bank_transfer_notes
+    ].freeze
+
+    FILE_CONTENT_TYPES = {
+      "jpg"  => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "png"  => "image/png",
+      "gif"  => "image/gif",
+      "pdf"  => "application/pdf"
+    }.freeze
+
+    # Create a manual bank transfer payment.
+    #
+    # @param data [Hash] payment and customer details (see README for the field list)
+    # @param allow_redirect [Boolean] whether to auto-follow HTTP redirects
+    # @return [Hash, String] response hash or raw string depending on the API response
+    # @raise [ArgumentError] when required fields are missing or invalid
+    # @raise [Bayarcash::Error] when the API request fails
+    def create_manual_bank_transfer(data, allow_redirect = false)
+      data = stringify_keys(data)
+
+      validate_manual_transfer_data(data)
+
+      data["bank_transfer_date"] ||= Date.today.strftime("%Y-%m-%d")
+
+      post_fields = prepare_manual_transfer_post_fields(data)
+
+      response = execute_manual_transfer_request(post_fields, allow_redirect)
+
+      process_manual_transfer_response(response[:body], response[:http_code], allow_redirect)
+    end
+
+    # Update the status of an existing manual bank transfer.
+    #
+    # @param ref_no [String] transaction reference number
+    # @param status [String] new status code
+    # @param amount [String] transaction amount
+    # @return [Object] decoded API response
+    # @raise [Bayarcash::Error] when the update fails
+    def update_manual_bank_transfer_status(ref_no, status, amount)
+      data = { "ref_no" => ref_no, "status" => status, "amount" => amount }
+
+      conn = Faraday.new do |faraday|
+        faraday.request :url_encoded
+        faraday.adapter Faraday.default_adapter
+      end
+
+      url = "#{manual_transfer_base_url}/manual-bank-transfer/update-status"
+
+      begin
+        response = conn.post(url) do |req|
+          req.headers["Accept"] = "application/json"
+          req.headers["Authorization"] = "Bearer #{@token}"
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = data
+        end
+      rescue Faraday::Error => e
+        raise Bayarcash::Error, "Connection failed: #{e.message}"
+      end
+
+      handle_api_response(response.body.to_s, response.status)
+    end
+
+    # Extract structured data from an HTML form response.
+    #
+    # @param html_response [String]
+    # @return [Hash{String => String}]
+    def parse_manual_bank_transfer_response(html_response)
+      data = {}
+
+      if (form_id = html_response[/id="([^"]+)"/, 1])
+        data["form_id"] = form_id
+      end
+
+      if (return_url = html_response[/action="([^"]+)"/, 1])
+        data["return_url"] = return_url
+      end
+
+      html_response.scan(/<input name="([^"]+)" type="hidden" value="([^"]*)">/).each do |name, value|
+        data[name] = value
+      end
+
+      data
+    end
+
+    protected
+
+    # The manual-transfer base URL (note: no /v2 or /v3 segment).
+    #
+    # @return [String]
+    def manual_transfer_base_url
+      @sandbox ? "https://console.bayarcash-sandbox.com/api" : "https://console.bayar.cash/api"
+    end
+
+    private
+
+    def validate_manual_transfer_data(data)
+      REQUIRED_MANUAL_TRANSFER_FIELDS.each do |field|
+        if data[field].nil?
+          raise ArgumentError, "Required field '#{field}' is missing"
+        end
+      end
+
+      if data["payment_gateway"].nil? || data["payment_gateway"].to_s != "2"
+        raise ArgumentError, "Invalid payment gateway. Value must be 2 for manual bank transfers."
+      end
+
+      if data["proof_of_payment"] && !File.exist?(data["proof_of_payment"])
+        raise ArgumentError, "Proof of payment file does not exist"
+      end
+    end
+
+    def prepare_manual_transfer_post_fields(data)
+      post_fields = {}
+
+      data.each do |key, value|
+        post_fields[key] = value unless key == "proof_of_payment"
+      end
+
+      if data["proof_of_payment"] && File.exist?(data["proof_of_payment"])
+        path = data["proof_of_payment"]
+        post_fields["proof_of_payment"] = Faraday::Multipart::FilePart.new(
+          path,
+          file_content_type(path),
+          File.basename(path)
+        )
+      end
+
+      post_fields
+    end
+
+    def execute_manual_transfer_request(post_fields, allow_redirect)
+      conn = Faraday.new do |faraday|
+        faraday.request :multipart
+        faraday.request :url_encoded
+        faraday.adapter Faraday.default_adapter
+      end
+
+      url = "#{manual_transfer_base_url}/manual-bank-transfer"
+
+      begin
+        response = conn.post(url) do |req|
+          req.headers["Accept"] = "application/json"
+          req.headers["Authorization"] = "Bearer #{@token}"
+          req.body = post_fields
+        end
+
+        redirects = 0
+        while allow_redirect && response.status >= 300 && response.status < 400 &&
+              response.headers["location"] && redirects < 10
+          response = Faraday.get(response.headers["location"])
+          redirects += 1
+        end
+      rescue Faraday::Error => e
+        raise Bayarcash::Error, "cURL Error: #{e.message}"
+      end
+
+      { body: response.body.to_s, http_code: response.status }
+    end
+
+    def process_manual_transfer_response(response, http_code, allow_redirect)
+      if http_code >= 200 && http_code < 300
+        if response.include?("<form")
+          parsed = parse_manual_bank_transfer_response(response)
+
+          {
+            success: true,
+            html_form: response,
+            form_data: parsed,
+            return_url: parsed["return_url"]
+          }
+        else
+          decoded = Bayarcash::Util.safe_json(response)
+          decoded && !Bayarcash::Util.php_falsy?(decoded) ? decoded : response
+        end
+      elsif http_code >= 300 && http_code < 400 && !allow_redirect
+        { redirect_url: response }
+      else
+        handle_api_error(response, http_code)
+      end
+    end
+
+    def handle_api_error(response, http_code)
+      decoded = Bayarcash::Util.safe_json(response)
+
+      if decoded.is_a?(Hash) && decoded.key?("message")
+        raise Bayarcash::Error, decoded["message"]
+      else
+        raise Bayarcash::Error, "API Error (HTTP #{http_code}): #{response[0, 200]}"
+      end
+    end
+
+    def handle_api_response(response, http_code)
+      if http_code >= 200 && http_code < 300
+        decoded = Bayarcash::Util.safe_json(response)
+        decoded && !Bayarcash::Util.php_falsy?(decoded) ? decoded : response
+      else
+        handle_api_error(response, http_code)
+      end
+    end
+
+    def file_content_type(file_path)
+      extension = File.extname(file_path).delete(".").downcase
+      FILE_CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+
+    def stringify_keys(data)
+      (data || {}).each_with_object({}) do |(key, value), memo|
+        memo[key.to_s] = value
+      end
+    end
+  end
+end

data/lib/bayarcash/resources/fpx_bank_resource.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by {Bayarcash::Client#fpx_banks_list}.
+    class FpxBankResource < Resource
+      attributes :bank_name, :bank_display_name, :bank_code, :bank_code_hashed,
+                 :bank_availability
+    end
+  end
+end

data/lib/bayarcash/resources/fpx_direct_debit_application_resource.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by direct-debit enrolment, maintenance and termination calls.
+    class FpxDirectDebitApplicationResource < Resource
+      attributes :payer_name, :payer_id_type, :payer_id, :payer_email,
+                 :payer_telephone_number, :order_number, :amount, :application_type,
+                 :application_reason, :frequency_mode, :effective_date, :expiry_date, :url
+    end
+  end
+end

data/lib/bayarcash/resources/fpx_direct_debit_resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by {Bayarcash::Client#get_fpx_direct_debit} (a mandate).
+    class FpxDirectDebitResource < Resource
+      attributes :id, :updated_at, :mandate_reference_number, :order_number,
+                 :application_reason, :frequency_mode, :frequency_mode_label,
+                 :effective_date, :expiry_date, :currency, :amount, :payer_name,
+                 :payer_id, :payer_id_type, :payer_bank_account_number, :payer_email,
+                 :payer_telephone_number, :status, :status_description, :return_url,
+                 :metadata, :portal, :merchant
+    end
+  end
+end

data/lib/bayarcash/resources/payment_intent_resource.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by {Bayarcash::Client#create_payment_intent} and
+    # {Bayarcash::Client#get_payment_intent}.
+    class PaymentIntentResource < Resource
+      attributes :payer_name, :payer_email, :payer_telephone_number, :order_number,
+                 :amount, :url, :type, :id, :status, :last_attempt, :paid_at,
+                 :currency, :attempts
+    end
+  end
+end

data/lib/bayarcash/resources/portal_resource.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by {Bayarcash::Client#get_portals}.
+    class PortalResource < Resource
+      attributes :id, :created_at, :portal_key, :portal_name, :website_url,
+                 :transaction_notification_email, :secondary_transaction_notification_email,
+                 :custom_payment_button_text, :enabled_sms_on_successful_transaction,
+                 :split_payment_enabled, :split_payment_merchants, :payment_channels,
+                 :merchant, :url, :merchant_id
+    end
+  end
+end

data/lib/bayarcash/resources/resource.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Base data-transfer object for API responses.
+    #
+    # Attributes are populated from the (snake_case) keys of the API payload and
+    # exposed as reader methods. Declared attributes always respond (returning nil
+    # when the API omits them); any unknown field the API returns is captured too,
+    # so the DTOs are tolerant of new or missing fields.
+    class Resource
+      # Declare known attributes for a resource subclass. Each becomes a reader that
+      # returns nil when absent.
+      #
+      # @param names [Array<Symbol, String>]
+      def self.attributes(*names)
+        @declared_attributes ||= []
+        names.each do |name|
+          key = name.to_s
+          @declared_attributes << key unless @declared_attributes.include?(key)
+          define_method(key) { @attributes[key] }
+        end
+      end
+
+      # @return [Array<String>] declared attribute names, including inherited ones
+      def self.declared_attributes
+        inherited = superclass.respond_to?(:declared_attributes) ? superclass.declared_attributes : []
+        inherited + (@declared_attributes || [])
+      end
+
+      # @param attributes [Hash] the API payload
+      # @param bayarcash [Bayarcash::Client, nil] owning client (never serialized)
+      def initialize(attributes = {}, bayarcash = nil)
+        @bayarcash = bayarcash
+        @attributes = {}
+        fill(attributes)
+      end
+
+      # Read a raw attribute by key (string or symbol).
+      #
+      # @param key [String, Symbol]
+      # @return [Object, nil]
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      # @return [Hash{String => Object}] the attributes, with nested resources converted
+      def to_h
+        @attributes.each_with_object({}) do |(key, value), memo|
+          memo[key] = deep_to_h(value)
+        end
+      end
+      alias to_array to_h
+      alias to_hash to_h
+
+      def respond_to_missing?(name, include_private = false)
+        key = name.to_s
+        @attributes.key?(key) || self.class.declared_attributes.include?(key) || super
+      end
+
+      def method_missing(name, *args)
+        key = name.to_s
+        if @attributes.key?(key) || self.class.declared_attributes.include?(key)
+          @attributes[key]
+        else
+          super
+        end
+      end
+
+      private
+
+      def fill(attributes)
+        (attributes || {}).each do |key, value|
+          @attributes[key.to_s] = value
+        end
+      end
+
+      def deep_to_h(value)
+        case value
+        when Resource
+          value.to_h
+        when Array
+          value.map { |item| item.is_a?(Resource) ? item.to_h : item }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/bayarcash/resources/transaction_resource.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module Resources
+    # Returned by transaction lookups and queries.
+    class TransactionResource < Resource
+      attributes :id, :updated_at, :created_at, :datetime, :payer_name, :payer_email,
+                 :payer_telephone_number, :order_number, :currency, :amount,
+                 :exchange_reference_number, :exchange_transaction_id, :payer_bank_name,
+                 :status, :status_description, :return_url, :metadata, :payout,
+                 :payment_gateway, :portal, :merchant, :mandate
+    end
+  end
+end