liqpay 0.0.1 → 0.1.0

data/.gitignore

@@ -1,4 +1,5 @@
 *.gem
 .bundle
+.rvmrc
 Gemfile.lock
 pkg/*

data/README.md

@@ -1,3 +1,122 @@
 # LiqPAY
 
-This Ruby gem implements the [LiqPAY](http://liqpay.com) billing system API.
+This Ruby gem implements the [LiqPAY](http://liqpay.com) billing system.
+
+As of now it only covers the [Liq&Buy 1.2 API](https://liqpay.com/?do=pages&p=cnb12), which is used to accept credit card payments on your site.
+
+## Installation
+
+Include the [liqpay gem](https://rubygems.org/gems/liqpay) in your app.
+
+## Configuration
+
+The recommended way is setting the `Liqpay.default_options` hash somewhere in
+your initializers.
+
+You MUST supply the `merchant_id` and `merchant_signature` options, that are
+provided by LiqPAY when you sign up.
+
+## Processing payments through Liq&Buy
+
+### General flow
+
+1. User initiates the payment process; you redirect him to LiqPAY via POST, providing necessary parameters to set up the payment's amount and description
+
+2. Users completes payment through LiqPAY.
+
+3. LiqPAY redirects the user to the URL you specified.
+
+4. You validate the response against your secret signature.
+
+5. If the payment was successful: You process the payment on your side.
+
+6. If the payment was cancelled: You cancel the operation.
+
+So, LiqPAY is pretty simple, it does no server-to-server validation, just a
+browser-driven flow.
+
+### Implementation in Rails 
+
+0. Configure Liqpay:
+
+        # config/initializers/liqpay.rb
+        Liqpay.default_options[:merchant_id] = 'MY_MERCHANT_ID'
+        Liqpay.default_options[:merchant_signature] = 'MY_MERCHANT_SIGNATURE'
+
+1. Create a `Liqpay::Request` object
+
+    The required options are: the amount and currency of the payment, and an
+    "order ID". 
+    
+    The "order ID" is just a random string that you will use to
+    identify the payment after it has been completed. If you have an `Order`
+    model (I suggest that you should), pass its ID. If not, it can be a random
+    string stored in the session, or whatever, but *it must be unique*.
+
+        @liqpay_request = Liqpay::Request.new(
+          :amount => '999.99', 
+          :currency => 'UAH', 
+          :order_id => '123', 
+          :description => 'Some Product',
+          :result_url => liqpay_payment_url
+        )
+
+    **Note that this does not do anything permanent.** No saves to the database, no
+    requests to LiqPAY.
+    
+
+
+2. Put a payment button somewhere
+
+    As you need to make a POST request, there is definitely going to be a form somewhere. 
+
+    To output a form consisting of a single "Pay with LiqPAY" button, do
+
+        <%=liqpay_button @liqpay_request %>
+
+    Or:
+
+        <%=liqpay_button @liqpay_request, :title => "Pay now!" %>
+
+    Or:
+
+        <%=liqpay_button @liqpay_request do %>
+          <%=link_to 'Pay now!', '#', :onclick => 'document.forms[0].submit();' %>
+        <% end %>
+
+3. Set up a receiving endpoint.
+       
+        # config/routes.rb
+        post '/liqpay_payment' => 'payments#liqpay_payment'
+
+        # app/controllers/payments_controller.rb
+        class PaymentsController < ApplicationController
+          # Skipping forgery protection here is important
+          protect_from_forgery :except => :liqpay_payment
+
+          def liqpay_payment
+            @liqpay_response = Liqpay::Response.new(params)
+
+            if @liqpay_response.success?
+              # check that order_id is valid
+              # check that amount matches
+              # handle success
+            else
+              # handle error
+            end
+          rescue Liqpay::InvalidResponse
+            # handle error
+          end
+        end
+
+That's about it.
+
+### Security considerations
+
+* Check that amount from response matches the expected amount;
+* check that the order id is valid;
+* check that the order isn't completed yet (to avoid replay attacks); 
+
+- - -
+
+2012 Leonid Shevtsov

data/lib/liqpay.rb

@@ -2,9 +2,11 @@ require 'liqpay/version'
 require 'liqpay/request'
 require 'liqpay/response'
 
+require 'liqpay/railtie' if defined?(Rails)
+
 module Liqpay
-  API_VERSION = '1.2'
-  ENDPOINT_URL = 'https://www.liqpay.com/?do=clickNbuy'
+  LIQBUY_API_VERSION = '1.2'
+  LIQBUY_ENDPOINT_URL = 'https://www.liqpay.com/?do=clickNbuy'
   SUPPORTED_CURRENCIES = %w(UAH USD EUR RUR)
 
   @default_options = {}

data/lib/liqpay/liqpay_helper.rb

@@ -0,0 +1,26 @@
+module Liqpay
+  module LiqpayHelper
+    # Displays a form to send a payment request to LiqPay
+    #
+    # You can either pass in a block, that SHOULD render a submit button (or not, if you plan to submit the form otherwise), or
+    # let the helper create a simple submit button for you.
+    #
+    # liqpay_request - an instance of Liqpay::Request
+    # options - currently accepts two options
+    #   id - the ID of the form being created (`liqpay_form` by default)
+    #   title - text on the submit button (`Pay with LiqPay` by default); not used if you pass in a block
+    def liqpay_button(liqpay_request, options={}, &block)
+      id = options.fetch(:id, 'liqpay_form')
+      title = options.fetch(:title, 'Pay with LiqPAY')
+      content_tag(:form, :id => id, :action => Liqpay::LIQBUY_ENDPOINT_URL, :method => :post) do
+        result = hidden_field_tag(:operation_xml, liqpay_request.encoded_xml)+hidden_field_tag(:signature, liqpay_request.signature)
+        if block_given?
+          result += yield
+        else
+          result += submit_tag(title, :name => nil)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/liqpay/railtie.rb

@@ -0,0 +1,7 @@
+require 'liqpay/liqpay_helper'
+
+module Liqpay
+  class Railtie < Rails::Railtie
+    ActionView::Base.send :include, Liqpay::LiqpayHelper 
+  end
+end

data/lib/liqpay/request.rb

@@ -2,7 +2,31 @@ require 'base64'
 
 module Liqpay
   class Request < BaseOperation
-    attr_accessor :result_url, :server_url, :order_id, :amount, :currency, :description, :default_phone, :pay_way, :goods_id, :exp_time
+    # REQUIRED Amount of payment (Float), in :currency
+    attr_accessor :amount
+    # REQUIRED Currency of payment - one of `Liqpay::SUPPORTED_CURRENCIES`
+    attr_accessor :currency
+    # REQUIRED Arbitrary but unique ID
+    attr_accessor :order_id
+    # RECOMMENDED URL that the user will be redirected to after payment
+    attr_accessor :result_url
+    # RECOMMENDED URL that'll receive the order details in the background.
+    attr_accessor :server_url
+    # RECOMMENDED Description to be displayed to the user
+    attr_accessor :description
+    # Phone number to be suggested to the user
+    #
+    # LiqPAY requires users to provide a phone number before payment.
+    # If you know the user's phone number, you can provide it so he
+    # doesn't have to enter it manually.
+    attr_accessor :default_phone
+    # Method of payment. One or more (comma-separated) of:
+    #   card - by card
+    #   liqpay - by liqpay account
+    attr_accessor :pay_way
+
+    attr_accessor :exp_time
+    attr_accessor :goods_id
 
     def initialize(options={})
       super(options)
@@ -36,7 +60,7 @@ module Liqpay
       validate! unless @kamikaze
       Nokogiri::XML::Builder.new { |xml|
         xml.request {
-          xml.version Liqpay::API_VERSION
+          xml.version Liqpay::LIQBUY_API_VERSION
           xml.merchant_id merchant_id
           xml.result_url result_url
           xml.server_url server_url

data/lib/liqpay/response.rb

@@ -3,13 +3,33 @@ require 'nokogiri'
 
 module Liqpay
   class Response < BaseOperation
+    SUCCESS_STATUSES = %w(success wait_secure)
+
     attr_reader :encoded_xml, :signature, :xml
 
     ATTRIBUTES = %w(merchant_id order_id amount currency description status code transaction_id pay_way sender_phone goods_id pays_count)
-    ATTRIBUTES.each do |attr|
+    %w(merchant_id order_id amount currency description status code transaction_id pay_way sender_phone goods_id pays_count).each do |attr|
       attr_reader attr
     end
 
+    # Amount of payment. MUST match the requested amount
+    attr_reader :amount
+    # Currency of payment. MUST match the requested currency
+    attr_reader :currency
+    # Status of payment. One of '
+    #   failure 
+    #   success
+    #   wait_secure - success, but the card wasn't known to the system 
+    attr_reader :status
+    # Error code
+    attr_reader :code
+    # LiqPAY's internal transaction ID
+    attr_reader :transaction_id
+    # Chosen method of payment
+    attr_reader :pay_way
+    # Payer's phone
+    attr_reader :sender_phone
+
     def initialize(options = {})
       super(options)
 
@@ -19,6 +39,11 @@ module Liqpay
       decode!
     end
 
+    # Returns true, if the transaction was successful
+    def success?
+      SUCCESS_STATUSES.include? self.status
+    end
+
   private
     def decode!
       @xml = Base64.decode64(@encoded_xml)

data/lib/liqpay/version.rb

@@ -1,3 +1,3 @@
 module Liqpay
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/liqpay.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = Liqpay::VERSION
   s.authors     = ["Leonid Shevtsov"]
   s.email       = ["leonid@shevtsov.me"]
-  s.homepage    = "http://leonid.shevtsov.me/en/liqpay"
+  s.homepage    = "https://github.com/leonid-shevtsov/liqpay"
   s.summary     = %q{LiqPAY billing API implementation in Ruby}
   s.description = %q{LiqPAY billing API implementation in Ruby}
 

metadata

@@ -1,90 +1,74 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: liqpay
-version: !ruby/object:Gem::Version 
-  hash: 29
+version: !ruby/object:Gem::Version
+  version: 0.1.0
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 1
-  version: 0.0.1
 platform: ruby
-authors: 
+authors:
 - Leonid Shevtsov
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-03 00:00:00 +03:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: nokogiri
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70327090826000 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: *70327090826000
 description: LiqPAY billing API implementation in Ruby
-email: 
+email:
 - leonid@shevtsov.me
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - README.md
 - Rakefile
 - lib/liqpay.rb
 - lib/liqpay/base_operation.rb
+- lib/liqpay/liqpay_helper.rb
+- lib/liqpay/railtie.rb
 - lib/liqpay/request.rb
 - lib/liqpay/response.rb
 - lib/liqpay/version.rb
 - liqpay.gemspec
-has_rdoc: true
-homepage: http://leonid.shevtsov.me/en/liqpay
+homepage: https://github.com/leonid-shevtsov/liqpay
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 3173392958928029467
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 3173392958928029467
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: LiqPAY billing API implementation in Ruby
 test_files: []
-