cashfree_pg 0.1.0

data/lib/cashfree_pg/money.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+
+module CashfreePg
+  # Converts amounts to a two-decimal JSON number.
+  #
+  # Ruby's JSON library turns a raw BigDecimal into a quoted exponent string
+  # such as "0.101e2". {Number} emits `10.10` instead.
+  #
+  # @api private
+  module Money
+    AMOUNT_KEY = /(?:\A|_)amount\z/
+
+    module_function
+
+    # Walks a payload and wraps amount fields for JSON.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def normalize(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key, key.to_s.match?(AMOUNT_KEY) ? number_for(item) : normalize(item)] }
+      when Array
+        value.map { |item| normalize(item) }
+      else
+        value
+      end
+    end
+
+    # @param value [Integer, String, BigDecimal, Float]
+    # @return [BigDecimal] rounded half-up to two places
+    def coerce(value)
+      decimal = case value
+                when Integer, BigDecimal then BigDecimal(value)
+                when String then decimal_from_string(value)
+                when Float then decimal_from_float(value)
+                else raise ArgumentError, "amount must be a String, Integer, or BigDecimal"
+                end
+      raise ArgumentError, "amount is not a number" unless decimal.finite?
+
+      decimal.round(2, BigDecimal::ROUND_HALF_UP)
+    end
+
+    # @param decimal [BigDecimal] already rounded to two places
+    # @return [String] unquoted JSON number with two decimal places
+    def format_number(decimal)
+      whole, fraction = decimal.to_s("F").split(".", 2)
+      "#{whole}.#{fraction.ljust(2, "0")}"
+    end
+
+    def number_for(value)
+      value.nil? ? nil : Number.new(coerce(value))
+    end
+
+    def decimal_from_string(value)
+      BigDecimal(value.strip)
+    rescue ArgumentError
+      raise ArgumentError, "amount is not a number"
+    end
+
+    def decimal_from_float(value)
+      warn("CashfreePg received a Float amount; pass a String or BigDecimal", uplevel: 2)
+      BigDecimal(value.to_s)
+    end
+    private_class_method :number_for, :decimal_from_string, :decimal_from_float
+
+    # JSON number that does not use exponent notation.
+    class Number
+      # @param decimal [BigDecimal]
+      def initialize(decimal)
+        @decimal = decimal
+      end
+
+      # @return [String]
+      def to_json(*)
+        Money.format_number(@decimal)
+      end
+    end
+    private_constant :Number
+  end
+end

data/lib/cashfree_pg/orders.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Create, fetch and terminate Cashfree orders.
+  class Orders < Resource
+    # A duplicate merchant `order_id` is a {ConflictError}, so reusing your own
+    # `order_id` is the safest way to retry after a timeout.
+    #
+    # @param idempotency_key [String, nil]
+    # @param attrs [Hash] Cashfree create-order fields. `order_amount` is sent as a two-decimal number.
+    # @return [Response]
+    # @example
+    #   client.orders.create(
+    #     order_id: "order_123",
+    #     order_amount: "10.10",
+    #     order_currency: "INR",
+    #     customer_details: { customer_id: "cust_1", customer_phone: "9999999999" }
+    #   )
+    def create(idempotency_key: nil, **attrs)
+      @client.post("/orders", attrs, idempotency_key: idempotency_key)
+    end
+
+    # @param order_id [String] merchant order id
+    # @return [Response]
+    # @example
+    #   client.orders.fetch("order_123")
+    def fetch(order_id)
+      @client.get(order_path(order_id))
+    end
+
+    # Ask Cashfree to terminate an unpaid order. The returned `order_status` may be
+    # `TERMINATION_REQUESTED`; fetch the order to confirm it reached `TERMINATED`.
+    #
+    # @param order_id [String] merchant order id
+    # @return [Response]
+    # @example
+    #   client.orders.terminate("order_123").order_status
+    def terminate(order_id)
+      @client.patch(order_path(order_id), { order_status: "TERMINATED" })
+    end
+  end
+end

data/lib/cashfree_pg/payment_links.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Collect a payment with a Cashfree link.
+  #
+  # SMS notifications are sent only in production. Sandbox sends email when
+  # `link_notify.send_email` is true, and does not send SMS.
+  class PaymentLinks < Resource
+    # @param idempotency_key [String, nil]
+    # @param attrs [Hash] keyword fields; requires `link_amount`, `link_currency`, `link_purpose` and `customer_details`
+    # @return [Response]
+    # @example
+    #   client.payment_links.create(
+    #     link_id: "link_123",
+    #     link_amount: "10.10",
+    #     link_currency: "INR",
+    #     link_purpose: "Test payment",
+    #     customer_details: { customer_phone: "9999999999" }
+    #   )
+    def create(idempotency_key: nil, **attrs)
+      @client.post("/links", attrs, idempotency_key: idempotency_key)
+    end
+
+    # @param link_id [String] merchant link id
+    # @return [Response]
+    # @example
+    #   client.payment_links.fetch("link_123")
+    def fetch(link_id)
+      @client.get("/links/#{segment(link_id, "link_id")}")
+    end
+
+    # Only an ACTIVE link can be cancelled.
+    #
+    # @param link_id [String]
+    # @return [Response]
+    # @example
+    #   client.payment_links.cancel("link_123")
+    def cancel(link_id)
+      @client.post("/links/#{segment(link_id, "link_id")}/cancel")
+    end
+
+    # Orders Cashfree created for a link. Use an order's `order_id` to refund a link payment.
+    #
+    # @param link_id [String]
+    # @param status [String, nil] `"PAID"` or `"ALL"`; Cashfree returns paid orders when nil
+    # @return [Array<Response>]
+    # @example
+    #   order_id = client.payment_links.orders("link_123").first.order_id
+    def orders(link_id, status: nil)
+      path = "/links/#{segment(link_id, "link_id")}/orders"
+      path += "?#{URI.encode_www_form(status: status)}" if status
+      list_of(@client.get(path), "link orders")
+    end
+  end
+end

data/lib/cashfree_pg/payments.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Payments for an order, including UPI via Cashfree order sessions.
+  #
+  # The gem talks only to Cashfree. It never connects to NPCI or a bank.
+  # Calling Order Pay from a server needs Cashfree's S2S feature enabled.
+  # A 403 is a {PermissionError} that says so.
+  class Payments < Resource
+    # Cashfree channel names. `:intent` is UPI intent; Cashfree calls that channel `link`.
+    CHANNELS = {
+      intent: "link",
+      link: "link",
+      qr: "qrcode",
+      qrcode: "qrcode",
+      pod_qr: "podQrCode",
+      collect: "collect"
+    }.freeze
+
+    # @param order_id [String]
+    # @return [Array<Response>]
+    # @example
+    #   client.payments.list("order_123")
+    def list(order_id)
+      list_of(@client.get("#{order_path(order_id)}/payments"), "payments")
+    end
+
+    # @param order_id [String]
+    # @param cf_payment_id [String]
+    # @return [Response]
+    # @example
+    #   client.payments.fetch("order_123", "12376123")
+    def fetch(order_id, cf_payment_id)
+      @client.get("#{order_path(order_id)}/payments/#{segment(cf_payment_id, "cf_payment_id")}")
+    end
+
+    # Start a UPI payment on an order session. No client secret is sent.
+    #
+    # Channels: `:intent` (opens the UPI app), `:qr` (QR image), `:collect` (legacy; needs `upi_id`).
+    # Sandbox collect VPAs include `testsuccess@gocash`.
+    #
+    # @param order [Response, Hash, String] order response, or the payment_session_id
+    # @param channel [Symbol, String]
+    # @param upi_id [String, nil] required for `:collect`
+    # @param options [Hash] other Cashfree UPI fields, such as `upi_expiry_minutes`
+    # @return [Response]
+    # @example
+    #   client.payments.upi(order, channel: :intent)
+    #   client.payments.upi(order, channel: :collect, upi_id: "testsuccess@gocash")
+    def upi(order, channel:, upi_id: nil, **options)
+      cashfree_channel = CHANNELS[channel.to_sym]
+      raise ArgumentError, "channel must be one of #{CHANNELS.keys.join(", ")}" unless cashfree_channel
+      raise ArgumentError, "collect requires upi_id" if cashfree_channel == "collect" && upi_id.nil?
+
+      check_vpa!(upi_id) if upi_id
+      upi = { channel: cashfree_channel, upi_id: upi_id }.compact.merge(options)
+      pay(session_id(order), upi)
+    end
+
+    # Capture or void a pre-authorised payment. `CAPTURE` requires an amount.
+    #
+    # @param order_id [String]
+    # @param action [Symbol, String] `:capture` or `:void`
+    # @param amount [String, Integer, BigDecimal, nil]
+    # @param idempotency_key [String, nil]
+    # @return [Response]
+    # @example
+    #   client.payments.authorize("order_123", action: :capture, amount: "10.10", idempotency_key: "cap_1")
+    def authorize(order_id, action:, amount: nil, idempotency_key: nil)
+      name = action.to_s.upcase
+      raise ArgumentError, "action must be CAPTURE or VOID" unless %w[CAPTURE VOID].include?(name)
+      raise ArgumentError, "CAPTURE requires an amount" if name == "CAPTURE" && amount.nil?
+      raise ArgumentError, "VOID does not take an amount" if name == "VOID" && !amount.nil?
+
+      body = { action: name, amount: amount }.compact
+      @client.post("#{order_path(order_id)}/authorization", body, idempotency_key: idempotency_key)
+    end
+
+    private
+
+    def pay(payment_session_id, upi)
+      @client.post(
+        "/orders/sessions",
+        { payment_session_id: payment_session_id, payment_method: { upi: upi } },
+        skip_auth: true
+      )
+    rescue PermissionError => e
+      raise PermissionError.new(
+        "#{e.message}. Order Pay from a server needs Cashfree S2S enabled on the account",
+        status: e.status, code: e.code, type: e.type,
+        request_id: e.request_id, raw_body: e.raw_body
+      )
+    end
+
+    def session_id(order)
+      return order if order.is_a?(String) && !order.empty?
+
+      id = order["payment_session_id"] || order[:payment_session_id] if order.respond_to?(:[])
+      raise ArgumentError, "payment_session_id is required" if id.nil? || id.to_s.empty?
+
+      id
+    end
+
+    def check_vpa!(upi_id)
+      return if upi_id.to_s.match?(/\A[^@\s]+@[^@\s]+\z/)
+
+      raise ArgumentError, "upi_id must look like name@bank"
+    end
+  end
+end

data/lib/cashfree_pg/refunds.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Refunds for a paid order.
+  #
+  # Pass your own `refund_id`. If a create times out, fetch that id before sending
+  # another refund. Cashfree rejects a duplicate `refund_id` with 409, which is a {ConflictError}.
+  class Refunds < Resource
+    # @param order_id [String]
+    # @param idempotency_key [String, nil]
+    # @param attrs [Hash] keyword fields; requires `refund_amount` and `refund_id`
+    # @return [Response]
+    # @example
+    #   client.refunds.create("order_123", refund_amount: "10.10", refund_id: "refund_00912")
+    def create(order_id, idempotency_key: nil, **attrs)
+      @client.post("#{order_path(order_id)}/refunds", attrs, idempotency_key: idempotency_key)
+    end
+
+    # @param order_id [String]
+    # @param refund_id [String] the merchant refund id
+    # @return [Response]
+    # @example
+    #   client.refunds.fetch("order_123", "refund_00912")
+    def fetch(order_id, refund_id)
+      @client.get("#{order_path(order_id)}/refunds/#{segment(refund_id, "refund_id")}")
+    end
+
+    # Cashfree returns a JSON array. It is not wrapped item by item.
+    #
+    # @param order_id [String]
+    # @return [Response]
+    # @example
+    #   client.refunds.list("order_123").to_h
+    def list(order_id)
+      @client.get("#{order_path(order_id)}/refunds")
+    end
+  end
+end

data/lib/cashfree_pg/request.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module CashfreePg
+  # One HTTPS call. No retries and no logging.
+  #
+  # @api private
+  class Request
+    STATUS_ERRORS = {
+      400 => InvalidRequestError,
+      401 => AuthenticationError,
+      403 => PermissionError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => ValidationError,
+      429 => RateLimitError
+    }.freeze
+
+    # @param client [Client]
+    # @param connection [Faraday::Connection]
+    def initialize(client, connection)
+      @client = client
+      @connection = connection
+    end
+
+    # @param method [Symbol] `:get`, `:post` or `:patch`
+    # @param path [String]
+    # @param body [Hash, nil]
+    # @param skip_auth [Boolean]
+    # @param idempotency_key [String, nil]
+    # @return [Response]
+    def perform(method, path, body: nil, skip_auth: false, idempotency_key: nil)
+      validate_path!(path)
+      @method = method
+      @request_id = SecureRandom.uuid
+      handle(dispatch(request_path(path), body, request_headers(skip_auth, idempotency_key)))
+    rescue Faraday::TimeoutError, Timeout::Error
+      raise timeout_error
+    rescue Faraday::ConnectionFailed, Faraday::SSLError, Errno::ECONNREFUSED, SocketError
+      raise ConnectionError.new("connection failed request_id=#{@request_id}", request_id: @request_id)
+    end
+
+    private
+
+    def dispatch(path, body, headers)
+      @connection.public_send(@method, path) do |req|
+        req.headers.update(headers)
+        req.body = JSON.generate(Money.normalize(body)) if body
+      end
+    end
+
+    def request_headers(skip_auth, idempotency_key)
+      headers = {
+        "User-Agent" => "cashfree_pg/#{VERSION} ruby/#{RUBY_VERSION}",
+        "Accept" => "application/json",
+        "Content-Type" => "application/json",
+        "x-api-version" => @client.api_version,
+        "x-request-id" => @request_id
+      }
+      headers["x-idempotency-key"] = idempotency_key if idempotency_key
+      return headers if skip_auth
+
+      headers.merge("x-client-id" => @client.client_id, "x-client-secret" => @client.client_secret)
+    end
+
+    def handle(response)
+      id = response.headers["x-request-id"]
+      id = @request_id if id.nil? || id.empty?
+      return success(response, id) if response.success?
+
+      raise_api_error(response, id)
+    end
+
+    def success(response, request_id)
+      data = parse_json(response.body)
+      if data.nil?
+        raise APIError.new("invalid JSON response status=#{response.status} request_id=#{request_id}",
+                           status: response.status, request_id: request_id, raw_body: response.body.to_s)
+      end
+
+      Response.new(data, status: response.status, request_id: request_id)
+    end
+
+    def raise_api_error(response, request_id)
+      payload = parse_json(response.body)
+      payload = {} unless payload.is_a?(Hash)
+      klass = STATUS_ERRORS.fetch(response.status, APIError)
+      raise klass.new(
+        error_message(response.status, payload, request_id),
+        status: response.status,
+        code: payload["code"]&.to_s,
+        type: payload["type"]&.to_s,
+        request_id: request_id,
+        raw_body: response.body.to_s
+      )
+    end
+
+    def error_message(status, payload, request_id)
+      parts = ["status=#{status}"]
+      parts << "code=#{payload["code"]}" if payload["code"]
+      parts << "type=#{payload["type"]}" if payload["type"]
+      detail = payload["message"].to_s.gsub(@client.client_secret, "[FILTERED]")
+      parts << detail unless detail.empty?
+      parts << "request_id=#{request_id}"
+      parts.join(" ")
+    end
+
+    # An empty body is `{}`. Invalid JSON is nil.
+    def parse_json(raw)
+      text = raw.to_s
+      return {} if text.strip.empty?
+
+      JSON.parse(text, decimal_class: BigDecimal)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def timeout_error
+      message = "request timed out request_id=#{@request_id}"
+      message = "#{message}; outcome is unknown; fetch before retrying" unless @method == :get
+      TimeoutError.new(message, request_id: @request_id)
+    end
+
+    # A leading slash would make Faraday drop the /pg prefix on the base URL.
+    def request_path(path)
+      path.delete_prefix("/")
+    end
+
+    def validate_path!(path)
+      return if path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
+
+      raise ArgumentError, "path must be a relative path starting with /"
+    end
+  end
+end

data/lib/cashfree_pg/resource.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CashfreePg
+  # Base for the API resources on a {Client}.
+  class Resource
+    # @param client [Client]
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # Wraps each item of a JSON array response so callers get field readers.
+    def list_of(response, name)
+      items = response.to_h
+      unless items.is_a?(Array)
+        raise APIError.new("#{name} list was not an array", status: response.status, request_id: response.request_id)
+      end
+
+      items.map { |item| Response.new(item, status: response.status, request_id: response.request_id) }
+    end
+
+    def order_path(order_id)
+      "/orders/#{segment(order_id, "order_id")}"
+    end
+
+    # Encodes one path segment. Blank ids and ids containing `/` are rejected
+    # so a caller's value cannot change which endpoint is called.
+    def segment(id, name)
+      text = id.to_s.strip
+      raise ArgumentError, "#{name} is required" if text.empty?
+      raise ArgumentError, "#{name} must not contain a slash" if text.include?("/")
+
+      URI.encode_uri_component(text)
+    end
+  end
+end

data/lib/cashfree_pg/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Hash-like Cashfree response. Field names stay as Cashfree sends them.
+  #
+  # Use {#[]} or {#dig} for keys that collide with Ruby methods (`hash`, `class`, `method`).
+  class Response
+    # @return [Integer]
+    attr_reader :status
+
+    # @return [String]
+    attr_reader :request_id
+
+    # @param data [Hash, Array]
+    # @param status [Integer]
+    # @param request_id [String]
+    def initialize(data, status:, request_id:)
+      @data = data
+      @status = status
+      @request_id = request_id
+    end
+
+    # @param key [String, Symbol]
+    # @return [Object, nil]
+    def [](key)
+      body[key.to_s]
+    end
+
+    # @param keys [Array<String, Symbol>]
+    # @return [Object, nil]
+    def dig(*keys)
+      body.dig(*keys.map(&:to_s))
+    end
+
+    # @return [Hash, Array]
+    def to_h
+      @data.is_a?(Hash) ? @data.dup : @data
+    end
+
+    # @param name [Symbol]
+    # @return [Object]
+    def method_missing(name, *args)
+      key = name.to_s
+      if args.empty? && !name.end_with?("=") && body.key?(key) && !self.class.method_defined?(name)
+        body[key]
+      else
+        super
+      end
+    end
+
+    # @param name [Symbol]
+    # @param include_private [Boolean]
+    # @return [Boolean]
+    def respond_to_missing?(name, include_private = false)
+      (body.key?(name.to_s) && !self.class.method_defined?(name)) || super
+    end
+
+    private
+
+    # @return [Hash]
+    def body
+      @data.is_a?(Hash) ? @data : {}
+    end
+  end
+end

data/lib/cashfree_pg/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CashfreePg
+  # Gem version, following Semantic Versioning.
+  VERSION = "0.1.0"
+end