README.md in gopay-ruby-0.1.1 vs README.md in gopay-ruby-0.2.0
- old
+ new
@@ -1,37 +1,143 @@
# gopay-ruby
[](http://badge.fury.io/rb/gopay-ruby)
[](https://travis-ci.org/PrimeHammer/gopay-ruby)
-[](https://gemnasium.com/PrimeHammer/gopay-ruby)
[](https://codeclimate.com/github/PrimeHammer/gopay-ruby)
-[](https://coveralls.io/github/PrimeHammer/gopay-ruby?branch=master)
-Unofficial wrapper for GoPay REST API
+The GoPay Ruby allows Ruby applications to access to the GoPay REST API.
+## Benefits
+It does OAuth authorization under the hood automatically. Easy configuration through initializer.
+
## Installation
Add this line to your application's Gemfile:
```ruby
-gem 'gopay-ruby'
+gem 'gopay-ruby', require: 'gopay'
+
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install gopay-ruby
+## Configure
+The Gem is framework agnostic. However, if you use Rails, put the initializer in Rails config dir:
+```ruby
+config/initializers/gopay.rb
+```
+
+```ruby
+GoPay.configure do |config|
+ config.goid = GOPAY_ID
+ config.client_id = GOPAY_CLIENT_ID
+ config.client_secret = GOPAY_SECRET
+ config.return_host = RETURN_HOST_URL
+ config.notification_host = NOTIFICATION_HOST_URL
+ config.gate = GATE_URL
+end
+```
+
## Usage
-### Retrieve a payment
+### Create a Payment
+Before charging a user, we need to create a new payment. This will return a hash including a URL which you can use to popup payment modal or redirect the user to the GoPay payment page.
```ruby
-GoPay::Payment.retrieve 35345534
+GoPay::Payment.create payment_data
```
+
+### payment_data example
+
+```ruby
+{
+ "payer":{"allowed_payment_instruments": ["BANK_ACCOUNT"],
+ "contact":{"first_name": "John",
+ "last_name": "Doe",
+ "email": "john.doe@example.com"
+ }
+ },
+ "target":{"type": "ACCOUNT",
+ "goid": "8123456789"
+ },
+ "amount":"1000",
+ "currency":"CZK",
+ "order_number":"001",
+ "order_description":"description001",
+ "callback":{"return_url":"url.for.return",
+ "notification_url":"url.for.notification"
+ },
+ "lang":"en"
+}
+```
+
+### Create a Payment response example
+This is a basic example of response hash, for more complex examples visit [GoPay API docs](https://doc.gopay.com).
+```ruby
+{
+ "id":3000006529,
+ "order_number":"001",
+ "state":"CREATED",
+ "amount":1000,"currency":"CZK",
+ "payer":{"allowed_payment_instruments":["BANK_ACCOUNT"],
+ "contact": {"first_name":"John",
+ "last_name":"Doe",
+ "email":"john.doe@example.com",
+ }
+ },
+ "target":{"type":"ACCOUNT",
+ "goid":8123456789
+ },
+ "additional_params":[{"name":"invoicenumber",
+ "value":"2015001003"
+ }],
+ "lang":"en",
+ "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
+}
+```
+
+### Retrieve the Payment
+If you want to return a payment object from GoPay REST API.
+
+```ruby
+GoPay::Payment.retrieve gopay_id
+```
+
+### Refund of the payment
+This functionality allows you to refund payment paid by a customer.
+You can use the refund in two ways. First option is a full refund payment and the other one is a partial refund. Both based on `amount` parameter.
+
+```ruby
+GoPay::Payment.refund gopay_id, amount
+```
+
+### Cancellation of the recurring payment
+The functionality allows you to cancel recurrence of a previously created recurring payment.
+
+```ruby
+GoPay::Payment.void_recurrence gopay_id
+```
+
+## Dealing with errors
+Errors are raised as GoPay::Error. The error contains error code error body returned by GoPay API.
+You can easily catch errors in your models as shown below.
+
+```ruby
+begin
+ response = GoPay::Payment.refund(gopay_id, gopay_amount)
+rescue GoPay::Error => exception
+ log_gopay_error exception
+end
+```
+
+## Documentation
+Parameters for all GoPay methods follow the official documentation. For further explanation please visit [GoPay API docs](https://doc.gopay.com).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/PrimeHammer/gopay-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.