README

Worldpay HTML Redirect Rails Plugin
===================================

Copyright (c) 2008 Paul Springett [http://paulspringett.name], released under the MIT license

This plugin helps in creating the HTML form for submitting payment information to WorldPay and includes methods for easily handling the callback response from WorldPay

When in development mode payments are submitted to the test page (and the testMode=100 POST parameter is added to the form). In production mode, requests are sent to the live payment page

TODO
====

* Custom notification URL
* FuturePay Support

Example
=======

CREATING FORM HTML

# in app/views/order_controller.rb

def new
	# save order in your own way
	@order = Order.new(@cart, session[:person], session[:address], session[:country])
	@order.save
	
	# set options for submitting to WorldPay
	@options = {
	  :desc => "Store Purchase", 					 # default is purchase
	  :currency => "USD", 										 # default is GBP
	  :name => "#{ @order.name }",								 # person's name
	  :address => "#{ @order.address.describe_for_worldpay }",	 # billing address without zip/postcode
	  :postcode => "#{ @order.address.postal_code }",			 # billing address's zip/postcode
	  :country => "#{ @order.country_code }",					 # 2 letter country code, eg US or GB
	  :tel => "#{ @order.telephone }",							 # contact telephone
	  :email => "#{ @order.email_address }"						 # email address
	}
	
end

# in app/views/order/new.html.erb

<% world_pay_form_tag(123456, @order.id, @order.total, @options) do %>
	<%= submit_tag 'Pay with Worldpay' %>
<% end %>

# these parameters are handled as follows:

# in vendor/plugins/world_pay/lib/world_pay.rb
# Paypal::Helpers

def world_pay_form(installation_id, order_ref, amount, options = {})

	# installation_id is the installation ID from your worldpay environment
	# order_ref stores the order number - this is passed back by WorldPay in the payment response callback
	# amount is the money to charge (as a float) (you can set currency as :currency => "XYZ" in the options hash)
	# options - additional details to send to WorldPay
	
end

HANDLING PAYMENT NOTIFICATION RESPONSE

# in app/controllers/transaction_controller.rb

class TransactionController < ApplicationController
  
  # stop rails from throwing exception
  skip_before_filter :verify_authenticity_token
  
  def notify_from_worldpay
    
	# parse response parameters into new WorldPay::Response object
    notification = WorldPay::Response.new(params, request.raw_post)

	# find the relevant order from the db
    order = Order.find(notification.order_ref)
    
    # validate callback by password from wp admin and valid order ref
	# callback password can be set in the WorldPay admin system
    if notification.is_authorized_by_callback_password?('password') and order
      
      # check payment response is valid
	  # and transaction was successful
      if notification.success?
        
        if notification.currencies_match?('USD')
		  # order is valid and has been paid for
          unless notification.amounts_match?(order.total)
			# order amount and amount paid for didn't match
          end
        else
         	# payment received in different currency than expected
        end
        
        # save order
		# deliver confirmation email to customer
        # increment discount uses for order
        
      end # success?
      
    end # is_authorized_by_callback_password

    render :nothing => true
    
  end
  
end

Copyright (c) 2008 Paul Springett [http://paulspringett.name], released under the MIT license