= wepay-rails

Wepay-Rails allows your rails app to accept payments with Wepay (http://www.wepay.com).

To install it, add this to your Gemfile

    gem 'wepay-rails'

Since Wepay uses Oauth2 to authenticate, wepay-rails has been built to handle this for you. You will need to
add a column to one of your models to hold the authentication token. For example, if you have a user model:

Your migration:

    add_column :my_model, :wepay_auth_code, :string

You need to also create a new model called WepayCheckoutRecord. It will be updated by wepay's IPN system as changes to the checkout change - such as the status.
Wepay-rails handles those IPN notifications for you. You can write observers watching the WepayCheckoutRecord model if you need to have
something specific occur when the checkout changes.

To create your WepayCheckoutRecord model and migration:

    script/rails g wepay_rails:install

This will create 3 files for you, a migration file for a table to hold the checkout results, the model and a wepay.yml.example file. Next run:

    rake db:migrate

Modify config/wepay.yml.example to your needs. You will need to set the model and column where you are storing your wepay auth code:

Snippet of wepay.yml showing the auth_code_location directive:

    production:
      auth_code_location: MyModel.wepay_auth_code

You will have to set up a few new controllers in your rails app to handle callbacks and redirects from wepay.
I created one called finalize_controller and I use it for a landing page when the customer is finished paying
their order. The other controller I created is a checkout_controller - I send my customers to it when they click checkout
in the cart. Your app is surely differnt than mine. Do what makes sense to you.
For now, here's what I am doing in my rails app to handle it...

  app
    |_ controllers
                 |_ purchase
                        |_ checkout_controller.rb
                        |_ finalize_controller.rb

The wepay-rails gem comes with an IpnController already built in for
handling requests from wepay about a specific checkout. If you wish to override it,
you can create an IpnController in your rails app.

    class IpnController < Wepay::ApplicationController
        def index
            #Do something with the instant payment notifications back from Wepay
        end
    end

Finally, your checkout controller (or some controller that will interact with the Wepay API):

    class Purchase::CheckoutController < Purchase::PurchaseController
        before_filter :authenticate_account! # I am using devise - this line depends on your authentication scheme

        # PLEASE READ
        # I am saving the wepay_auth_code in my Profile model. Somewhere in my rails app, I have a method called
        # current_profile which I use to return the Profile object of my user. I pass that object through the
        # init_checkout_and_send_user_to_wepay method along with my checkout parameters.

        # After the customer is sent to wepay, when they are done paying you, they will be redirected
        # back to your application - you will set the location they will be redirected back to using the redirect_uri directive
        # either here - or in wepay.yml. Using it here overrides wepay.yml.

        def index

            cart = current_account.cart # EXAMPLE - get my shopping cart
            tx_id = cart.transaction_id # EXAMPLE - I use a column in my cart to have a way to look up the cart upon the user's return from wepay

            checkout_params = {
                :amount => cart.grand_total,
                :short_description => cart.short_description,
                :long_description => cart.long_description,
                :redirect_uri => purchase_finalize_index_url(:txID => tx_id) # Wepay redirects the user back to this url after purchase
            }

            # Finally, send the user off to wepay so you can get paid! - CASH MONEY
            init_checkout_and_send_user_to_wepay(checkout_params, current_profile)
        end
    end

The controller I use for finalizing the checkout - AKA - the controller the user is sent back to after his/her trip to
wepay to checkout.

    class Purchase::FinalizeController < Wepay::ApplicationController
      def index
        cart = Cart.find_by_transaction_id(params[:txID])
        wcr  = WepayCheckoutRecord.find_by_checkout_id(params[:checkout_id])

        checkout = wepay_gateway.lookup_checkout(wcr.checkout_id)
        wcr.update_attributes(checkout)

        # Convert cart to an order?? Move to observer of WepayCheckoutRecord??
        cart.convert_cart_to_order if wcr.state == 'authorized'

        render :text => wcr.inspect
      end
    end

Example Routes for these:
    namespace :purchase do
        resource :cart, :has_many => :purchase_items
        resources :checkout, :only => [:index]
        resources :finalize, :only => [:index]
    end


== Special Thanks to additional contributers of Wepay-Rails
* lucisferre (Chris Nicola) https://github.com/lucisferre


== Contributing to wepay-rails
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Adam Medeiros. See LICENSE.txt for
further details.