Webirr

Official Ruby gem for WeBirr Payment Gateway APIs

This gem provides convenient access to WeBirr Payment Gateway APIs from Ruby Applications.

Installation

Add this line to your application's Gemfile:

gem 'webirr'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install webirr

Usage

The library needs to be configured with a merchant Id & API key. You can get it by contacting webirr.com

You can use this library for production or test environments. you will need to set is_test_env=true for test, and false for production apps when creating objects of class WeBirr::Client

Examples

Creating a new Bill / Updating an existing Bill on WeBirr Servers

require 'webirr/bill'
require 'webirr/webirr_client'

# Create & Update Bill
def create_bill
    api_key = 'YOUR_API_KEY'
    merchant_id = 'YOUR_MERCHANT_ID'

    # client to use test envionment
    webirr_client = WeBirr::Client.new(api_key, true)

    bill = Webirr::Bill.new
    bill.amount = "120.45"
    bill.customer_code = "C001" # it can be email address or phone number if you dont have customer code
    bill.customer_name = "Yohannes Aregay Hailu"
    bill.time = "2022-09-06 14:20:26" # your bill time, always in this format
    bill.description = "Food delivery"
    bill.bill_reference = "ruby/2022/001" # your unique reference number
    bill.merchant_id = merchant_id

    puts "\nCreating Bill..."

    res = webirr_client.create_bill(bill)

    if (res["error"].blank?)
        # success
        payment_code = res["res"]  # returns paymentcode such as 429 723 975
        puts "\nPayment Code = #{payment_code}" # we may want to save payment code in local db.
    else
        # fail
        puts "\nerror: #{res["error"]}"
        puts "\nerrorCode: #{res["errorCode"]}" # can be used to handle specific busines error such as ERROR_INVLAID_INPUT_DUP_REF
    end

    #pp res

    # Update existing bill if it is not paid
    bill.amount = "278.00"
    bill.customer_name = 'John ruby'
    #bill.bill_reference = "WE CAN NOT CHANGE THIS"

    puts "\nUpdating Bill..."

    res = webirr_client.update_bill(bill)

    if (res["error"].blank?)
        # success
        puts "\nbill is updated succesfully" #res.res will be 'OK'  no need to check here!
    else
        # fail
        puts "\nerror: #{res["error"]}"
        puts "\nerrorCode: #{res["errorCode"]}" # can be used to handle specific busines error such as ERROR_INVLAID_INPUT
    end
end

create_bill()

Getting Payment status of an existing Bill from WeBirr Servers

require 'webirr/bill'
require 'webirr/webirr_client'

# Get Payment Status of Bill
def get_webirr_payment_status
    api_key = 'YOUR_API_KEY'
    merchant_id = 'YOUR_MERCHANT_ID'

    # client to use test envionment
    webirr_client = WeBirr::Client.new(api_key, true)

    payment_code = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL'  # suchas as '141 263 782'

    puts "\nGetting Payment Status..."

    res = webirr_client.get_payment_status(payment_code)

    if (res["error"].blank?) 
        # success
        if (res["res"]["status"] == 2)
          data =  res["res"]["data"]
          puts "\nbill is paid"
          puts "\nbill payment detail"
          puts "\nBank: #{data["bankID"]}"
          puts "\nBank Reference Number: #{data["paymentReference"]}"
          puts "\nAmount Paid: #{data["amount"]}"
        else
          puts "\nbill is pending payment"
        end
    else
        # fail
        puts "\nerror: #{res["error"]}"
        puts "\nerrorCode: #{res["errorCode"]}" # can be used to handle specific busines error such as ERROR_INVLAID_INPUT
    end

    #pp res
end

get_webirr_payment_status()

Sample object returned from get_payment_status()

{
  error: null,
  res: {
    status: 2,
    data: {
      id: 111112347,
      paymentReference: '8G3303GHJN',      
      confirmed: true,
      confirmedTime: '2021-07-03 10:25:35',
      bankID: 'cbe_birr',
      time: '2021-07-03 10:25:33',
      amount: '4.60',
      wbcCode: '624 549 955'
    }
  },
  errorCode: null
}

Getting Payment status of an existing Bill from WeBirr Servers

require 'webirr/bill'
require 'webirr/webirr_client'

// Get Payment Status of Webirr::Bill
def get_webirr_payment_status
    api_key = 'YOUR_API_KEY'
    merchant_id = 'YOUR_MERCHANT_ID'

    webirr_client = WeBirr::Client.new(api_key, true)

    payment_code = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL'  // suchas as '141 263 782'

    puts "\nGetting Payment Status..."

    res = webirr_client.get_payment_status(payment_code)

    if (res["error"].blank?) 
        # success
        if (res["res"]["status"] == 2)
          data =  res["res"]["data"]
          puts "\nbill is paid"
          puts "\nbill payment detail"
          puts "\nBank: #{data["bankID"]}"
          puts "\nBank Reference Number: #{data["paymentReference"]}"
          puts "\nAmount Paid: #{data["amount"]}"
        else
          puts "\nbill is pending payment"
        end
    else
        # fail
        puts "\nerror: #{res["error"]}"
        puts "\nerrorCode: #{res["errorCode"]}" # can be used to handle specific busines error such as ERROR_INVLAID_INPUT
    end

    //pp res
end
get_webirr_payment_status()

Sample object returned from getPaymentStatus()

{
  error: null,
  res: {
    status: 2,
    data: {
      id: 111112347,
      paymentReference: '8G3303GHJN',      
      confirmed: true,
      confirmedTime: '2021-07-03 10:25:35',
      bankID: 'cbe_birr',
      time: '2021-07-03 10:25:33',
      amount: '4.60',
      wbcCode: '624 549 955'
    }
  },
  errorCode: null
}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/webirr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Webirr project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.