Peeves – PVS – Protx VSP Server

Introduction

Peeves is a library for accessing the Protx VSP Server. Its patterns are loosely modeled on ActiveMerchant, for clarity (unfortunately AM doesn’t support the VSP Server mode of operation). Peeves was built for an application called Woobius, but is released free of charge (and free of any warranties) to the community in the hope that it will be useful.

Using the Protx VSP Server enables you to not have to host payment pages on your own site. You initiate a transaction, then forward the user to the page returned by Protx, and the rest is handled off-site. This has many benefits, in particular not needing to implement credit card validation pages yourself, not needing to handle credit card numbers directly (which means that you’re automatically PCI-DSS compliant), and not needing to deal with 3D-secure yourself.

Protx is an UK payment gateway. You can find more information on their VPS Server service here.

Licence

The initial version of Peeves was written from scratch by Daniel Tenner. It is loosely based on ActiveMerchant’s patterns, but all code is original, and is licenced under the Apache Licence.

As a user, this means you can effectively use Peeves for whatever you want so long as you agree not to sue people about it.

As a contributor, it means that you licence to Peeves any contributions that you make as per the Apache licence.

Kicking the tyres

After setting up your IP address in the VSP Simulator, and obtaining a valid simulator vendor name, temporarily edit simulate.rb with your vendor name and run:

	ruby simulate.rb

Everything should work. If it doesn’t work, try asking me (swombat) for help on freenode, channel #flails.

Assuming everything worked fine, revert your change to simulate.rb.

Usage

Configuration

In each environment file, you want to do something like this:

	PEEVES_VENDOR           = "woobius"
	PEEVES_GATEWAY_MODE     = :simulator

The gateway mode can be set to :simulator, :test, or :live.

Then, in environment.rb, do:

	Peeves::Config.vendor 		= PEEVES_VENDOR
	Peeves::Config.gateway_mode = PEEVES_GATEWAY_MODE

Making a request

As per simulate.rb:

	transaction_reference = Peeves::UniqueId.generate("TEST")
	customer_data = Peeves::CustomerData.new(:surname => 'blah',
	                                         :firstnames => 'blah',
	                                         :address1 => 'blah',
	                                         :address2 => 'blah',
	                                         :city => 'blah',
	                                         :post_code => 'blah',
	                                         :country => 'gb',
	                                         :email => '[email protected]'
	                                        )

	# Payment registration
	payment_response = p.payment(Peeves::Money.new(1000, "GBP"),
	              {
	                :transaction_reference => transaction_reference,
	                :description           => "Test Transaction",
	                :notification_url      => "http://callback.example.com/process_stuff",
	                :customer_data         => { :billing  => customer_data,
	                                            :delivery => customer_data,
	                                            :email    => customer_data.email }
	              })

This will register a payment and return a url that you should forward the user to.

Once the user has made the payment on the Protx VSP Server pages, you will receive a callback at the URL you defined as :notification_url. You should call something like the following on the parameters that you receive back:

	def record_response_params(params)
    returning PeevesGateway.parse_notification(params) do |response|
      self.update_attributes(
        :last_status                          => response.status,
        :last_status_detail                   => response.last_status_detail,
        :vps_transaction_id                   => response.vps_transaction_id,
        :transaction_authorisation_number     => response.transaction_authorisation_number,
        :status_3d_secure                     => response.status_3d_secure,
        :code_3d_secure                       => response.code_3d_secure
      )
    end    
  end

In response to this, you must send back a success message or the transaction will eventually be cancelled by Protx:

	render :text => PeevesGateway.response(PeevesGateway::APPROVED, url, "Payment succeeded")

Protx will then forward the user to url, where you can display a happy success page.

Repeat transactions

Protx VSP Server wouldn’t be worth much without repeat transactions. Here’s an example of how to use them (this code sits on an Invoice class in Woobius):

  def pay_from(previous_invoice)
    response = PeevesGateway.new.repeat(Peeves::Money.new(self.currency_amount, self.currency),
      {
        :transaction_reference                    => self.reference,
        :description                              => self.description,
        :related_transaction_reference            => previous_invoice.reference,
        :related_vps_transaction_id               => previous_invoice.vps_transaction_id,
        :related_security_key                     => previous_invoice.security_key,
        :related_transaction_authorisation_number => previous_invoice.transaction_authorisation_number
      })
    self.update_attributes(
      :last_status              => response.status,
      :last_status_detail       => response.status_detail,
      :vps_transaction_id       => response.vps_transaction_id,
      :security_key             => response.security_key
    )
    if response.approved?
      self.paid!
    end

    response
  end

Keeping abreast of changes

Things might change. If you pull the latest version of Peeves and something doesn’t work, check the changelog: CHANGES.textile.

Contributing back

Please use the fork functionality on github to make a fork and then push back your changes to the fork queue. I will probably accept most useful changes, but it might take me a few days before I get around to it!

Thanks!