README.md in docdata-0.0.2 vs README.md in docdata-0.0.5
- old
+ new
@@ -1,15 +1,18 @@
# Docdata
[](http://travis-ci.org/henkm/docdata)
[](http://badge.fury.io/rb/docdata)
+[](https://gemnasium.com/henkm/docdata)
[](https://codeclimate.com/github/henkm/docdata)
[](https://coveralls.io/r/henkm/docdata)
-Docdata is a Ruby binder for Docdata Payments. Current status: **in progress, not stable**.
+Docdata is a Ruby implementation for using Docdata Payments.
-This gem relies on the awesom Savon gem to communicate with Docdata Payments' SOAP API.
+Here you can find the [Documentation](http://rdoc.info/gems/docdata)
+This gem relies on the awesom [Savon](http://savonrb.com/) gem to communicate with Docdata Payments' SOAP API.
+
## Installation
Add this line to your application's Gemfile:
gem 'docdata'
@@ -59,27 +62,31 @@
| Name | Type | Required |
|-----------|------------|---------|
| amount | Integer (amount in cents) | Yes |
| currency | String (ISO currency code) | Yes |
| order_reference | String (your own unique reference) | Yes |
+| description | String | No |
| profile | String (name of your Docdata Payment profile)| Yes |
| shopper | Docdata::Shopper | Yes |
| line_items | Array (of Docdata::LineItem objects) | No |
| bank_id | String | No |
| prefered_payment_method | String | No |
-| key | String (is availabel after successful 'create' action) | No (readonly)
+| default_act | Boolean (should consumer skip docdata page?) | No |
+| key | String (is available after successful 'create') | readonly |
+| url | String (redirect URI is available after 'create') | readonly |
## Default values
A quick warning about the default values for the Shopper object: **For some payment methods, Docdata Payments needs the actual information in order for the payment to take place.**
If you use `GIROPAY`, `SEPA` and `AFTERPAY` this is the case. (Maybe also in other payment methods, please let me know!)
## Example usage in Rails application
The example below assumes you have your application set up with a Order model, which contains the information needed for this transaction (amount, name, etc.).
+
```ruby
-# orders_controller.rb
+
def start_transaction
# find the order from your database
@order = Order.find(params[:id])
# initialize a shopper, use details from your order
@@ -104,21 +111,23 @@
redirect_to @payment.redirect_url
else
# TODO: Display the error and warn the user that something went wrong.
end
end
+
```
## Ideal
For transactions in the Netherlands, iDeal is the most common option. To redirect a user directly to the bank page (skipping the Docdata web menu page), you can ask your user to choose a bank from any of the banks listed in the `Docdata::Ideal.banks` method.
In `Docdata::Payment` you can set `bank_id` to any value. If you do, the redirect URI will redirect your user directly to the bank page.
Example code:
+
```ruby
-# orders_controller.rb
+
def ideal_checkout
@order = Order.find(params[:order_id])
@banks = Docdata::Ideal.banks
end
@@ -149,47 +158,54 @@
redirect_to @payment.redirect_url
else
# TODO: Display the error and warn the user that something went wrong.
end
end
+
```
View template (ideal_checkout.html.erb):
-```erb
+```html
+
<h2>Choose your bank</h2>
<%= form_tag start_ideal_transaction_path, method: :post, target: "_blank" do %>
<%= select_tag "bank_id", options_from_collection_for_select(@banks, "id", "name") %>
<%= hidden_field_tag :order_id, @order.id %>
<%= submit_tag "Proceed to checkout" %>
<% end %>
+
```
## Tips and samples
#### Redirect directly to bank page (skip Docdata web menu)
When making a new `Docdata::Payment`, use the `default_act` parameter to redirect consumers directly to the acquirers website. Example:
```ruby
- @payment = Docdata::Payment.new(
- amount: @order.total,
- currency: @order.currency,
- shopper: shopper,
- profile: "My Default Profile",
- order_reference: "order ##{@order.id}",
- bank_id: params[:bank_id],
- default_act: true # redirect directly to the bank, skipping the Docdata web menu
- )
+
+@payment = Docdata::Payment.new(
+ amount: @order.total,
+ currency: @order.currency,
+ shopper: shopper,
+ profile: "My Default Profile",
+ order_reference: "order ##{@order.id}",
+ bank_id: params[:bank_id],
+ default_act: true # redirect directly to the bank, skipping the Docdata web menu
+)
+
```
#### Retrieve a list of iDeal banks to show
`Docata::Ideal.banks` returns an Array.
## Contributing
+Want to contribute? Greate!
+
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Make changes, document them and add tests (rspec)
-4. Run the entire test suite and make sure all tests pass
+4. Run the entire test suite and make sure all tests pass (`rake`)
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Push to the branch (`git push origin my-new-feature`)
7. Create new Pull Request