cashfree_pg 0.1.0

data/lib/cashfree_pg/webhook.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module CashfreePg
+  # Verifies a Cashfree webhook, then parses it.
+  #
+  # The signature is Base64(HMAC-SHA256(timestamp + raw body, client secret)).
+  # Pass the raw body string. A parsed Hash will not match.
+  # `tolerance` is a timestamp window in seconds. It is off unless you set it,
+  # because Cashfree retries reuse the original timestamp.
+  class Webhook
+    # A verified event. Unknown `type` values are returned as sent.
+    #
+    # @!attribute [r] type
+    #   @return [String, nil]
+    # @!attribute [r] time
+    #   @return [String, nil] Cashfree `event_time`
+    # @!attribute [r] data
+    #   @return [Hash, nil]
+    # @!attribute [r] version
+    #   @return [String, nil] `x-webhook-version`
+    Event = Data.define(:type, :time, :data, :version)
+
+    # @param raw_body [String] exact request body, not a parsed Hash
+    # @param headers [Hash] plain Hash, Rack env, or Rails headers
+    # @param secret [String] Cashfree client secret
+    # @param tolerance [Numeric, nil] seconds; nil skips the timestamp check
+    # @return [Event]
+    # @raise [SignatureVerificationError]
+    # @example
+    #   CashfreePg::Webhook.construct_event(
+    #     raw_body: request.raw_post,
+    #     headers: request.headers,
+    #     secret: ENV.fetch("CASHFREE_CLIENT_SECRET")
+    #   )
+    def self.construct_event(raw_body:, headers:, secret:, tolerance: nil)
+      new(raw_body, headers, secret, tolerance).construct
+    end
+    private_class_method :new
+
+    # @api private
+    def initialize(raw_body, headers, secret, tolerance)
+      @raw_body = raw_body
+      @headers = headers
+      @secret = secret
+      @tolerance = tolerance
+    end
+
+    # @api private
+    def construct
+      check_input!
+      signature = present_header("x-webhook-signature")
+      timestamp = present_header("x-webhook-timestamp")
+      raise SignatureVerificationError, "webhook signature does not match" unless valid?(timestamp, signature)
+
+      check_window!(timestamp)
+      build_event(header("x-webhook-version"))
+    end
+
+    private
+
+    # A blank secret would let anyone sign with an empty key.
+    def check_input!
+      raise SignatureVerificationError, "webhook secret is missing" if @secret.to_s.strip.empty?
+      raise SignatureVerificationError, "webhook body must be a string" unless @raw_body.is_a?(String)
+      raise SignatureVerificationError, "webhook body is empty" if @raw_body.empty?
+      raise SignatureVerificationError, "webhook headers are missing" unless @headers.respond_to?(:each)
+    end
+
+    def valid?(timestamp, signature)
+      digest = OpenSSL::HMAC.digest("SHA256", @secret.to_s, "#{timestamp}#{@raw_body}")
+      expected = [digest].pack("m0")
+      signature.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(expected, signature)
+    end
+
+    def check_window!(timestamp)
+      return if @tolerance.nil? || within_window?(timestamp)
+
+      raise SignatureVerificationError, "webhook timestamp is outside the allowed window"
+    end
+
+    def within_window?(timestamp)
+      (Time.now.to_f - (Integer(timestamp, 10) / 1000.0)).abs <= @tolerance
+    rescue ArgumentError
+      false
+    end
+
+    def present_header(name)
+      value = header(name).to_s
+      raise SignatureVerificationError, "webhook #{name.delete_prefix("x-webhook-")} is missing" if value.strip.empty?
+
+      value
+    end
+
+    def header(name)
+      @headers.each do |key, value|
+        return value if header_name(key) == name
+      end
+      nil
+    end
+
+    def header_name(key)
+      key.to_s.downcase.tr("_", "-").delete_prefix("http-")
+    end
+
+    def build_event(version)
+      payload = JSON.parse(@raw_body, decimal_class: BigDecimal)
+      raise SignatureVerificationError, "webhook body is not JSON" unless payload.is_a?(Hash)
+
+      Event.new(type: payload["type"], time: payload["event_time"], data: payload["data"], version: version)
+    rescue JSON::ParserError
+      raise SignatureVerificationError, "webhook body is not JSON"
+    end
+  end
+end

data/lib/cashfree_pg.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "cashfree_pg/version"
+require_relative "cashfree_pg/errors"
+require_relative "cashfree_pg/money"
+require_relative "cashfree_pg/response"
+require_relative "cashfree_pg/client"
+require_relative "cashfree_pg/resource"
+require_relative "cashfree_pg/orders"
+require_relative "cashfree_pg/payments"
+require_relative "cashfree_pg/refunds"
+require_relative "cashfree_pg/payment_links"
+require_relative "cashfree_pg/webhook"
+
+# Ruby client for the Cashfree Payments API.
+module CashfreePg
+end

data/sig/cashfree_pg.rbs

@@ -0,0 +1,125 @@
+module CashfreePg
+  VERSION: String
+
+  class Error < StandardError
+    attr_reader status: Integer?
+    attr_reader code: String?
+    attr_reader type: String?
+    attr_reader request_id: String?
+    attr_reader raw_body: String?
+
+    def initialize: (?String? message, ?status: Integer?, ?code: String?, ?type: String?, ?request_id: String?, ?raw_body: String?) -> void
+    def inspect: () -> String
+  end
+
+  class InvalidRequestError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class PermissionError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class ConflictError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  class RateLimitError < Error
+  end
+
+  class APIError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class SignatureVerificationError < Error
+  end
+
+  class Response
+    attr_reader status: Integer
+    attr_reader request_id: String
+
+    def initialize: (Hash[String, untyped] | Array[untyped] data, status: Integer, request_id: String) -> void
+    def []: (String | Symbol key) -> untyped
+    def dig: (*String | Symbol keys) -> untyped
+    def to_h: () -> (Hash[String, untyped] | Array[untyped])
+  end
+
+  class Client
+    SANDBOX_URL: String
+    PRODUCTION_URL: String
+    DEFAULT_API_VERSION: String
+
+    attr_reader client_id: String
+    attr_reader client_secret: String
+    attr_reader environment: Symbol
+    attr_reader api_version: String
+    attr_reader base_url: String
+
+    def initialize: (client_id: String, client_secret: String, ?environment: Symbol, ?api_version: String, ?open_timeout: Numeric, ?read_timeout: Numeric, ?base_url: String?, ?allow_custom_base_url: bool) -> void
+    def get: (String path, ?skip_auth: bool) -> Response
+    def post: (String path, ?Hash[untyped, untyped]? body, ?skip_auth: bool, ?idempotency_key: String?) -> Response
+    def patch: (String path, Hash[untyped, untyped] body) -> Response
+    def orders: () -> Orders
+    def payments: () -> Payments
+    def refunds: () -> Refunds
+    def payment_links: () -> PaymentLinks
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+
+  class Resource
+    def initialize: (Client client) -> void
+  end
+
+  class Orders < Resource
+    def create: (?idempotency_key: String?, **untyped) -> Response
+    def fetch: (String order_id) -> Response
+    def terminate: (String order_id) -> Response
+  end
+
+  class Refunds < Resource
+    def create: (String order_id, ?idempotency_key: String?, **untyped) -> Response
+    def fetch: (String order_id, String refund_id) -> Response
+    def list: (String order_id) -> Response
+  end
+
+  class PaymentLinks < Resource
+    def create: (?idempotency_key: String?, **untyped) -> Response
+    def fetch: (String link_id) -> Response
+    def cancel: (String link_id) -> Response
+    def orders: (String link_id, ?status: String?) -> Array[Response]
+  end
+
+  class Payments < Resource
+    CHANNELS: Hash[Symbol, String]
+
+    def list: (String order_id) -> Array[Response]
+    def fetch: (String order_id, String cf_payment_id) -> Response
+    def upi: (untyped order, channel: Symbol | String, ?upi_id: String?, **untyped) -> Response
+    def authorize: (String order_id, action: Symbol | String, ?amount: untyped?, ?idempotency_key: String?) -> Response
+  end
+
+  class Webhook
+    class Event < ::Data
+      attr_reader type: String?
+      attr_reader time: String?
+      attr_reader data: untyped
+      attr_reader version: String?
+
+      def self.new: (type: String?, time: String?, data: untyped, version: String?) -> instance
+    end
+
+    def self.construct_event: (raw_body: String, headers: untyped, secret: String, ?tolerance: Numeric?) -> Event
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: cashfree_pg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Muballigh Faraz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-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'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 'A small, well-tested Ruby client for Cashfree Payment Gateway APIs:
+  orders, payments, UPI, refunds, payment links and webhook verification. Instance-based,
+  thread-safe, with API version pinning, exact money handling and secrets redacted
+  by default. Not affiliated with or endorsed by Cashfree Payments.'
+email:
+- support@shadbox.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cashfree_pg.rb
+- lib/cashfree_pg/client.rb
+- lib/cashfree_pg/errors.rb
+- lib/cashfree_pg/money.rb
+- lib/cashfree_pg/orders.rb
+- lib/cashfree_pg/payment_links.rb
+- lib/cashfree_pg/payments.rb
+- lib/cashfree_pg/refunds.rb
+- lib/cashfree_pg/request.rb
+- lib/cashfree_pg/resource.rb
+- lib/cashfree_pg/response.rb
+- lib/cashfree_pg/version.rb
+- lib/cashfree_pg/webhook.rb
+- sig/cashfree_pg.rbs
+homepage: https://github.com/Shadbox-Infosystem/cashfree_pg
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Shadbox-Infosystem/cashfree_pg
+  source_code_uri: https://github.com/Shadbox-Infosystem/cashfree_pg
+  changelog_uri: https://github.com/Shadbox-Infosystem/cashfree_pg/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Shadbox-Infosystem/cashfree_pg/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Unofficial Ruby client for the Cashfree Payments API.
+test_files: []