cmi_gateway 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c97198a524328f6200fc9b97710753837cb1b714ce85a1fa63edee8218c529d
+  data.tar.gz: 34b389efec7b6f48e6a5a451fdd0882cc36d52505d2528a4ee766d9baf32242e
+SHA512:
+  metadata.gz: 04c936c4c22cce98adfc2ee290db15f46f1e474f277f4fce47e87777ce8e736595b7d1d709bb3b5bcc4f59f57d428c1e96a6b0f00be25260190ae3e975449013
+  data.tar.gz: 47b3153a671f1c6d34e5f69d253bdfc1413ec6fbb2f9dc1b1a4041a5ebb3ee94e73cd3c5facd40b5e8983b738ee36b3c7f432eb4be80feaa400233ddfe9c4a8a

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-07
+
+### Added
+
+- `CmiGateway::Configuration` and global `CmiGateway.configure` for environment and merchant profiles (default + named, e.g. `:vc`).
+- `CmiGateway::Checkout` — 3D Pay Hosting parameter build, SHA-512 hash (`ver3`), test/production gateway URLs.
+- `CmiGateway::Callback` — parse callback params; `success?` from `ProcReturnCode` / `Response`.
+- `CmiGateway::Helpers` — amount formatting, hash escaping, transliteration helpers.
+- RSpec suite and GitHub Actions CI (Ruby 3.1–3.3).
+
+[Unreleased]: https://github.com/merouaneamqor/cmi_gateway/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/merouaneamqor/cmi_gateway/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ollazen
+
+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/README.md

@@ -0,0 +1,125 @@
+# cmi_gateway
+
+Ruby helpers for **CMI (Centre Monétique Interbancaire)** [3D Pay Hosting](https://www.cmi.co.ma/) integration: build signed checkout form parameters (SHA-512 + Base64) and parse server callbacks.
+
+- **No Rails required** — uses only the Ruby standard library.
+- **Multiple merchant profiles** (e.g. default + VC) via `CmiGateway.configure`.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "cmi_gateway", github: "merouaneamqor/cmi_gateway"
+# or, during development:
+# gem "cmi_gateway", path: "../cmi_gateway"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+require "cmi_gateway"
+
+CmiGateway.configure do |config|
+  config.environment = :test # or :production
+
+  config.client_id = ENV.fetch("CMI_CLIENT_ID", nil)
+  config.store_key = ENV.fetch("CMI_STORE_KEY", nil)
+
+  vc_id = ENV["CMI_VC_CLIENT_ID"].to_s.strip
+  vc_key = ENV["CMI_VC_STORE_KEY"].to_s.strip
+  if !vc_id.empty? && !vc_key.empty?
+    config.add_profile(:vc, client_id: vc_id, store_key: vc_key)
+  end
+end
+```
+
+In Rails, put this in `config/initializers/cmi_gateway.rb` and map `config.environment` to `Rails.env.production?`.
+
+## Building a checkout (browser POST to CMI)
+
+```ruby
+checkout = CmiGateway::Checkout.new(
+  amount: 199.00,
+  order_id: "BOOK-123",
+  ok_url: "https://example.com/pay/ok",
+  fail_url: "https://example.com/pay/fail",
+  callback_url: "https://api.example.com/webhooks/cmi",
+  email: "user@example.com",
+  phone: "0600000000",
+  bill_to_name: "Jean Dupont",
+  bill_to_street1: "12 Rue Example",
+  bill_to_city: "Casablanca",
+  bill_to_postal_code: "20000",
+  shopurl: "https://example.com",
+  lang: "fr",
+  tran_type: "PreAuth",
+  profile: :default,      # or :vc when configured
+  accent_strip: false,   # set true for stricter VC-style accent handling on hash inputs
+  extra_params: {}       # merged into signed params (string keys recommended)
+)
+
+checkout.action_url # test or production est3Dgate URL
+checkout.params     # Hash including "hash" — use as hidden fields in a form POST
+```
+
+Validate before rendering:
+
+```ruby
+checkout.validate! # raises CmiGateway::ValidationError
+# or
+checkout.valid?
+checkout.errors
+```
+
+### Low-level hash (tests / custom param sets)
+
+```ruby
+params_without_hash = { "clientid" => "...", "amount" => "10.00", "encoding" => "utf-8" }
+digest = CmiGateway::Checkout.build_hash(params_without_hash, "store_key", accent_strip: false)
+```
+
+## Parsing callbacks
+
+CMI posts form fields back to your `callbackUrl`. Success is detected the same way as common CMI samples: `ProcReturnCode == "00"` or `Response` case-insensitively equals `"Approved"`.
+
+```ruby
+callback = CmiGateway::Callback.new(request.request_parameters) # Rails
+# or CmiGateway::Callback.new(params.to_unsafe_h)
+
+callback.success?
+callback.order_id
+callback.transaction_id
+callback.auth_code
+callback.error_code   # when not successful
+callback.error_message
+callback.raw          # indifferent string-key hash
+```
+
+**Security note:** This gem does not verify a callback `hash` from CMI; confirm with your acquirer whether server-to-server verification is required and implement it if so.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Community
+
+- [Contributing](CONTRIBUTING.md)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+- AI assistants: see [CLAUDE.md](CLAUDE.md)
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/cmi_gateway/callback.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CmiGateway
+  class Callback
+    attr_reader :raw
+
+    def initialize(params)
+      @raw = stringify_keys(params)
+    end
+
+    def success?
+      code = @raw["ProcReturnCode"].to_s
+      response = @raw["Response"].to_s
+      code == "00" || response.casecmp("Approved").zero?
+    end
+
+    def order_id
+      o = @raw["oid"].to_s.strip
+      return o unless o.empty?
+
+      o2 = @raw["OrderId"].to_s.strip
+      o2.empty? ? nil : o2
+    end
+
+    def transaction_id
+      t = @raw["TransId"].to_s.strip
+      t.empty? ? nil : t
+    end
+
+    def auth_code
+      a = @raw["AuthCode"].to_s.strip
+      a.empty? ? nil : a
+    end
+
+    def error_code
+      return nil if success?
+
+      c = @raw["ProcReturnCode"].to_s.strip
+      c.empty? ? nil : c
+    end
+
+    def error_message
+      return nil if success?
+
+      m = @raw["ErrMsg"].to_s.strip
+      m.empty? ? nil : m
+    end
+
+    def [](key)
+      @raw[key.to_s]
+    end
+
+    private
+
+    def stringify_keys(params)
+      return {} if params.nil?
+
+      params.each_with_object({}) do |(k, v), out|
+        out[k.to_s] = v
+      end
+    end
+  end
+end

data/lib/cmi_gateway/checkout.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+require "bigdecimal"
+
+module CmiGateway
+  class Checkout
+    STORE_TYPE = "3D_PAY_HOSTING"
+    DEFAULT_HASH_ALGORITHM = "ver3"
+    DEFAULT_ENCODING = "utf-8"
+    DEFAULT_LANG = "fr"
+    DEFAULT_TRAN_TYPE = "PreAuth"
+    DEFAULT_CURRENCY = "504"
+    DEFAULT_COUNTRY = "504"
+
+    PRODUCTION_URL = "https://payment.cmi.co.ma/fim/est3Dgate"
+    TEST_URL = "https://testpayment.cmi.co.ma/fim/est3Dgate"
+
+    attr_reader :accent_strip, :profile_name
+
+    def initialize(
+      amount:,
+      order_id:,
+      ok_url:,
+      fail_url:,
+      callback_url:,
+      currency: DEFAULT_CURRENCY,
+      lang: DEFAULT_LANG,
+      tran_type: DEFAULT_TRAN_TYPE,
+      email: nil,
+      phone: nil,
+      bill_to_name: nil,
+      bill_to_street1: nil,
+      bill_to_city: nil,
+      bill_to_postal_code: nil,
+      bill_to_country: DEFAULT_COUNTRY,
+      shopurl: nil,
+      accent_strip: false,
+      profile: :default,
+      extra_params: {},
+      configuration: nil
+    )
+      @amount = amount
+      @order_id = order_id
+      @ok_url = ok_url
+      @fail_url = fail_url
+      @callback_url = callback_url
+      @currency = currency
+      @lang = lang
+      @tran_type = tran_type
+      @email = email
+      @phone = phone
+      @bill_to_name = bill_to_name
+      @bill_to_street1 = bill_to_street1
+      @bill_to_city = bill_to_city
+      @bill_to_postal_code = bill_to_postal_code
+      @bill_to_country = bill_to_country
+      @shopurl = shopurl
+      @accent_strip = accent_strip
+      @profile_name = profile
+      @extra_params = stringify_keys(extra_params || {})
+      @configuration = configuration || CmiGateway.configuration
+    end
+
+    def action_url
+      @configuration.production? ? PRODUCTION_URL : TEST_URL
+    end
+
+    def params
+      @params ||= build_signed_params
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def validate!
+      raise ValidationError, errors.join(", ") unless valid?
+
+      self
+    end
+
+    def errors
+      @errors ||= begin
+        errs = []
+        errs << "amount is required" if @amount.nil? && !@extra_params.key?("amount")
+        errs << "order_id is required" if @order_id.to_s.strip.empty?
+        errs << "ok_url is required" if @ok_url.to_s.strip.empty?
+        errs << "fail_url is required" if @fail_url.to_s.strip.empty?
+        errs << "callback_url is required" if @callback_url.to_s.strip.empty?
+        begin
+          prof = @configuration.profile_for(@profile_name)
+          errs << "CMI client_id is missing for profile #{@profile_name.inspect}" if prof.client_id.to_s.strip.empty?
+          errs << "CMI store_key is missing for profile #{@profile_name.inspect}" if prof.store_key.to_s.strip.empty?
+        rescue UnknownProfileError => e
+          errs << e.message
+        end
+        errs
+      end
+    end
+
+    def self.build_hash(params, store_key, accent_strip: false)
+      plain = +""
+      params.keys.sort_by(&:downcase).each do |key|
+        next if %w[hash encoding].include?(key)
+
+        val = params[key].to_s.strip
+        val = val.tr(Helpers::ACCENT_MAP, Helpers::ACCENT_REP) if accent_strip
+        plain << Helpers.escape_hash_component(val) << "|"
+      end
+      plain << store_key.to_s
+
+      Base64.strict_encode64(Digest::SHA2.new(512).digest(plain))
+    end
+
+    private
+
+    def profile
+      @profile ||= @configuration.profile_for(@profile_name)
+    end
+
+    def build_signed_params
+      validate!
+
+      amount_value = @amount.nil? ? @extra_params["amount"] : @amount
+
+      base = {
+        "clientid" => profile.client_id.to_s,
+        "storetype" => STORE_TYPE,
+        "TranType" => @tran_type.to_s,
+        "amount" => Helpers.format_amount(amount_value),
+        "currency" => @currency.to_s,
+        "oid" => @order_id.to_s,
+        "okUrl" => @ok_url.to_s,
+        "failUrl" => @fail_url.to_s,
+        "callbackUrl" => @callback_url.to_s,
+        "lang" => @lang.to_s,
+        "rnd" => random_rnd,
+        "hashAlgorithm" => DEFAULT_HASH_ALGORITHM,
+        "encoding" => DEFAULT_ENCODING,
+        "callBackResponse" => "true",
+      }
+
+      base["email"] = @email.to_s if @email
+      base["tel"] = @phone.to_s if @phone
+      base["BillToName"] = format_name(@bill_to_name) if @bill_to_name
+      base["BillToStreet1"] = format_street(@bill_to_street1) if @bill_to_street1
+      base["BillToCity"] = @bill_to_city.to_s.strip if @bill_to_city
+      base["BillToPostalCode"] = @bill_to_postal_code.to_s if @bill_to_postal_code
+      base["BillToCountry"] = @bill_to_country.to_s
+      base["shopurl"] = @shopurl.to_s if @shopurl
+
+      merged = base.merge(@extra_params)
+      hash = self.class.build_hash(merged, profile.store_key, accent_strip: @accent_strip)
+      merged.merge("hash" => hash)
+    end
+
+    def random_rnd
+      rand(36**17).to_s(36)
+    end
+
+    def format_name(name)
+      base = name.to_s.strip
+      return "" if base.empty?
+
+      ascii = base.unicode_normalize(:nfkd).encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+      ascii = Helpers.apply_accent_map(ascii) if @accent_strip
+      ascii.strip
+    end
+
+    def format_street(address)
+      base = Helpers.transliterate_street(address)
+      base = Helpers.apply_accent_map(base) if @accent_strip
+      base
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(k, v), out|
+        out[k.to_s] = v
+      end
+    end
+  end
+end

data/lib/cmi_gateway/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CmiGateway
+  class Configuration
+    attr_accessor :environment, :client_id, :store_key
+    attr_reader :named_profiles
+
+    def initialize
+      @environment = :test
+      @client_id = nil
+      @store_key = nil
+      @named_profiles = {}
+    end
+
+    def add_profile(name, client_id:, store_key:)
+      @named_profiles[name.to_sym] = Profile.new(client_id: client_id, store_key: store_key)
+    end
+
+    def profile_for(name)
+      key = (name || :default).to_sym
+      return default_profile if key == :default
+
+      prof = @named_profiles[key]
+      raise UnknownProfileError, "Unknown CMI profile: #{name.inspect}" if prof.nil?
+
+      prof
+    end
+
+    def default_profile
+      Profile.new(client_id: @client_id, store_key: @store_key)
+    end
+
+    def production?
+      @environment.to_s.downcase == "production"
+    end
+  end
+end

data/lib/cmi_gateway/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CmiGateway
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class UnknownProfileError < Error; end
+
+  class ValidationError < Error; end
+end

data/lib/cmi_gateway/helpers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CmiGateway
+  module Helpers
+    module_function
+
+    ACCENT_MAP = "àâçèéêîôùû"
+    ACCENT_REP = "aaceeeiouu"
+
+    # CMI amount format: two decimal places.
+    def format_amount(value)
+      numeric = case value
+                when String then BigDecimal(value)
+                when Integer, Float, BigDecimal then BigDecimal(value.to_s)
+                else BigDecimal("0")
+                end
+      format("%.2f", numeric)
+    end
+
+    # Hash pipeline: strip, escape | then \ (order matches CMI integration gist).
+    def escape_hash_component(value)
+      value.to_s.strip.gsub("|", "\\|").gsub("\\", "\\\\")
+    end
+
+    def apply_accent_map(value)
+      value.to_s.tr(ACCENT_MAP, ACCENT_REP)
+    end
+
+    # ASCII-ish name for BillTo fields (no Rails I18n).
+    def transliterate_name(name)
+      base = name.to_s.strip
+      return "" if base.empty?
+
+      base.unicode_normalize(:nfkd).encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+           .gsub(/[^0-9A-Za-z ]/, " ")
+           .squeeze(" ")
+           .strip
+    end
+
+    # Street-style sanitization: transliterate then strip non-alphanumeric except space.
+    def transliterate_street(address)
+      base = address.to_s.strip
+      return "" if base.empty?
+
+      base.unicode_normalize(:nfkd).encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+           .gsub(/[^0-9A-Za-z ]/, "")
+           .squeeze(" ")
+           .strip
+    end
+  end
+end

data/lib/cmi_gateway/profile.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CmiGateway
+  class Profile
+    attr_reader :client_id, :store_key
+
+    def initialize(client_id:, store_key:)
+      @client_id = client_id
+      @store_key = store_key
+    end
+
+    def complete?
+      !client_id.to_s.strip.empty? && !store_key.to_s.strip.empty?
+    end
+  end
+end

data/lib/cmi_gateway/version.rb

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

data/lib/cmi_gateway.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "cmi_gateway/version"
+require_relative "cmi_gateway/errors"
+require_relative "cmi_gateway/profile"
+require_relative "cmi_gateway/configuration"
+require_relative "cmi_gateway/helpers"
+require_relative "cmi_gateway/checkout"
+require_relative "cmi_gateway/callback"
+
+module CmiGateway
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: cmi_gateway
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AMQOR MEROUANE
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-07 00:00:00.000000000 Z
+dependencies:
+- !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.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: Builds CMI payment form parameters and SHA-512 hash; parses server callbacks.
+email:
+- marouaneamqor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cmi_gateway.rb
+- lib/cmi_gateway/callback.rb
+- lib/cmi_gateway/checkout.rb
+- lib/cmi_gateway/configuration.rb
+- lib/cmi_gateway/errors.rb
+- lib/cmi_gateway/helpers.rb
+- lib/cmi_gateway/profile.rb
+- lib/cmi_gateway/version.rb
+homepage: https://github.com/merouaneamqor/cmi_gateway
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/merouaneamqor/cmi_gateway
+  source_code_uri: https://github.com/merouaneamqor/cmi_gateway
+  changelog_uri: https://github.com/merouaneamqor/cmi_gateway/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/merouaneamqor/cmi_gateway/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: CMI (Morocco) 3D Pay Hosting checkout signing and callback parsing
+test_files: []