bayarcash 1.0.0

data/lib/bayarcash/callback_verifications.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # Callback verification, one verifier per callback type.
+  #
+  # Each verifier reconstructs the exact payload the gateway signs, computes the
+  # HMAC-SHA256 checksum and compares it against the supplied `checksum` using a
+  # constant-time comparison (see {Bayarcash::SecurityUtils.secure_compare}).
+  module CallbackVerifications
+    # Verify a direct-debit bank-approval callback.
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_direct_debit_bank_approval_callback_data(callback_data, secret_key)
+      payload = {
+        "record_type"              => cb(callback_data, "record_type"),
+        "approval_date"            => cb(callback_data, "approval_date"),
+        "approval_status"          => cb(callback_data, "approval_status"),
+        "mandate_id"               => cb(callback_data, "mandate_id"),
+        "mandate_reference_number" => cb(callback_data, "mandate_reference_number"),
+        "order_number"             => cb(callback_data, "order_number"),
+        "payer_bank_code_hashed"   => cb(callback_data, "payer_bank_code_hashed"),
+        "payer_bank_code"          => cb(callback_data, "payer_bank_code"),
+        "payer_bank_account_no"    => cb(callback_data, "payer_bank_account_no"),
+        "application_type"         => cb(callback_data, "application_type")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    # Verify a direct-debit authorization callback.
+    #
+    # NOTE: this payload MUST include `application_type` (the gateway signs it);
+    # omitting it causes every genuine authorization callback to fail verification.
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_direct_debit_authorization_callback_data(callback_data, secret_key)
+      payload = {
+        "record_type"               => cb(callback_data, "record_type"),
+        "transaction_id"            => cb(callback_data, "transaction_id"),
+        "mandate_id"                => cb(callback_data, "mandate_id"),
+        "application_type"          => cb(callback_data, "application_type"),
+        "exchange_reference_number" => cb(callback_data, "exchange_reference_number"),
+        "exchange_transaction_id"   => cb(callback_data, "exchange_transaction_id"),
+        "order_number"              => cb(callback_data, "order_number"),
+        "currency"                  => cb(callback_data, "currency"),
+        "amount"                    => cb(callback_data, "amount"),
+        "payer_name"                => cb(callback_data, "payer_name"),
+        "payer_email"               => cb(callback_data, "payer_email"),
+        "payer_bank_name"           => cb(callback_data, "payer_bank_name"),
+        "status"                    => cb(callback_data, "status"),
+        "status_description"        => cb(callback_data, "status_description"),
+        "datetime"                  => cb(callback_data, "datetime")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    # Verify a direct-debit transaction callback.
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_direct_debit_transaction_callback_data(callback_data, secret_key)
+      payload = {
+        "record_type"              => cb(callback_data, "record_type"),
+        "batch_number"             => cb(callback_data, "batch_number"),
+        "mandate_id"               => cb(callback_data, "mandate_id"),
+        "mandate_reference_number" => cb(callback_data, "mandate_reference_number"),
+        "transaction_id"           => cb(callback_data, "transaction_id"),
+        "datetime"                 => cb(callback_data, "datetime"),
+        "reference_number"         => cb(callback_data, "reference_number"),
+        "amount"                   => cb(callback_data, "amount"),
+        "status"                   => cb(callback_data, "status"),
+        "status_description"       => cb(callback_data, "status_description"),
+        "cycle"                    => cb(callback_data, "cycle")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    # Verify a transaction callback (sent to your callback_url).
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_transaction_callback_data(callback_data, secret_key)
+      payload = {
+        "record_type"               => cb(callback_data, "record_type"),
+        "transaction_id"            => cb(callback_data, "transaction_id"),
+        "exchange_reference_number" => cb(callback_data, "exchange_reference_number"),
+        "exchange_transaction_id"   => cb(callback_data, "exchange_transaction_id"),
+        "order_number"              => cb(callback_data, "order_number"),
+        "currency"                  => cb(callback_data, "currency"),
+        "amount"                    => cb(callback_data, "amount"),
+        "payer_name"                => cb(callback_data, "payer_name"),
+        "payer_email"               => cb(callback_data, "payer_email"),
+        "payer_bank_name"           => cb(callback_data, "payer_bank_name"),
+        "status"                    => cb(callback_data, "status"),
+        "status_description"        => cb(callback_data, "status_description"),
+        "datetime"                  => cb(callback_data, "datetime")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    # Verify a return-url callback (payer redirect).
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_return_url_callback_data(callback_data, secret_key)
+      payload = {
+        "transaction_id"            => cb(callback_data, "transaction_id"),
+        "exchange_reference_number" => cb(callback_data, "exchange_reference_number"),
+        "exchange_transaction_id"   => cb(callback_data, "exchange_transaction_id"),
+        "order_number"              => cb(callback_data, "order_number"),
+        "currency"                  => cb(callback_data, "currency"),
+        "amount"                    => cb(callback_data, "amount"),
+        "payer_bank_name"           => cb(callback_data, "payer_bank_name"),
+        "status"                    => cb(callback_data, "status"),
+        "status_description"        => cb(callback_data, "status_description")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    # Verify a pre-transaction callback (sent before the transaction record).
+    #
+    # @param callback_data [Hash]
+    # @param secret_key [String]
+    # @return [Boolean]
+    def verify_pre_transaction_callback_data(callback_data, secret_key)
+      payload = {
+        "record_type"               => cb(callback_data, "record_type"),
+        "exchange_reference_number" => cb(callback_data, "exchange_reference_number"),
+        "order_number"              => cb(callback_data, "order_number")
+      }
+
+      verify_callback(callback_data, payload, secret_key)
+    end
+
+    private
+
+    # Reconstruct the checksum from the payload and compare it, constant-time,
+    # against the checksum supplied in the callback data.
+    def verify_callback(callback_data, payload, secret_key)
+      provided_checksum = cb(callback_data, "checksum") || ""
+
+      payload_string = payload
+                       .sort_by { |key, _| key.to_s }
+                       .map { |_, value| Bayarcash::Util.php_string(value) }
+                       .join("|")
+
+      computed = OpenSSL::HMAC.hexdigest(
+        "SHA256",
+        Bayarcash::Util.php_string(secret_key),
+        payload_string
+      )
+
+      Bayarcash::SecurityUtils.secure_compare(computed, provided_checksum.to_s)
+    end
+
+    # Read a callback field that may use string or symbol keys; nil when absent.
+    def cb(callback_data, key)
+      return callback_data[key] if callback_data.key?(key)
+
+      symbol = key.to_sym
+      return callback_data[symbol] if callback_data.key?(symbol)
+
+      nil
+    end
+  end
+end

data/lib/bayarcash/checksum_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # Checksum generation (HMAC-SHA256), byte-compatible with the gateway.
+  #
+  # The recipe is always the same: sort the payload hash by KEY ascending, join the
+  # VALUES with "|", then HMAC-SHA256 with the merchant secret key and return the
+  # lowercase hex digest.
+  module ChecksumGenerator
+    # Generic checksum primitive: ksort by key, implode values with "|", HMAC-SHA256.
+    #
+    # @param secret_key [String]
+    # @param payload [Hash]
+    # @return [String] lowercase hex HMAC-SHA256 digest
+    def create_checksum_value(secret_key, payload)
+      hmac_from_payload(secret_key, payload)
+    end
+
+    # Checksum for a payment intent request.
+    #
+    # Signs `payment_channel` (comma-joined when an array/multiple, empty when none),
+    # `order_number`, `amount`, `payer_name` and `payer_email`.
+    #
+    # @param secret_key [String]
+    # @param data [Hash]
+    # @return [String]
+    def create_payment_intent_checksum_value(secret_key, data)
+      payment_channel = fetch_field(data, "payment_channel", [])
+      payment_channel = [payment_channel] unless payment_channel.is_a?(Array)
+      payment_channel = payment_channel.join(",")
+
+      payload = {
+        "payment_channel" => payment_channel,
+        "order_number"    => fetch_field(data, "order_number"),
+        "amount"          => fetch_field(data, "amount"),
+        "payer_name"      => fetch_field(data, "payer_name"),
+        "payer_email"     => fetch_field(data, "payer_email")
+      }
+
+      hmac_from_payload(secret_key, payload)
+    end
+
+    # Old typo version, kept for backward compatibility.
+    #
+    # @see #create_payment_intent_checksum_value
+    def create_payment_inten_checksum_value(secret_key, data)
+      create_payment_intent_checksum_value(secret_key, data)
+    end
+
+    # Checksum for an FPX Direct Debit enrolment request.
+    #
+    # @param secret_key [String]
+    # @param data [Hash]
+    # @return [String]
+    def create_fpx_direct_debit_enrolment_checksum_value(secret_key, data)
+      payload = {
+        "order_number"           => fetch_field(data, "order_number"),
+        "amount"                 => fetch_field(data, "amount"),
+        "payer_name"             => fetch_field(data, "payer_name"),
+        "payer_email"            => fetch_field(data, "payer_email"),
+        "payer_telephone_number" => fetch_field(data, "payer_telephone_number"),
+        "payer_id_type"          => fetch_field(data, "payer_id_type"),
+        "payer_id"               => fetch_field(data, "payer_id"),
+        "application_reason"     => fetch_field(data, "application_reason"),
+        "frequency_mode"         => fetch_field(data, "frequency_mode")
+      }
+
+      hmac_from_payload(secret_key, payload)
+    end
+
+    # Checksum for an FPX Direct Debit maintenance request.
+    #
+    # @param secret_key [String]
+    # @param data [Hash]
+    # @return [String]
+    def create_fpx_direct_debit_maintenance_checksum_value(secret_key, data)
+      payload = {
+        "amount"                 => fetch_field(data, "amount"),
+        "payer_email"            => fetch_field(data, "payer_email"),
+        "payer_telephone_number" => fetch_field(data, "payer_telephone_number"),
+        "application_reason"     => fetch_field(data, "application_reason"),
+        "frequency_mode"         => fetch_field(data, "frequency_mode")
+      }
+
+      hmac_from_payload(secret_key, payload)
+    end
+
+    private
+
+    # Sort the payload by key, join stringified values with "|", HMAC-SHA256.
+    def hmac_from_payload(secret_key, payload)
+      payload_string = payload
+                       .sort_by { |key, _| key.to_s }
+                       .map { |_, value| Bayarcash::Util.php_string(value) }
+                       .join("|")
+
+      OpenSSL::HMAC.hexdigest("SHA256", Bayarcash::Util.php_string(secret_key), payload_string)
+    end
+
+    # Read a field from a hash that may use string or symbol keys.
+    def fetch_field(data, key, default = nil)
+      return data[key] if data.key?(key)
+
+      symbol = key.to_sym
+      return data[symbol] if data.key?(symbol)
+
+      default
+    end
+  end
+end

data/lib/bayarcash/client.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # The Bayarcash API client.
+  #
+  # Mirrors the public surface of the official PHP SDK while remaining idiomatic
+  # Ruby and framework-agnostic.
+  #
+  # @example
+  #   client = Bayarcash::Client.new("YOUR_API_TOKEN")
+  #   client.use_sandbox.set_api_version("v3")
+  #   intent = client.create_payment_intent(data)
+  #   redirect_to intent.url
+  class Client
+    include MakesHttpRequests
+    include ChecksumGenerator
+    include CallbackVerifications
+    include FpxDirectDebitPaymentIntent
+    include ManualBankTransfer
+
+    # Payment channels
+    FPX               = 1
+    MANUAL_TRANSFER   = 2
+    FPX_DIRECT_DEBIT  = 3
+    FPX_LINE_OF_CREDIT = 4
+    DUITNOW_DOBW      = 5
+    DUITNOW_QR        = 6
+    SPAYLATER         = 7
+    BOOST_PAYFLEX     = 8
+    QRISOB            = 9
+    QRISWALLET        = 10
+    NETS              = 11
+    CREDIT_CARD       = 12
+    ALIPAY            = 13
+    WECHATPAY         = 14
+    PROMPTPAY         = 15
+    TOUCH_N_GO        = 16
+    BOOST_WALLET      = 17
+    GRABPAY           = 18
+    GRABPL            = 19
+    SHOPEE_PAY        = 21
+
+    # Allowed filter keys for {#get_all_transactions}.
+    ALLOWED_TRANSACTION_FILTERS = %w[
+      order_number status payment_channel exchange_reference_number payer_email
+    ].freeze
+
+    # @return [String] the API token
+    attr_reader :token
+    # @return [Integer] request timeout in seconds
+    attr_reader :timeout
+    # @return [Boolean] whether the sandbox environment is in use
+    attr_reader :sandbox
+    # @return [String] the API version in use ("v2" or "v3")
+    attr_reader :api_version
+
+    # @param token [String] the Bayarcash API token
+    # @param sandbox [Boolean] use the sandbox environment
+    # @param api_version [String] "v2" (default) or "v3"
+    # @param timeout [Integer] request timeout in seconds
+    def initialize(token, sandbox: false, api_version: "v2", timeout: 30)
+      @token = token
+      @sandbox = sandbox
+      @api_version = api_version
+      @timeout = timeout
+      build_connection
+    end
+
+    # Set the API token and rebuild the HTTP client.
+    #
+    # @param token [String]
+    # @param connection [Faraday::Connection, nil] inject a custom connection (mainly for tests)
+    # @return [self]
+    def set_token(token, connection = nil)
+      @token = token
+      connection ? (@connection = connection) : build_connection
+      self
+    end
+
+    # Switch to the sandbox environment and rebuild the HTTP client.
+    #
+    # @param connection [Faraday::Connection, nil]
+    # @return [self]
+    def use_sandbox(connection = nil)
+      @sandbox = true
+      connection ? (@connection = connection) : build_connection
+      self
+    end
+
+    # @return [Boolean]
+    def sandbox?
+      @sandbox
+    end
+
+    # Set the request timeout and rebuild the HTTP client.
+    #
+    # @param timeout [Integer] seconds
+    # @return [self]
+    def set_timeout(timeout)
+      @timeout = timeout
+      build_connection
+      self
+    end
+
+    # @return [Integer]
+    def get_timeout
+      @timeout
+    end
+
+    # Set the API version ("v2" or "v3") and rebuild the HTTP client.
+    #
+    # @param version [String]
+    # @return [self]
+    def set_api_version(version)
+      @api_version = version
+      build_connection
+      self
+    end
+
+    # @return [String]
+    def get_api_version
+      @api_version
+    end
+
+    # Get the list of FPX banks.
+    #
+    # @return [Array<Bayarcash::Resources::FpxBankResource>]
+    def fpx_banks_list
+      transform_collection(get("banks"), Resources::FpxBankResource)
+    end
+
+    # Get the list of portals.
+    #
+    # @return [Array<Bayarcash::Resources::PortalResource>]
+    def get_portals
+      response = get("portals")
+      collection = response.is_a?(Hash) ? (response["data"] || response) : response
+      transform_collection(collection, Resources::PortalResource)
+    end
+
+    # Get the payment channels available for a portal by portal key.
+    #
+    # @param portal_key [String]
+    # @return [Array]
+    def get_channels(portal_key)
+      get_portals.each do |portal|
+        return portal.payment_channels if portal.portal_key == portal_key
+      end
+      []
+    end
+
+    # Create a new payment intent.
+    #
+    # @param data [Hash]
+    # @return [Bayarcash::Resources::PaymentIntentResource]
+    def create_payment_intent(data)
+      Resources::PaymentIntentResource.new(post("payment-intents", data), self)
+    end
+
+    # Get transaction details (v2 and v3).
+    #
+    # @param id [String]
+    # @return [Bayarcash::Resources::TransactionResource]
+    def get_transaction(id)
+      Resources::TransactionResource.new(get("transactions/#{id}"), self)
+    end
+
+    # Get a payment intent by id (v3 only).
+    #
+    # @param payment_intent_id [String]
+    # @return [Bayarcash::Resources::PaymentIntentResource]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_payment_intent(payment_intent_id)
+      ensure_v3!("getPaymentIntent")
+      Resources::PaymentIntentResource.new(get("payment-intents/#{payment_intent_id}"), self)
+    end
+
+    # Cancel a payment intent (v3 only).
+    #
+    # @param payment_intent_id [String]
+    # @return [Bayarcash::Resources::PaymentIntentResource]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def cancel_payment_intent(payment_intent_id)
+      ensure_v3!("cancelPaymentIntent")
+      Resources::PaymentIntentResource.new(delete("payment-intents/#{payment_intent_id}"), self)
+    end
+
+    # Get all transactions with optional filters (v3 only).
+    #
+    # @param parameters [Hash] any of :order_number, :status, :payment_channel,
+    #   :exchange_reference_number, :payer_email
+    # @return [Hash] { data: Array<TransactionResource>, meta: Hash }
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_all_transactions(parameters = {})
+      ensure_v3!("getAllTransactions")
+
+      query_params = parameters.select { |key, _| ALLOWED_TRANSACTION_FILTERS.include?(key.to_s) }
+      query_string = Bayarcash::Util.build_query(query_params)
+      endpoint = "transactions" + (query_string.empty? ? "" : "?#{query_string}")
+
+      response = get(endpoint)
+
+      {
+        data: transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource),
+        meta: response.is_a?(Hash) ? (response["meta"] || {}) : {}
+      }
+    end
+
+    # Get transactions by order number (v3 only).
+    #
+    # @param order_number [String]
+    # @return [Array<Bayarcash::Resources::TransactionResource>]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_transaction_by_order_number(order_number)
+      ensure_v3!("getTransactionByOrderNumber")
+      response = get("transactions?order_number=#{order_number}")
+      transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
+    end
+
+    # Get transactions by payer email (v3 only).
+    #
+    # @param email [String]
+    # @return [Array<Bayarcash::Resources::TransactionResource>]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_transactions_by_payer_email(email)
+      ensure_v3!("getTransactionsByPayerEmail")
+      response = get("transactions?payer_email=#{Bayarcash::Util.url_encode(email)}")
+      transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
+    end
+
+    # Get transactions by status (v3 only).
+    #
+    # @param status [String]
+    # @return [Array<Bayarcash::Resources::TransactionResource>]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_transactions_by_status(status)
+      ensure_v3!("getTransactionsByStatus")
+      response = get("transactions?status=#{status}")
+      transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
+    end
+
+    # Get transactions by payment channel (v3 only).
+    #
+    # @param channel [Integer]
+    # @return [Array<Bayarcash::Resources::TransactionResource>]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_transactions_by_payment_channel(channel)
+      ensure_v3!("getTransactionsByPaymentChannel")
+      response = get("transactions?payment_channel=#{channel}")
+      transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
+    end
+
+    # Get a single transaction by exchange reference number (v3 only).
+    #
+    # @param reference_number [String]
+    # @return [Bayarcash::Resources::TransactionResource, nil]
+    # @raise [Bayarcash::Error] when the API version is not v3
+    def get_transaction_by_reference_number(reference_number)
+      ensure_v3!("getTransactionByReferenceNumber")
+      response = get("transactions?exchange_reference_number=#{Bayarcash::Util.url_encode(reference_number)}")
+      data = response.is_a?(Hash) ? (response["data"] || []) : []
+      return nil if data.nil? || data.empty?
+
+      transform_collection(data, Resources::TransactionResource).first
+    end
+
+    # Return the base URI for the current API version and environment.
+    #
+    # @return [String]
+    def base_uri
+      if @api_version == "v3"
+        @sandbox ? "https://api.console.bayarcash-sandbox.com/v3/" : "https://api.console.bayar.cash/v3/"
+      else
+        @sandbox ? "https://console.bayarcash-sandbox.com/api/v2/" : "https://console.bayar.cash/api/v2/"
+      end
+    end
+
+    private
+
+    # Transform a raw collection into an array of resources.
+    def transform_collection(collection, klass, extra = {})
+      (collection || []).map do |data|
+        klass.new((data || {}).merge(extra), self)
+      end
+    end
+
+    def ensure_v3!(method_name)
+      return if @api_version == "v3"
+
+      raise Bayarcash::Error, "The #{method_name} method is only available for API version v3."
+    end
+  end
+end

data/lib/bayarcash/duit_now/dobw.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  module DuitNow
+    # DuitNow Online Banking / Wallet (DOBW) account types and status codes.
+    class Dobw
+      CASA        = "01"
+      CREDIT_CARD = "02"
+      EWALLET     = "03"
+
+      # Status code
+      STATUS_NEW       = 0
+      STATUS_PENDING   = 1
+      STATUS_FAILED    = 2
+      STATUS_SUCCESS   = 3
+      STATUS_CANCELLED = 4
+
+      STATUS_LABELS = {
+        STATUS_NEW       => "New",
+        STATUS_PENDING   => "Pending",
+        STATUS_CANCELLED => "Cancelled",
+        STATUS_SUCCESS   => "Successful",
+        STATUS_FAILED    => "Failed"
+      }.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
+    end
+  end
+end

data/lib/bayarcash/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # Base class for every error raised by the SDK.
+  class Error < StandardError; end
+
+  # Raised on HTTP 422 responses. Carries the validation error payload from the API.
+  class ValidationError < Error
+    # @return [Hash, Array] the raw errors payload returned by the API
+    attr_reader :errors
+
+    def initialize(errors = {})
+      @errors = errors || {}
+      super("The given data failed to pass validation.")
+    end
+  end
+
+  # Raised on HTTP 404 responses.
+  class NotFoundError < Error
+    def initialize(message = "The resource you are looking for could not be found.")
+      super
+    end
+  end
+
+  # Raised on HTTP 400 responses. The message holds the reason returned by the API.
+  class FailedActionError < Error; end
+
+  # Raised on HTTP 429 responses. Exposes the rate-limit reset timestamp when available.
+  class RateLimitExceededError < Error
+    # @return [Integer, nil] unix timestamp at which the rate limit resets
+    attr_reader :rate_limit_resets_at
+
+    def initialize(rate_limit_reset = nil)
+      @rate_limit_resets_at = rate_limit_reset
+      super("Too Many Requests.")
+    end
+  end
+
+  # Raised by the optional {Bayarcash::MakesHttpRequests#retry_until} helper after a timeout.
+  class TimeoutError < Error
+    # @return [Array] the output collected before the timeout
+    attr_reader :output
+
+    def initialize(output = [])
+      @output = output
+      super("Script timed out while waiting for the process to complete.")
+    end
+  end
+end

data/lib/bayarcash/fpx.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Bayarcash
+  # FPX transaction status codes and their human-readable labels.
+  class Fpx
+    STATUS_NEW       = 0
+    STATUS_PENDING   = 1
+    STATUS_FAILED    = 2
+    STATUS_SUCCESS   = 3
+    STATUS_CANCELLED = 4
+
+    STATUS_LABELS = {
+      STATUS_NEW       => "New",
+      STATUS_PENDING   => "Pending",
+      STATUS_CANCELLED => "Cancelled",
+      STATUS_SUCCESS   => "Successful",
+      STATUS_FAILED    => "Failed"
+    }.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
+  end
+end