rma-payment-gateway 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db28ad0604ff2c4059955f10b342d1b3b0646f6c7a356659c1fa92e6a223bfb5
-  data.tar.gz: 055de1e3a1b750b7087db7dff5c3a93352b0f376beec3406300456ef290d565b
+  metadata.gz: 93083bc4a39780d2b7387e013edf0e71d01bcdd128582383c0805edf8173f461
+  data.tar.gz: 1dbea3526aed562579e070a1cc99470be1ff94d76bce1c2f6fd8780c6b033bbf
 SHA512:
-  metadata.gz: 8c76f60d57151def8dea62e8e306b9249fd3ae6b9d6d2d786423ee94c7a0980ec146786d8c214e54eee8c7f622c21185e7665703d77420b7ed641afcd5ca86b4
-  data.tar.gz: 185416f5968e942cc855151733cf7493f31bfc07af6bf8df0db1009e9416f7b7e8adf6456d037fa547ccedd424c5e698c0afc40de23bf5696e435e14b88a1b19
+  metadata.gz: f9f2d09bf865b4b4575fc18e54f990e98cd13f732c53a337a78ccbcc9ae8de7a94cdd9ac52a2b0a91a3191d803672bcd9d6e1fb4464cf883e3c3bd445c3d0f51
+  data.tar.gz: 94d79e7619c070b68d7e29704d27bcc2e6bfca44dd745801e1be6b63ea8220e9bc24629eb4212971364d41268a2f1fb68d5b251f96ba435fef8c05e1c32b59de

data/README.md

@@ -1,7 +1,7 @@
 # RMA Payment Gateway Ruby Gem
 
 [![Gem Version](https://badge.fury.io/rb/rma-payment-gateway.svg)](https://badge.fury.io/rb/rma-payment-gateway)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-ruby.svg)](https://www.ruby-lang.org/en/)
 
 A Ruby gem for integrating with the RMA (Royal Monetary Authority of Bhutan) Payment Gateway API. This gem provides a simple and intuitive interface for processing payments through the RMA Payment Gateway system.
 

data/examples/basic_payment.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'rma/payment/gateway'
+
+# Configure the gateway
+Rma::Payment::Gateway.configure do |config|
+  config.base_url = ENV['RMA_BASE_URL'] || 'https://your-rma-gateway-url.com'
+  config.rsa_key_path = ENV['RMA_RSA_KEY_PATH'] || 'config/rma_private_key.pem'
+  config.beneficiary_id = ENV['RMA_BENEFICIARY_ID'] || 'your_beneficiary_id'
+  config.payment_description = ENV['RMA_PAYMENT_DESCRIPTION'] || 'Payment for services'
+end
+
+# Initialize client
+client = Rma::Payment::Gateway::Client.new
+
+def process_payment(client, order_no, amount, email, bank_id, account_no, otp)
+  puts "🚀 Starting payment process for Order: #{order_no}"
+  puts "💰 Amount: #{amount} BTN"
+  puts "📧 Email: #{email}"
+  puts "-" * 50
+
+  begin
+    # Step 1: Authorization
+    puts "\n1️⃣  Requesting payment authorization..."
+    auth_response = client.authorization.call(order_no, amount, email)
+    transaction_id = auth_response["bfs_bfsTxnId"]
+    
+    puts "✅ Authorization successful!"
+    puts "   Transaction ID: #{transaction_id}"
+    puts "   Response Code: #{auth_response['bfs_responseCode']}"
+
+    # Step 2: Account Inquiry
+    puts "\n2️⃣  Verifying bank account..."
+    inquiry_response = client.account_inquiry.call(transaction_id, bank_id, account_no)
+    
+    puts "✅ Account verified!"
+    puts "   Account Holder: #{inquiry_response['bfs_remitterName']}"
+    puts "   Account Number: #{inquiry_response['bfs_remitterAccNo']}"
+    puts "   📱 OTP sent to registered mobile number"
+
+    # Step 3: Debit Request
+    puts "\n3️⃣  Completing payment with OTP..."
+    debit_response = client.debit_request.call(transaction_id, otp)
+    
+    puts "🎉 Payment completed successfully!"
+    puts "   Transaction ID: #{debit_response['bfs_bfsTxnId']}"
+    puts "   Amount Debited: #{debit_response['bfs_txnAmount']} BTN"
+    puts "   Order Number: #{debit_response['bfs_orderNo']}"
+    
+    return debit_response
+
+  rescue Rma::Payment::Gateway::InvalidParameterError => e
+    puts "❌ Invalid parameters: #{e.message}"
+  rescue Rma::Payment::Gateway::AuthenticationError => e
+    puts "❌ Authentication failed: #{e.message}"
+  rescue Rma::Payment::Gateway::NetworkError => e
+    puts "❌ Network error: #{e.message}"
+  rescue Rma::Payment::Gateway::Error => e
+    puts "❌ Payment failed: #{e.message}"
+  end
+end
+
+# Example usage
+if __FILE__ == $0
+  # Sample payment data
+  order_no = "ORDER#{Time.now.to_i}"
+  amount = 100.50
+  email = "customer@example.com"
+  bank_id = "1010"  # Bank of Bhutan
+  account_no = "12345678"
+  otp = "123456"  # In real scenario, customer provides this
+
+  result = process_payment(client, order_no, amount, email, bank_id, account_no, otp)
+  
+  if result
+    puts "\n🎊 Payment processing completed successfully!"
+  else
+    puts "\n💥 Payment processing failed!"
+  end
+end

data/examples/error_handling.rb

@@ -0,0 +1,251 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'rma/payment/gateway'
+
+# Configure the gateway
+Rma::Payment::Gateway.configure do |config|
+  config.base_url = ENV['RMA_BASE_URL'] || 'https://your-rma-gateway-url.com'
+  config.rsa_key_path = ENV['RMA_RSA_KEY_PATH'] || 'config/rma_private_key.pem'
+  config.beneficiary_id = ENV['RMA_BENEFICIARY_ID'] || 'your_beneficiary_id'
+  config.payment_description = ENV['RMA_PAYMENT_DESCRIPTION'] || 'Payment for services'
+end
+
+class PaymentProcessor
+  attr_reader :client, :logger
+
+  def initialize
+    @client = Rma::Payment::Gateway::Client.new
+    @logger = Logger.new(STDOUT)
+  end
+
+  def process_payment_with_comprehensive_error_handling(order_no, amount, email, bank_id, account_no, otp)
+    logger.info("Starting payment process for order: #{order_no}")
+
+    begin
+      # Step 1: Authorization with error handling
+      transaction_id = authorize_payment(order_no, amount, email)
+      return nil unless transaction_id
+
+      # Step 2: Account verification with error handling
+      account_verified = verify_account(transaction_id, bank_id, account_no)
+      return nil unless account_verified
+
+      # Step 3: Complete payment with error handling
+      complete_payment(transaction_id, otp)
+
+    rescue => e
+      logger.error("Unexpected error in payment process: #{e.message}")
+      logger.error(e.backtrace.join("\n"))
+      nil
+    end
+  end
+
+  private
+
+  def authorize_payment(order_no, amount, email)
+    logger.info("Authorizing payment...")
+    
+    response = client.authorization.call(order_no, amount, email)
+    transaction_id = response["bfs_bfsTxnId"]
+    
+    logger.info("Authorization successful: #{transaction_id}")
+    transaction_id
+
+  rescue Rma::Payment::Gateway::ConfigurationError => e
+    logger.error("Configuration error: #{e.message}")
+    logger.error("Please check your RMA gateway configuration")
+    notify_admin("Configuration Error", e)
+    nil
+
+  rescue Rma::Payment::Gateway::InvalidParameterError => e
+    logger.error("Invalid parameters: #{e.message}")
+    logger.error("Order: #{order_no}, Amount: #{amount}, Email: #{email}")
+    
+    # Provide specific feedback based on the error
+    if e.message.include?('email')
+      logger.error("Email validation failed")
+    elsif e.message.include?('amount')
+      logger.error("Amount validation failed")
+    end
+    nil
+
+  rescue Rma::Payment::Gateway::AuthenticationError => e
+    logger.error("Authentication failed: #{e.message}")
+    logger.error("Check your RSA key and beneficiary ID")
+    notify_admin("Authentication Error", e)
+    nil
+
+  rescue Rma::Payment::Gateway::NetworkError => e
+    logger.error("Network error during authorization: #{e.message}")
+    
+    # Implement retry logic for network errors
+    retry_authorization(order_no, amount, email, 3)
+
+  rescue Rma::Payment::Gateway::APIError => e
+    logger.error("API error during authorization: #{e.message}")
+    logger.error("Response code: #{e.response_code}")
+    
+    case e.response_code
+    when '02'
+      logger.error("Invalid beneficiary - contact RMA support")
+    when '99'
+      logger.error("System error - try again later")
+    end
+    nil
+
+  rescue Rma::Payment::Gateway::Error => e
+    logger.error("Gateway error during authorization: #{e.message}")
+    nil
+  end
+
+  def verify_account(transaction_id, bank_id, account_no)
+    logger.info("Verifying account...")
+    
+    response = client.account_inquiry.call(transaction_id, bank_id, account_no)
+    account_name = response["bfs_remitterName"]
+    
+    logger.info("Account verified: #{account_name}")
+    true
+
+  rescue Rma::Payment::Gateway::InvalidParameterError => e
+    logger.error("Invalid account details: #{e.message}")
+    
+    if e.message.include?('bank_id')
+      logger.error("Invalid bank code: #{bank_id}")
+    elsif e.message.include?('account_no')
+      logger.error("Invalid account number: #{account_no}")
+    end
+    false
+
+  rescue Rma::Payment::Gateway::APIError => e
+    logger.error("Account verification failed: #{e.message}")
+    
+    case e.response_code
+    when '03'
+      logger.error("Invalid transaction ID")
+    when '04'
+      logger.error("Account not found or inactive")
+    end
+    false
+
+  rescue Rma::Payment::Gateway::Error => e
+    logger.error("Error during account verification: #{e.message}")
+    false
+  end
+
+  def complete_payment(transaction_id, otp)
+    logger.info("Completing payment...")
+    
+    response = client.debit_request.call(transaction_id, otp)
+    
+    logger.info("Payment completed successfully!")
+    logger.info("Amount: #{response['bfs_txnAmount']} BTN")
+    response
+
+  rescue Rma::Payment::Gateway::APIError => e
+    logger.error("Payment completion failed: #{e.message}")
+    
+    case e.response_code
+    when '05'
+      logger.error("Invalid OTP provided")
+    when '06'
+      logger.error("OTP has expired - request new OTP")
+    when '04'
+      logger.error("Insufficient funds in account")
+    end
+    nil
+
+  rescue Rma::Payment::Gateway::Error => e
+    logger.error("Error during payment completion: #{e.message}")
+    nil
+  end
+
+  def retry_authorization(order_no, amount, email, max_retries)
+    retries = 0
+    
+    while retries < max_retries
+      retries += 1
+      sleep(2 ** retries) # Exponential backoff
+      
+      logger.info("Retrying authorization (attempt #{retries}/#{max_retries})...")
+      
+      begin
+        response = client.authorization.call(order_no, amount, email)
+        logger.info("Authorization successful on retry #{retries}")
+        return response["bfs_bfsTxnId"]
+      rescue Rma::Payment::Gateway::NetworkError => e
+        logger.warn("Retry #{retries} failed: #{e.message}")
+        next if retries < max_retries
+        logger.error("All retry attempts failed")
+      end
+    end
+    
+    nil
+  end
+
+  def notify_admin(error_type, exception)
+    # In a real application, you would send email, Slack notification, etc.
+    logger.error("ADMIN NOTIFICATION: #{error_type}")
+    logger.error("Exception: #{exception.class.name}")
+    logger.error("Message: #{exception.message}")
+    logger.error("Time: #{Time.current}")
+  end
+end
+
+# Example usage with comprehensive error handling
+if __FILE__ == $0
+  processor = PaymentProcessor.new
+  
+  # Test with various error scenarios
+  test_cases = [
+    {
+      name: "Valid Payment",
+      order_no: "ORDER#{Time.now.to_i}",
+      amount: 100.50,
+      email: "customer@example.com",
+      bank_id: "1010",
+      account_no: "12345678",
+      otp: "123456"
+    },
+    {
+      name: "Invalid Email",
+      order_no: "ORDER#{Time.now.to_i}",
+      amount: 100.50,
+      email: "invalid-email",
+      bank_id: "1010",
+      account_no: "12345678",
+      otp: "123456"
+    },
+    {
+      name: "Invalid Amount",
+      order_no: "ORDER#{Time.now.to_i}",
+      amount: -100,
+      email: "customer@example.com",
+      bank_id: "1010",
+      account_no: "12345678",
+      otp: "123456"
+    }
+  ]
+
+  test_cases.each do |test_case|
+    puts "\n" + "="*60
+    puts "Testing: #{test_case[:name]}"
+    puts "="*60
+    
+    result = processor.process_payment_with_comprehensive_error_handling(
+      test_case[:order_no],
+      test_case[:amount],
+      test_case[:email],
+      test_case[:bank_id],
+      test_case[:account_no],
+      test_case[:otp]
+    )
+    
+    if result
+      puts "✅ Test passed: Payment processed successfully"
+    else
+      puts "❌ Test failed: Payment processing failed"
+    end
+  end
+end

data/examples/rails_integration.rb

@@ -0,0 +1,171 @@
+# Example Rails integration
+
+# app/models/payment.rb
+class Payment < ApplicationRecord
+  belongs_to :order
+  belongs_to :user
+  
+  enum status: {
+    pending: 0,
+    authorized: 1,
+    account_verified: 2,
+    completed: 3,
+    failed: 4,
+    refunded: 5
+  }
+  
+  validates :order_id, presence: true
+  validates :amount, presence: true, numericality: { greater_than: 0 }
+  validates :transaction_id, uniqueness: true, allow_nil: true
+  
+  def rma_client
+    @rma_client ||= Rma::Payment::Gateway::Client.new
+  end
+  
+  def authorize!
+    response = rma_client.authorization.call(
+      order.order_number,
+      amount,
+      user.email
+    )
+    
+    update!(
+      transaction_id: response["bfs_bfsTxnId"],
+      status: :authorized,
+      authorized_at: Time.current
+    )
+    
+    response
+  end
+  
+  def verify_account!(bank_id, account_no)
+    response = rma_client.account_inquiry.call(
+      transaction_id,
+      bank_id,
+      account_no
+    )
+    
+    update!(
+      status: :account_verified,
+      account_holder_name: response["bfs_remitterName"],
+      verified_at: Time.current
+    )
+    
+    response
+  end
+  
+  def complete!(otp)
+    response = rma_client.debit_request.call(
+      transaction_id,
+      otp
+    )
+    
+    update!(
+      status: :completed,
+      completed_at: Time.current
+    )
+    
+    response
+  end
+end
+
+# app/services/rma_payment_service.rb
+class RmaPaymentService
+  attr_reader :payment, :errors
+
+  def initialize(payment)
+    @payment = payment
+    @errors = []
+  end
+
+  def process_authorization
+    payment.authorize!
+    true
+  rescue Rma::Payment::Gateway::Error => e
+    @errors << e.message
+    payment.update(status: :failed, error_message: e.message)
+    false
+  end
+
+  def process_account_verification(bank_id, account_no)
+    payment.verify_account!(bank_id, account_no)
+    true
+  rescue Rma::Payment::Gateway::Error => e
+    @errors << e.message
+    payment.update(status: :failed, error_message: e.message)
+    false
+  end
+
+  def process_completion(otp)
+    payment.complete!(otp)
+    true
+  rescue Rma::Payment::Gateway::Error => e
+    @errors << e.message
+    payment.update(status: :failed, error_message: e.message)
+    false
+  end
+end
+
+# app/controllers/payments_controller.rb
+class PaymentsController < ApplicationController
+  before_action :authenticate_user!
+  before_action :find_payment, except: [:create]
+
+  def create
+    @payment = current_user.payments.build(payment_params)
+    @payment.order = current_order
+    
+    if @payment.save
+      service = RmaPaymentService.new(@payment)
+      
+      if service.process_authorization
+        redirect_to account_verification_payment_path(@payment)
+      else
+        flash[:error] = service.errors.join(', ')
+        render :new
+      end
+    else
+      render :new
+    end
+  end
+
+  def account_verification
+    # Show form for bank details
+  end
+
+  def verify_account
+    service = RmaPaymentService.new(@payment)
+    
+    if service.process_account_verification(params[:bank_id], params[:account_no])
+      redirect_to otp_verification_payment_path(@payment)
+    else
+      flash[:error] = service.errors.join(', ')
+      render :account_verification
+    end
+  end
+
+  def otp_verification
+    # Show form for OTP
+  end
+
+  def complete
+    service = RmaPaymentService.new(@payment)
+    
+    if service.process_completion(params[:otp])
+      redirect_to payment_success_path(@payment)
+    else
+      flash[:error] = service.errors.join(', ')
+      render :otp_verification
+    end
+  end
+
+  private
+
+  def find_payment
+    @payment = current_user.payments.find(params[:id])
+  end
+
+  def payment_params
+    params.require(:payment).permit(:amount)
+  end
+end