payu-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7174c74c8e761c3551f5cc8630ac654b924487f3b864946cc2ba6eb0e217d348
+  data.tar.gz: 6e03c092a17af45084ba92dc68c8704df3754560906615a7704c87406cb64cbb
+SHA512:
+  metadata.gz: 6d8c2bce20f3b640a9f5d37920eb99f6a0d805e75d5cd9b260d3fd01ebe6e26a833a86ffb650f87cd5206f598728764e621b6326b4ea77cd6767c36baa21e46c
+  data.tar.gz: 58e87cb538219d113cc1e44c32156f89245d8bacb603c6a04fa6cb4539c0d7ba8efb9a7c86898fdafb187889b34667ceab3f79a2a852bcf3b066d44155aef92f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishwajeetsingh Desurkar
+
+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,87 @@
+# payu-ruby
+
+Ruby client for the PayU India payment gateway — hosted-checkout form
+building, callback/reverse-hash verification, server-to-server
+`verify_payment` reconciliation, and refunds. Framework-agnostic; no Rails
+dependency.
+
+## Installation
+
+```ruby
+gem "payu-ruby"
+```
+
+## Usage
+
+```ruby
+client = Payu::Client.new(
+  key:       "your_merchant_key",
+  salt:      "your_merchant_salt",
+  test_mode: true # use test.payu.in
+)
+
+# 1. Build the hosted-checkout redirect form (no network call)
+form = client.build_payment(
+  txnid:       "ORDER-123",
+  amount:      499.00,
+  productinfo: "Tickets for RubyConf",
+  firstname:   "Jane",
+  email:       "jane@example.com",
+  phone:       "9876543210",
+  surl:        "https://app.example.com/payu/callback",
+  furl:        "https://app.example.com/payu/callback",
+  notify_url:  "https://app.example.com/webhooks/payu"
+)
+form.payment_url # => URL to POST form.fields to (form submit or WebView)
+form.fields      # => Hash of all form fields including :hash
+
+# 2. Verify an inbound callback/redirect's hash.
+# Never trust this alone for final state — see below.
+callback = client.verify_callback(params)
+callback.valid? # => true/false
+
+# 3. Server-to-server reconciliation — the source of truth
+result = client.verify_payment(txnid: "ORDER-123")
+result.success? # / .pending? / .failed?
+result.mihpayid
+result.raw # full parsed JSON, for audit logging
+
+# 4. Refunds
+refund = Payu::Refund.new(key: "your_merchant_key", salt: "your_merchant_salt", test_mode: true)
+refund.initiate(mihpayid: result.mihpayid, amount: 499.00)
+refund.status(result.mihpayid)
+```
+
+**Security note**: `verify_callback` never raises on a bad hash — it returns
+`valid?: false` so you decide how to record tampering. The callback's
+reported status is informational only; always follow up with
+`verify_payment` before treating a transaction as successful.
+
+For Rails, expose `GET /checkout/:id/pay` that renders an auto-submit form
+page. For mobile, return `{ payment_url:, params: }` as JSON and have the
+app open `payment_url` in a WebView, POSTing the params.
+
+## Error handling
+
+All errors inherit from `Payu::PayuError`.
+
+- `Payu::ConfigurationError` — missing `key`/`salt`.
+- `Payu::ValidationError` — missing/blank required fields passed to
+  `build_payment`.
+- `Payu::ApiError` — base class for network/API failures; carries `#status`
+  and `#body` when available.
+  - `Payu::NetworkError` — no HTTP response was received (timeout,
+    connection failure).
+  - `Payu::ResponseError` — a response was received, but it was a non-200
+    status or an unparseable body.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/payu/callback_result.rb

@@ -0,0 +1,31 @@
+module Payu
+  # Return value of Client#verify_callback. Never raised on a bad hash —
+  # #valid? reports the outcome so the host decides how to record tampering.
+  #
+  # This is informational only: PayU's reported status here must not be
+  # trusted for final state. Always follow up with Client#verify_payment.
+  class CallbackResult
+    attr_reader :params, :valid
+
+    def initialize(params:, valid:)
+      @params = params
+      @valid = valid
+    end
+
+    def valid? = @valid
+
+    def txnid       = @params[:txnid]
+    def status      = @params[:status]
+    def email       = @params[:email]
+    def firstname   = @params[:firstname]
+    def productinfo = @params[:productinfo]
+    def amount      = @params[:amount]
+    def mihpayid    = @params[:mihpayid]
+
+    def udf1 = @params[:udf1]
+    def udf2 = @params[:udf2]
+    def udf3 = @params[:udf3]
+    def udf4 = @params[:udf4]
+    def udf5 = @params[:udf5]
+  end
+end

data/lib/payu/client.rb

@@ -0,0 +1,77 @@
+module Payu
+  # Stateless/reentrant facade over PayU's hosted-checkout + verify_payment
+  # API. Construct once with credentials and reuse across requests.
+  class Client
+    def initialize(key:, salt:, test_mode: false)
+      @config = Configuration.new
+      @config.key = key
+      @config.salt = salt
+      @config.test_mode = test_mode
+      @config.validate!
+    end
+
+    # Builds the signed hosted-checkout form. No network call is made —
+    # only #verify_payment hits the network.
+    def build_payment(txnid:, amount:, productinfo:, firstname:, email:, phone:,
+                      surl:, furl:, notify_url: nil,
+                      udf1: "", udf2: "", udf3: "", udf4: "", udf5: "")
+      validate_build_payment!(txnid: txnid, amount: amount, email: email)
+
+      amt = format("%.2f", amount)
+
+      hash = Payu::Hash.request(
+        key: @config.key, txnid: txnid, amount: amt,
+        productinfo: productinfo, firstname: firstname, email: email,
+        udf1: udf1, udf2: udf2, udf3: udf3, udf4: udf4, udf5: udf5,
+        salt: @config.salt
+      )
+
+      fields = {
+        key:         @config.key,
+        txnid:       txnid,
+        amount:      amt,
+        productinfo: productinfo,
+        firstname:   firstname,
+        email:       email,
+        phone:       phone.to_s,
+        surl:        surl,
+        furl:        furl,
+        udf1:        udf1.to_s,
+        udf2:        udf2.to_s,
+        udf3:        udf3.to_s,
+        udf4:        udf4.to_s,
+        udf5:        udf5.to_s,
+        hash:        hash
+      }
+      fields[:notify_url] = notify_url if notify_url && !notify_url.empty?
+
+      PaymentForm.new(payment_url: @config.payment_url, fields: fields)
+    end
+
+    # Verifies an inbound callback/redirect's hash. Never raises on a bad
+    # hash — the host decides how to record tampering via #valid?.
+    #
+    # PayU's reported status here is informational only — never trust it
+    # for final state; always follow up with #verify_payment.
+    def verify_callback(params)
+      valid = Payu::Hash.valid_response?(params: params, salt: @config.salt)
+      CallbackResult.new(params: params, valid: valid)
+    end
+
+    # Server-to-server reconciliation — the source of truth for transaction
+    # state.
+    def verify_payment(txnid:)
+      hash = Payu::Hash.api(key: @config.key, command: "verify_payment", var1: txnid, salt: @config.salt)
+      raw = Payu::Http.post_form(@config.api_url, command: "verify_payment", var1: txnid, hash: hash, key: @config.key)
+      VerificationResult.new(txnid: txnid, raw: raw)
+    end
+
+    private
+
+    def validate_build_payment!(txnid:, amount:, email:)
+      raise Payu::ValidationError, "txnid is required" if txnid.to_s.strip.empty?
+      raise Payu::ValidationError, "amount is required" if amount.nil?
+      raise Payu::ValidationError, "email is required" if email.to_s.strip.empty?
+    end
+  end
+end

data/lib/payu/configuration.rb

@@ -0,0 +1,25 @@
+module Payu
+  class Configuration
+    attr_accessor :key, :salt, :test_mode
+
+    # Production endpoints (docs.payu.in, confirmed May 2026)
+    PAYMENT_URL  = "https://secure.payu.in/_payment"
+    API_URL      = "https://secure.payu.in/merchant/postservice?form=2"
+
+    # Sandbox endpoints
+    TEST_PAYMENT_URL = "https://test.payu.in/_payment"
+    TEST_API_URL     = "https://test.payu.in/merchant/postservice?form=2"
+
+    def initialize
+      @test_mode = false
+    end
+
+    def payment_url = test_mode ? TEST_PAYMENT_URL : PAYMENT_URL
+    def api_url     = test_mode ? TEST_API_URL     : API_URL
+
+    def validate!
+      raise ConfigurationError, "Payu key is required"  if key.nil?  || key.empty?
+      raise ConfigurationError, "Payu salt is required" if salt.nil? || salt.empty?
+    end
+  end
+end

data/lib/payu/errors.rb

@@ -0,0 +1,26 @@
+module Payu
+  class PayuError         < StandardError; end
+  class ConfigurationError < PayuError; end
+  class HashMismatchError  < PayuError; end
+  class PaymentFailedError < PayuError; end
+  class ValidationError    < PayuError; end
+
+  # Raised by Payu::Http. Carries the HTTP status and raw body when
+  # available so callers can distinguish failure modes instead of pattern
+  # matching on the message.
+  class ApiError < PayuError
+    attr_reader :status, :body
+
+    def initialize(msg = nil, status: nil, body: nil)
+      super(msg)
+      @status = status
+      @body = body
+    end
+  end
+
+  # No HTTP response was received at all (timeout, connection refused, DNS, ...).
+  class NetworkError < ApiError; end
+
+  # A response was received, but it was a non-200 status or an unparseable body.
+  class ResponseError < ApiError; end
+end

data/lib/payu/hash.rb

@@ -0,0 +1,53 @@
+require "digest"
+
+module Payu
+  module Hash
+    # Request hash — confirmed formula from docs.payu.in (May 2026):
+    #   sha512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT)
+    # 17 pipe-delimited values: 6 mandatory + 5 UDF + 5 empty reserved slots + salt
+    def self.request(key:, txnid:, amount:, productinfo:, firstname:, email:,
+                     udf1: "", udf2: "", udf3: "", udf4: "", udf5: "", salt:)
+      parts = [
+        key, txnid, amount, productinfo, firstname, email,
+        udf1.to_s, udf2.to_s, udf3.to_s, udf4.to_s, udf5.to_s,
+        "", "", "", "", "",  # reserved udf6-udf10 slots
+        salt
+      ]
+      Digest::SHA512.hexdigest(parts.join("|"))
+    end
+
+    # Response hash — field order is REVERSED vs request (confirmed from docs.payu.in):
+    #   sha512(SALT|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)
+    #
+    # Variant: when PayU adds additional_charges (platform/convenience fee), it is prepended:
+    #   sha512(additional_charges|SALT|status|...|key)
+    def self.response(params:, salt:)
+      p = params
+      core = [
+        salt,
+        p[:status].to_s,
+        "", "", "", "", "",  # reserved slots (reversed)
+        p[:udf5].to_s, p[:udf4].to_s, p[:udf3].to_s, p[:udf2].to_s, p[:udf1].to_s,
+        p[:email].to_s, p[:firstname].to_s, p[:productinfo].to_s,
+        p[:amount].to_s, p[:txnid].to_s, p[:key].to_s
+      ]
+      additional = p[:additional_charges].to_s
+      parts = additional.empty? ? core : [additional] + core
+      Digest::SHA512.hexdigest(parts.join("|"))
+    end
+
+    # Constant-time comparison to prevent timing attacks
+    def self.valid_response?(params:, salt:)
+      expected = response(params: params, salt: salt)
+      received = params[:hash].to_s
+      return false if expected.bytesize != received.bytesize
+
+      expected.bytes.zip(received.bytes).reduce(0) { |acc, (a, b)| acc | (a ^ b) }.zero?
+    end
+
+    # Hash for server-to-server API commands: sha512(key|command|var1|salt)
+    def self.api(key:, command:, var1:, salt:)
+      Digest::SHA512.hexdigest("#{key}|#{command}|#{var1}|#{salt}")
+    end
+  end
+end

data/lib/payu/http.rb

@@ -0,0 +1,46 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Payu
+  # Thin internal POST wrapper shared by Client#verify_payment and Refund.
+  # Not part of the public API.
+  class Http
+    USER_AGENT = "payu-ruby/#{Payu::VERSION}; Ruby/#{RUBY_VERSION}".freeze
+
+    def self.post_form(url, params)
+      uri  = URI(url)
+      body = URI.encode_www_form(params)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/x-www-form-urlencoded"
+      req["User-Agent"] = USER_AGENT
+      req.body = body
+
+      resp = http.request(req)
+
+      unless resp.code.to_i == 200
+        raise Payu::ResponseError.new(
+          "PayU returned HTTP #{resp.code}", status: resp.code.to_i, body: resp.body
+        )
+      end
+
+      begin
+        JSON.parse(resp.body)
+      rescue JSON::ParserError => e
+        raise Payu::ResponseError.new(
+          "PayU returned invalid JSON: #{e.message}", status: resp.code.to_i, body: resp.body
+        )
+      end
+    rescue Payu::ApiError
+      raise
+    rescue => e
+      raise Payu::NetworkError, "PayU API call failed: #{e.message}"
+    end
+  end
+end

data/lib/payu/payment_form.rb

@@ -0,0 +1,12 @@
+module Payu
+  # Return value of Client#build_payment. No network call is made to
+  # produce this — it's just the signed field set and the URL to post it to.
+  class PaymentForm
+    attr_reader :payment_url, :fields
+
+    def initialize(payment_url:, fields:)
+      @payment_url = payment_url
+      @fields = fields
+    end
+  end
+end

data/lib/payu/refund.rb

@@ -0,0 +1,38 @@
+module Payu
+  class Refund
+    def initialize(key:, salt:, test_mode: false)
+      @config = Configuration.new
+      @config.key = key
+      @config.salt = salt
+      @config.test_mode = test_mode
+      @config.validate!
+    end
+
+    # Initiate a full or partial refund.
+    # mihpayid: PayU's payment ID (returned in callback as :mihpayid)
+    # amount:   amount to refund (can be partial)
+    def initiate(mihpayid:, amount:)
+      hash = Payu::Hash.api(
+        key: @config.key, command: "cancel_refund_transaction",
+        var1: mihpayid, salt: @config.salt
+      )
+      Payu::Http.post_form(
+        @config.api_url,
+        command: "cancel_refund_transaction", var1: mihpayid, var2: format("%.2f", amount),
+        hash: hash, key: @config.key
+      )
+    end
+
+    # Check refund status by mihpayid.
+    def status(mihpayid)
+      hash = Payu::Hash.api(
+        key: @config.key, command: "get_refund_details",
+        var1: mihpayid, salt: @config.salt
+      )
+      Payu::Http.post_form(
+        @config.api_url,
+        command: "get_refund_details", var1: mihpayid, hash: hash, key: @config.key
+      )
+    end
+  end
+end

data/lib/payu/verification_result.rb

@@ -0,0 +1,29 @@
+module Payu
+  # Return value of Client#verify_payment — the source of truth for
+  # transaction state (never trust the callback/redirect alone).
+  class VerificationResult
+    attr_reader :raw, :txnid
+
+    def initialize(txnid:, raw:)
+      @txnid = txnid
+      @raw = raw
+    end
+
+    def success? = transaction_status == "success"
+    def pending? = transaction_status == "pending"
+    def failed?  = !success? && !pending?
+
+    def mihpayid     = transaction_details["mihpayid"]
+    def bank_ref_num = transaction_details["bank_ref_num"]
+
+    private
+
+    def transaction_status
+      transaction_details["status"]
+    end
+
+    def transaction_details
+      @raw.dig("transaction_details", @txnid) || {}
+    end
+  end
+end

data/lib/payu/version.rb

@@ -0,0 +1,3 @@
+module Payu
+  VERSION = "0.1.0"
+end

data/lib/payu.rb

@@ -0,0 +1,50 @@
+require "payu/version"
+require "payu/errors"
+require "payu/http"
+require "payu/configuration"
+require "payu/hash"
+require "payu/payment_form"
+require "payu/callback_result"
+require "payu/verification_result"
+require "payu/client"
+require "payu/refund"
+
+# Payu — Ruby client for PayU India payment gateway.
+#
+# Usage:
+#   client = Payu::Client.new(
+#     key:       "your_merchant_key",
+#     salt:      "your_merchant_salt",
+#     test_mode: true   # use test.payu.in
+#   )
+#
+#   # 1. Build the hosted-checkout redirect form (no network call)
+#   form = client.build_payment(
+#     txnid:       "ORDER-123",
+#     amount:      499.00,
+#     productinfo: "Tickets for RubyConf",
+#     firstname:   "Jane",
+#     email:       "jane@example.com",
+#     phone:       "9876543210",
+#     surl:        "https://app.example.com/payu/callback",
+#     furl:        "https://app.example.com/payu/callback",
+#     notify_url:  "https://app.example.com/webhooks/payu"
+#   )
+#   form.payment_url  # => URL to POST form.fields to (form submit or WebView)
+#   form.fields        # => Hash of all form fields including :hash
+#
+#   # 2. Verify an inbound callback/redirect's hash (never trust it for final state)
+#   callback = client.verify_callback(params)
+#   callback.valid?  # => true/false
+#
+#   # 3. Server-to-server reconciliation — the source of truth
+#   result = client.verify_payment(txnid: "ORDER-123")
+#   result.success? / result.pending? / result.failed?
+#   result.mihpayid
+#   result.raw        # full parsed JSON, for audit logging
+#
+# For Rails, expose GET /checkout/:id/pay that renders an auto-submit form page.
+# For mobile, return { payment_url:, params: } as JSON; the app opens payment_url
+# in a WebView posting the params.
+module Payu
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: payu-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vishwajeetsingh Desurkar
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Hash generation, payment initiation params, server-to-server verification,
+  and refund support for PayU India. Framework-agnostic — works with Rails, Sinatra,
+  or plain Ruby.
+email:
+- vishwajeetsinghd@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/payu.rb
+- lib/payu/callback_result.rb
+- lib/payu/client.rb
+- lib/payu/configuration.rb
+- lib/payu/errors.rb
+- lib/payu/hash.rb
+- lib/payu/http.rb
+- lib/payu/payment_form.rb
+- lib/payu/refund.rb
+- lib/payu/verification_result.rb
+- lib/payu/version.rb
+homepage: https://github.com/Selectus2/payu-rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby client for PayU India payment gateway
+test_files: []