Mpayer

A ruby client that makes it easy to integrate to Mpayer payment gateway. It allows for railsesque way of interacting with Mpayer objects. Is compatible currently with Mpayer version 1

Installation

Add this line to your application's Gemfile:

gem requires ruby ~>2.0

gem 'mpayer_ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mpayer_ruby

Usage

First thing is to get the credentials of an Mpayer teller. This are the stored as environment variables. Add the following to your ~/.bash_profile file or wherever else you load ENV variables

export MPAYER_USER=<Your User name>
export MPAYER_TOKEN=<Your token>

Configurations

To configure credentials for your API calls on you code use config block below. For Rails, put this in config/initializers/mpayer.rb

Mpayer.setup do |config|
    config.user_no = <Your User name>
    config.token = <Your token>
end

Versioning is not currently supported.

Quick Example

require "rubygems"
require "mpayer_ruby"

Mpayer.setup do |config|
    config.user_no = <USER>
    config.token = <TOKEN>
end

#Get all clients in your organisation
clients = Mpayer::Client.all(page:1,per_page:100)

#Get one client in your organisation
clients = Mpayer::Client.find(123)

#Instantiate without http call, obviously if you know that the client exists
clients = Mpayer::Client.find(123, fetch:false)

Endpoints

Mpayer gem currently supports a few endpoint below

https://app.mpayer.co.ke/api/login

https://app.mpayer.co.ke/api/client

https://app.mpayer.co.ke/api/accounts

https://app.mpayer.co.ke/api/transactions

https://app.mpayer.co.ke/api/payables

All responses are objects and can be accessed with dot notation e.g

clients = Mpayer::Client.all(page:1,per_page:100) 
client = client.first
client.name #=> "CLark Kent"

Login

Login provides your organisations settings and credentials.

login = Mpayer.login 
# defaults are picked from user:ENV['MPAYER_USER'],password:ENV['MPAYER_PASSWORD']

login = Mpayer.login(user:'james@bond.com', password: "bond..james bond")

Client

clients = Mpayer::Client.all

client = Mpayer::Client.find(id)  #Instantiates and hits the api
client = Mpayer::Client.find(id, fetch:false) #Instantiates only

client_attributes = {client: { client_name: "Kiki Lolo", client_birthday: Time.zone.now.iso8601, client_type: "ext", ac_type: "cu",client_mobile: '0733222222', client_email: 'lolo@kiki.com',currency: "kes", mandate:"s", sub_type: "od" }}
client = Mpayer::Client.create(client_attributes)

client = Mpayer::Client.find(20284,fetch:false).account(account_id) # Get clients account with id
client = Mpayer::Client.find(20284,fetch:false)
account = client.account(account_id) # Get clients account with id

client_accounts = Mpayer::Client.find(20284,fetch:false).accounts(page:1,per_page:100)
client_payables = Mpayer::Client.find(20284,fetch:false).payables(page:1,per_page:100)
client_transactions = Mpayer::Client.find(20284,fetch:false).transactions(account_id, page:1,per_page:100)

Account

accounts = Mpayer::Account.all
account = Mpayer::Account.find(1) #Instantiates and hits the api
account = Mpayer::Account.find(1, fetch:false) #Instantiates only

account = Mpayer::Account.find(1, fetch:false)
account.update(name:'Lolo Kiki')

options = {from_date: Time.zone.now -  (86400*365),to_date:nil, dr_cr:nil, ac_type:nil, category:nil}
accounts = Mpayer::Account.aggregates(options)

members = Mpayer::Account.find(25735, fetch:false).members

payable_items = Mpayer::Account.find(25735, fetch:false).payable_items

Payable

payables = Mpayer::Payable.all
payable = Mpayer::Payable.find(id) #Instantiates and hits the api
payable = Mpayer::Payable.find(id,fetch:false) #Instantiates only

Mpayer::Payable.where(ref_id:"Ksdfsfsdf000411") #Search for payable. only ref_id supported currently

payable_items = []
[*0..5].each do |n|
    payable_items << {
        payment_party: 'pz_test' ,
        terminal_ac: 'pz_test2' ,
        details: "paying to test account" ,
        amount: 10,
        price: 10,
        unit_measure: 1.0
    }
end
options = {
    payment: {
        payable_no: rand(10000), 
        note: "payable to pay something",
        ref_id:rand(10000),
        client_id: client_id, 
        status: status,
        payable_type: payable_type,
        due_date: Time.zone.now+(86400*31), 
        pay: payable_items,
        tags: tags,
        flags: flags,
        infos: infos ,
        sync_lag:sync_lag
    }
}
payable = Mpayer::Payable.create(options)

payable = Mpayer::Payable.find(8818,fetch:false)
payable.destroy# Delete a payable

Transactions

# Note: cr_party is the recieving (credited) account while dr_party is paying (debited) account

transactions = Mpayer::Transaction.all(from: Time.zone.now -  (86400*400))

transaction = Mpayer::Transaction.where(ref_id:"KT00410000402")# Only ref_id supported currently

body = {particulars:"particulars",amount:1000, cr_party: "account_alias"}
deposit = Mpayer::Transaction.deposit(body)

body = {particulars:"particulars",amount:10, dr_party: "01202320320"}
withdrawal = Mpayer::Transaction.withdraw(body)

body = {particulars:"particulars",amount:10, cr_party: "02304304", dr_party:"alias" }
transfer = Mpayer::Transaction.transfer(body)

Fetch

# Used to interact with https://app.mpayer.co.ke/api

Mpayer.setup do |config|
    config.user_no = 'GLOBAL_USER'
    config.token = 'GLOBAL_TOKEN'
end

url = "/clients/all_clients"
Mpayer::Fetch.get(url,query:{page:page,per_page:per_page})
Mpayer::Fetch.post(url,{client:{name:'Kiki Lolo'}})
Mpayer::Fetch.put(url,{client:{name:'Kiki Lolo'}})
Mpayer::Fetch.delete(url)

Development

After checking out the repo, run bin/setup to install dependencies. Then, 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 to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Testing

mpayer_ruby has used webmock gem to stub out real request to mpayer.co.ke. In order to make tests work, first generate the json api on file using the rake task

$ rake load:mpayer

This will generate local copies of mpayer endpoints for testing. Should work well for unit testing.

WHen you want to run test against real mpayer.co.ke for real responses, run it with the environmental variable CI_TEST=ON as follows

$ CI_TEST=ON rake test

or

$ CI_TEST=ON bundle exec guard

Todo

1. Add Webmock for faster / localised test or sinatra app method
2. Add versioning

Contributing

1. Fork it ( https://github.com/[my-github-username]/mpayer/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request