Merge pull request #10 from sparkplug/extend-functionality

Extend functionality

.coveralls.yml

@@ -0,0 +1 @@
+repo_token: bYVvifY6POXhFwOja3SZIX1nUxtWrUxKj

.rubocop.yml

@@ -5,10 +5,14 @@ Naming/FileName:
 Metrics/MethodLength: 
   Max: 25
 Metrics/BlockLength:
-  Max: 30
+  Max: 35
 Metrics/ParameterLists:
   Max: 8
 Lint/DuplicateMethods:
   Enabled: false
 Naming/AccessorMethodName:
+  Enabled: false
+Naming/PredicateName:
+  Enabled: false
+Style/AsciiComments:
   Enabled: false

Gemfile.lock

@@ -9,12 +9,20 @@ GEM
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
     coderay (1.1.2)
+    coveralls (0.8.23)
+      json (>= 1.8, < 3)
+      simplecov (~> 0.16.1)
+      term-ansicolor (~> 1.3)
+      thor (>= 0.19.4, < 2.0)
+      tins (~> 1.6)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
+    docile (1.3.2)
     faraday (1.0.0)
       multipart-post (>= 1.2, < 3)
     hashdiff (1.0.0)
+    json (2.3.0)
     method_source (0.9.2)
     multipart-post (2.1.1)
     pry (0.12.2)
@@ -36,6 +44,17 @@ GEM
       rspec-support (~> 3.9.0)
     rspec-support (3.9.2)
     safe_yaml (1.0.5)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    sync (0.5.0)
+    term-ansicolor (1.7.1)
+      tins (~> 1.0)
+    thor (1.0.1)
+    tins (1.24.1)
+      sync
     vcr (5.1.0)
     webmock (2.3.2)
       addressable (>= 2.3.6)
@@ -47,6 +66,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.0)
+  coveralls (~> 0.8.15)
   faraday
   momoapi-ruby!
   pry (~> 0.12)

README.md

@@ -1,7 +1,8 @@
 # MTN MoMo API Ruby Gem
 
 [![Build Status](https://travis-ci.com/sparkplug/momoapi-ruby.svg?branch=master)](https://travis-ci.com/sparkplug/momoapi-ruby)
-
+[![Coverage Status](https://coveralls.io/repos/github/sparkplug/momoapi-ruby/badge.svg?branch=master)](https://coveralls.io/github/sparkplug/momoapi-ruby?branch=master)
+[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/momo-api-developers/)
 
 ## Usage
 
@@ -43,14 +44,18 @@ Add the following configurations in an initializer file (for example, `config/in
 Momoapi.configure do |config|
   config.base_url = 'Your MoMo account base URL'
   config.callback_host = 'Your Provider Callback Host'
-  config.collection_primary_key = 'Your Collection Subscription Key'
-  config.collection_user_id = 'Your Collection User ID'
-  config.collection_api_secret = 'Your Collection API Key'
 end
 ```
 
 ## Collections
-The collections client can be created with the following paramaters. Note that the `COLLECTION_USER_ID` and `COLLECTION_API_SECRET` for production are provided on the MTN OVA dashboard;
+The collections client can be created with the following paramaters. Note that the `COLLECTION_USER_ID` and `COLLECTION_API_SECRET` for production are provided on the MTN OVA dashboard.
+
+Add the following to your configuration block:
+```
+  config.collection_primary_key = 'Your Collection Subscription Key'
+  config.collection_user_id = 'Your Collection User ID'
+  config.collection_api_secret = 'Your Collection API Key'
+```
 
 * `collection_primary_key`: Primary Key for the `Collection` product on the developer portal.
 * `collection_user_id`: For sandbox, use the one generated with the `momoapi-ruby` command.
@@ -77,9 +82,91 @@ collection = Momoapi::Collection.new
 require 'momoapi-ruby'
 
 collection = Momoapi::Collection.new
-collection.requestToPay(
+collection.request_to_pay(
     mobile="256772123456", amount="600", external_id="123456789", payee_note="dd", payer_message="dd", currency="EUR")
 ```
+An extra argument, `callback_url`, can be passed to this method, denoting the URL to the server where the callback should be sent.
+
+## Disbursements
+The disbursements client can be created with the following paramaters. The `DISBURSEMENT_USER_ID` and `DISBURSEMENT_API_SECRET` for production are provided on the MTN OVA dashboard.
+
+Add the following to your configuration block:
+```
+  config.disbursement_primary_key = 'Your Disbursement Subscription Key'
+  config.disbursement_user_id = 'Your Disbursement User ID'
+  config.disbursement_api_secret = 'Your Disbursement API Key'
+```
+
+* `disbursement_primary_key`: Primary Key for the `Disbursement` product on the developer portal.
+* `disbursement_user_id`: For sandbox, use the one generated with the `momoapi-ruby` command.
+* `disbursement_api_secret`: For sandbox, use the one generated with the `momoapi-ruby` command.
+
+You can create a disbursement client with the following:
+
+```ruby
+require 'momoapi-ruby'
+
+disbursement = Momoapi::Disbursement.new
+```
+
+### Methods
+1. `transfer`: Used to transfer an amount from the owner’s account to a payee account. Status of the transaction can be validated by using the `get_transaction_status` method.
+
+2. `get_transaction_status`: Retrieve transaction information using the `transaction_id` returned by `transfer`. You can invoke it at intervals until the transaction fails or succeeds. If the transaction has failed, it will throw an appropriate error. 
+
+3. `get_balance`: Get the balance of the account.
+
+### Sample Code
+
+```ruby
+require 'momoapi-ruby'
+
+disbursement = Momoapi::Disbursement.new
+disbursement.transfer(
+    mobile="256772123456", amount="600", external_id="123456789", payee_note="dd", payer_message="dd", currency="EUR")
+```
+An extra argument, `callback_url`, can be passed to this method, denoting the URL to the server where the callback should be sent.
+
+## Remittances
+The remittances client can be created with the following paramaters. The `REMITTANCES_USER_ID` and `REMITTANCES_API_SECRET` for production are provided on the MTN OVA dashboard.
+
+Add the following to your configuration block:
+```
+  config.remittance_primary_key = 'Your Remittance Subscription Key'
+  config.remittance_user_id = 'Your Remittance User ID'
+  config.remittance_api_secret = 'Your Remittance API Key'
+```
+
+* `remittance_primary_key`: Primary Key for the `Remittance` product on the developer portal.
+* `remittance_user_id`: For sandbox, use the one generated with the `momoapi-ruby` command.
+* `remittance_api_secret`: For sandbox, use the one generated with the `momoapi-ruby` command.
+
+You can create a remittance client with the following:
+
+```ruby
+require 'momoapi-ruby'
+
+remittance = Momoapi::Remittance.new
+```
+
+### Methods
+1. `transfer`: Used to transfer an amount from the owner’s account to a payee account. Status of the transaction can be validated by using the `get_transaction_status` method.
+
+2. `get_transaction_status`: Retrieve transaction information using the `transaction_id` returned by `transfer`. You can invoke it at intervals until the transaction fails or succeeds. If the transaction has failed, it will throw an appropriate error. 
+
+3. `get_balance`: Get the balance of the account.
+
+### Sample Code
+
+```ruby
+require 'momoapi-ruby'
+
+remittance = Momoapi::Remittance.new
+remittance.transfer(
+    mobile="256772123456", amount="600", external_id="123456789", payee_note="dd", payer_message="dd", currency="EUR")
+```
+An extra argument, `callback_url`, can be passed to this method, denoting the URL to the server where the callback should be sent.
+
 
 ## Contributing
 

lib/momoapi-ruby/cli.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# This is an executable file allowing a user to use the command line interface
+# to pass in a callback host url and a subscription key
+# and get back a generated user id and API key
+
 require 'faraday'
 require 'json'
 require 'securerandom'

lib/momoapi-ruby/client.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Base implementation of the MTN API client
+
+# Includes methods common to collections, disbursements and remittances
+
 require 'faraday'
 
 require 'momoapi-ruby/config'
@@ -23,8 +27,9 @@ def send_request(method, path, headers, *_body)
     end
 
     def interpret_response(resp)
+      body = resp.body.empty? ? '' : JSON.parse(resp.body)
       response = {
-        body: resp.body,
+        body: body,
         code: resp.status
       }
       unless resp.status >= 200 && resp.status < 300
@@ -37,6 +42,8 @@ def handle_error(response_body, response_code)
       raise Error::APIError.new(response_body, response_code)
     end
 
+    # Create an  access token which can then be used to
+    # authorize and authenticate towards the other end-points of the API
     def get_auth_token(path, subscription_key)
       headers = {
         "Ocp-Apim-Subscription-Key": subscription_key
@@ -55,7 +62,7 @@ def get_auth_token(path, subscription_key)
       end
     end
 
-    def get_balance(path, subscription_key)
+    def prepare_get_request(path, subscription_key)
       headers = {
         "X-Target-Environment": Momoapi.config.environment || 'sandbox',
         "Content-Type": 'application/json',
@@ -64,13 +71,19 @@ def get_balance(path, subscription_key)
       send_request('get', path, headers)
     end
 
+    # get the balance on an account
+    def get_balance(path, subscription_key)
+      prepare_get_request(path, subscription_key)
+    end
+
+    # retrieve transaction information, for transfer and payments
     def get_transaction_status(path, subscription_key)
-      headers = {
-        "X-Target-Environment": Momoapi.config.environment || 'sandbox',
-        "Content-Type": 'application/json',
-        "Ocp-Apim-Subscription-Key": subscription_key
-      }
-      send_request('get', path, headers)
+      prepare_get_request(path, subscription_key)
+    end
+
+    # check if an account holder is registered and active in the system
+    def is_user_active(path, subscription_key)
+      prepare_get_request(path, subscription_key)
     end
   end
 end

lib/momoapi-ruby/collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Implementation of the MTN API collections client
+
 require 'securerandom'
 
 require 'momoapi-ruby/config'
@@ -22,15 +24,26 @@ def get_transaction_status(transaction_id)
       super(path, Momoapi.config.collection_primary_key)
     end
 
+    # This method is used to request a payment from a consumer (Payer).
+    # The payer will be asked to authorize the payment. The transaction will
+    # be executed once the payer has authorized the payment.
+    # The requesttopay will be in status PENDING until the transaction
+    # is authorized or declined by the payer or it is timed out by the system.
+    # The status of the transaction can be validated
+    # by using `get_transation_status`
     def request_to_pay(phone_number, amount, external_id,
-                       payee_note = '', payer_message = '', currency = 'EUR')
+                       payee_note = '', payer_message = '',
+                       currency = 'EUR', **options)
       uuid = SecureRandom.uuid
       headers = {
         "X-Target-Environment": Momoapi.config.environment || 'sandbox',
         "Content-Type": 'application/json',
         "X-Reference-Id": uuid,
         "Ocp-Apim-Subscription-Key": Momoapi.config.collection_primary_key
       }
+      if options[:callback_url]
+        headers['X-Callback-Url'] = options[:callback_url]
+      end
       body = {
         "payer": {
           "partyIdType": 'MSISDN',
@@ -46,5 +59,10 @@ def request_to_pay(phone_number, amount, external_id,
       send_request('post', path, headers, body)
       { transaction_reference: uuid }
     end
+
+    def is_user_active(phone_number)
+      path = "/collection/v1_0/accountholder/msisdn/#{phone_number}/active"
+      super(path, Momoapi.config.collection_primary_key)
+    end
   end
 end

lib/momoapi-ruby/config.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Configurations are set up in this file
+# for a user's MTN MoMo API user credentials
+
 module Momoapi
   class Config
     attr_accessor :environment, :base_url,

lib/momoapi-ruby/disbursement.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Implementation of the MTN API disbursements client
+
 require 'momoapi-ruby/config'
 require 'momoapi-ruby/client'
 
@@ -20,15 +22,23 @@ def get_transaction_status(transaction_id)
       super(path, Momoapi.config.disbursement_primary_key)
     end
 
+    # The transfer operation is used to transfer an amount from the owner’s
+    # account to a payee account.
+    # The status of the transaction can be validated
+    # by using `get_transation_status`
     def transfer(phone_number, amount, external_id,
-                 payee_note = '', payer_message = '', currency = 'EUR')
+                 payee_note = '', payer_message = '',
+                 currency = 'EUR', **options)
       uuid = SecureRandom.uuid
       headers = {
         "X-Target-Environment": Momoapi.config.environment || 'sandbox',
         "Content-Type": 'application/json',
         "X-Reference-Id": uuid,
         "Ocp-Apim-Subscription-Key": Momoapi.config.disbursement_primary_key
       }
+      if options[:callback_url]
+        headers['X-Callback-Url'] = options[:callback_url]
+      end
       body = {
         "payer": {
           "partyIdType": 'MSISDN',
@@ -44,5 +54,10 @@ def transfer(phone_number, amount, external_id,
       send_request('post', path, headers, body)
       { transaction_reference: uuid }
     end
+
+    def is_user_active(phone_number)
+      path = "/disbursement/v1_0/accountholder/msisdn/#{phone_number}/active"
+      super(path, Momoapi.config.disbursement_primary_key)
+    end
   end
 end

lib/momoapi-ruby/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Error handling for unsuccessful responses from the MTN Momo API
+
 module Error
   class APIError < StandardError
     def initialize(message, code)