README.md in pesapal-0.0.3 vs README.md in pesapal-0.1.0
- old
+ new
@@ -12,16 +12,21 @@
order iframe. Everything else should be easy to do as the groundwork has already
been laid. If you are [feeling generous and want to contribute, feel free][9].
Submit [issues and requests here][6] and [find all the releases here][12].
-The gem should be [up on RubyGems.org][7] and it's [accompanying RubyDoc reference][13] here.
+The gem should be [up on RubyGems.org][7] and it's [accompanying RubyDoc reference here][13].
_Ps: No 3rd party oAuth library dependencies, it handles all the oAuth flows on
-it's own so it's light on your app._
+it's own so your app is one dependency less._
+_Ps 2: We are still at pre-release stage ... target is version 1.0.0 for a
+public release (suitable for production deployment with the basic functionality
+in place). As a result always check the documentation carefully on upgrades to
+mitigate breaking changes._
+
Installation
------------
Add this line to your application's Gemfile:
@@ -37,43 +42,73 @@
Usage
-----
+
### Setup ###
Initialize Pesapal object and choose the mode, there are two modes;
-`:development` and `:production`. They determine if you the code will interact
-with Pesapal for testing or for a live deployment.
+`:development` and `:production`. They determine if the code will interact
+with the testing or the live Pesapal API.
```ruby
# initiate pesapal object set to development mode
pesapal = Pesapal::Merchant.new(:development)
```
-Now set the Pesapal credentials. This assumes that you've chosen the appropriate
-credentials as they differ based on the mode chosen above (Pesapal provide the
-keys). Replace the placeholders below with your own credentials.
+You can set the configuration details from a YAML file at the location of
+your choice upon initialization as shown in the example below for a Rails app.
+The second parameter is optional and has a default value of
+`"#{Rails.root}/config/pesapal.yml"` if left out as in the example above.
```ruby
-# set pesapal api credentials
-pesapal.credentials = { :consumer_key => '<YOUR_CONSUMER_KEY>',
- :consumer_secret => '<YOUR_CONSUMER_SECRET>'
- }
+# initiate pesapal object set to development mode and use the YAML file found at
+# the specified location
+pesapal = Pesapal::Merchant.new(:development, "<PATH_TO_YAML_FILE>")
```
-By default the callback is set to `http://0.0.0.0:3000/pesapal/callback` on instantiation but you can easily set it to whatever works for you as shown below.
+And the YAML file should look something like this. Feel free to change to the
+appropriate values.
+```yaml
+development:
+ callback_url: 'http://0.0.0.0:3000/pesapal/callback'
+ consumer_key: '<YOUR_CONSUMER_KEY>'
+ consumer_secret: '<YOUR_CONSUMER_SECRET>'
+
+production:
+ callback_url: 'http://1.2.3.4:3000/pesapal/callback'
+ consumer_key: '<YOUR_CONSUMER_KEY>'
+ consumer_secret: '<YOUR_CONSUMER_SECRET>'
+```
+
+If the YAML file does not exist, then the object is set up with some bogus
+credentials which would not work anyway and therefore, the next logical step is
+that you set them yourself. Which, you can do using a hash as shown below
+(please note that Pesapal provides different keys for different modes and since
+this is like an override, there's the assumption that you chose the right one).
+
```ruby
-pesapal.callback_url = 'WHATEVER_URL_YOU_WANT'
+# set pesapal api configuration manually (override YAML & bogus credentials)
+pesapal.config = { :callback_url => 'http://0.0.0.0:3000/pesapal/callback'
+ :consumer_key => '<YOUR_CONSUMER_KEY>',
+ :consumer_secret => '<YOUR_CONSUMER_SECRET>'
+ }
```
+_Ps: Make sure this hash has the appropriate values before running any methods
+that interact with the API as the methods pick from these values. This means
+that you can also override them at runtime for a truly dynamic/complex app that
+might have different values for different scenarios._
+
+
### Post Order ###
-Once you've set up the credentials, set up the order details in a hash as shown
-in the example below ... all keys **MUST** be present. If there's one that you
-wish to ignore just leave it with a blank string but make sure it's included
+Once you've finalized the configuration, set up the order details in a hash as
+shown in the example below ... all keys **MUST** be present. If there's one that
+you wish to ignore just leave it with a blank string but make sure it's included
e.g. the phonenumber.
```ruby
#set order details
pesapal.order_details = { :amount => 1000,
@@ -87,37 +122,48 @@
}
```
Then generate the transaction url as below. In the example, the value is
assigned to the variable `order_url` which you can pass on to the templating
-system of your to generate an iframe.
+system of your choice to generate an iframe. Please note that this method
+utilizes all that information set in the previous steps in generating the url so
+it's important that it's the last step in the post order process.
```ruby
# generate transaction url
order_url = pesapal.generate_order_url
+
+# order_url will a string with the url example;
+# http://demo.pesapal.com/API/PostPesapalDirectOrderV4?oauth_callback=http%3A%2F%2F1.2.3.4%3A3000%2Fpesapal%2Fcallback&oauth_consumer_key=A9MXocJiHK1P4w0M%2F%2FYzxgIVMX557Jt4&oauth_nonce=13804335543pDXs4q3djsy&oauth_signature=BMmLR0AVInfoBI9D4C38YDA9eSM%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1380433554&oauth_version=1.0&pesapal_request_data=%26lt%3B%3Fxml%20version%3D%26quot%3B1.0%26quot%3B%20encoding%3D%26quot%3Butf-8%26quot%3B%3F%26gt%3B%26lt%3BPesapalDirectOrderInfo%20xmlns%3Axsi%3D%26quot%3Bhttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%26quot%3B%20xmlns%3Axsd%3D%26quot%3Bhttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%26quot%3B%20Amount%3D%26quot%3B1000%26quot%3B%20Description%3D%26quot%3Bthis%20is%20the%20transaction%20description%26quot%3B%20Type%3D%26quot%3BMERCHANT%26quot%3B%20Reference%3D%26quot%3B808%26quot%3B%20FirstName%3D%26quot%3BSwaleh%26quot%3B%20LastName%3D%26quot%3BMdoe%26quot%3B%20Email%3D%26quot%3Bj%40kingori.co%26quot%3B%20PhoneNumber%3D%26quot%3B%2B254722222222%26quot%3B%20xmlns%3D%26quot%3Bhttp%3A%2F%2Fwww.pesapal.com%26quot%3B%20%2F%26gt%3B
```
+_Ps: Please note the `:callback_url` value in the `pesapal.config` hash ...
+after the user successfully posts the order, the response will be sent to this
+url. Refer to [official Pesapal Step-By-Step integration guide][18] for more
+details._
+
Contributing
------------
-1. [Fork it][8]
-2. Create your feature branch (`git checkout -b wip-my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature with awesome'`)
-4. Push to the branch (`git push origin wip-my-new-feature`)
-5. Create new pull request
+1. Make sure you've read the [M.O. ★][14] ([blog article here][16])
+2. Especially [the part about my conventions when writing and merging new features][15]
+2. [Fork it][8]
+2. Create your feature branch (`git checkout -b BRANCH_NAME`)
+3. Commit your changes (`git commit -am 'AWESOME COMMIT MESSAGE'`)
+4. Push to the branch (`git push origin BRANCH_NAME`)
+5. Create new pull request and we can [have the conversations here][17]
-_Ps: Please prefix branch name with 'wip-' ... means 'work in progress'._
-
References
----------
* [oAuth 1.0 Spec][1]
* [Developing a RubyGem using Bundler][2]
* [Make your own gem][3]
* [Pesapal API Reference (Official)][4]
+* [Pesapal Step-By-Step Reference (Official)][18]
* [Pesapal PHP API Reference (Unofficial)][5]
License
-------
@@ -137,5 +183,10 @@
[9]: https://github.com/itsmrwave/pesapal-rubygem#contributing
[10]: http://kingori.co/
[11]: https://github.com/itsmrwave/pesapal-rubygem/blob/master/LICENSE.txt
[12]: https://github.com/itsmrwave/pesapal-rubygem/releases/
[13]: http://rubydoc.info/gems/pesapal/
+[14]: https://github.com/itsmrwave/mo
+[15]: https://github.com/itsmrwave/mo/tree/master/convention#-convention
+[16]: http://kingori.co/articles/2013/09/modus-operandi/
+[17]: https://github.com/itsmrwave/pesapal-rubygem/pulls
+[18]: http://developer.pesapal.com/how-to-integrate/step-by-step