Class: Zaypay::PriceSetting

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/zaypay/price_setting.rb

Overview

PriceSetting instances allows you to communicate to the Zaypay platform.

It is basically a Ruby wrapper for the Zaypay-API, which provides you a bunch of payment-related methods, as well as some utility methods.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(price_setting_id = nil, api_key = nil) ⇒ PriceSetting

Creates instances of Zaypay::PriceSetting.

To instantiate, one must provide a PriceSetting-id and its API-Key. You can obtain these information once you have created a PriceSetting on the Zaypay platform (www.zaypay.com).

You can also call the “one-arg” or the “no-args” version of the initializer, but to do that, you must first create config/zaypay.yml in your Rails app, see the README file.

Parameters:

  • price_setting_id (Integer) (defaults to: nil) —

    your PriceSetting’s id

  • api_key (String) (defaults to: nil) —

    your PriceSetting’s api-key



25
26
27
28
 
# File 'lib/zaypay/price_setting.rb', line 25

def initialize(price_setting_id=nil, api_key=nil)
  @price_setting_id, @api_key = price_setting_id, api_key
  select_settings
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, url, extra_query_string = {}) ⇒ Object (protected) 



221
222
223
224
225
226
227
228
229
 
# File 'lib/zaypay/price_setting.rb', line 221

def method_missing(method, url, extra_query_string={})
  super unless [:get, :post, :put, :delete].include?(method)
  response = self.class.send(method, ('https://secure.zaypay.com' + url), {:query => default_query.merge!(extra_query_string), 
                                                                          :headers => {'Accept' => 'application/xml' } })
  
  Zaypay::Util.uber_symbolize(response)
  check response
  block_given? ? yield(response[:response]) : response[:response]
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



9
10
11
 
# File 'lib/zaypay/price_setting.rb', line 9

def api_key
  @api_key
end

#locale ⇒ Object

Returns the value of attribute locale.



10
11
12
 
# File 'lib/zaypay/price_setting.rb', line 10

def locale
  @locale
end

#payment_method_id ⇒ Object

Returns the value of attribute payment_method_id.



10
11
12
 
# File 'lib/zaypay/price_setting.rb', line 10

def payment_method_id
  @payment_method_id
end

#price_setting_id ⇒ Object (readonly)

Returns the value of attribute price_setting_id.



9
10
11
 
# File 'lib/zaypay/price_setting.rb', line 9

def price_setting_id
  @price_setting_id
end

Instance Method Details

#country_has_been_configured_for_ip(ip, options = {}) ⇒ Hash

Returns a country as a Hash, if the country of the given IP has been configured for your Price Setting.

If the country of the given IP has been configured for this Price Setting, it returns a hash with :country and :locale subhashes, else it returns nil.

Parameters:

  • ip (String) —

    an ip-address (e.g. from your site’s visitors)

Returns:

  • (Hash) —

    a hash containing :country and :locale subhashes



89
90
91
92
93
94
 
# File 'lib/zaypay/price_setting.rb', line 89

def country_has_been_configured_for_ip(ip, options={})
  # options can take a :amount key
  locale  = locale_for_ip(ip)
  country = list_countries(options).select{ |c| c.has_value? locale[:country] }.first
  {:country => country, :locale => locale} if country
end

#create_payment(options = {}) ⇒ Hash

Creates a payment on the Zaypay platform.

You can provide an options-hash, which will add additional data to your payment. The following keys have special functionalities:

:amount        # Enables dynamic pricing. It must be an integer representing the price in cents.
:payalogue_id  # Adds the URL of the payalogue specified to your payment as :payalogue_url.

Any other keys will be added to a key named :your_variables, which can be used for your future reference. Please check the README for the structure of the payment returned.

Example: 

@price_setting.create_payment(:payalogue_id => payalogue_id, :amount => optional_amount, :my_variable_1 => "value_1", :my_variable_2 => "value_2")

Parameters:

  • options (Hash) (defaults to: {}) —

    an options-hash that can take an :amount, :payalogue_id as options, and any other keys can be used as your custom variables for your own reference

Returns:

  • (Hash) —

    a hash containing data of the payment you just created

Raises:

  • (Zaypay::Error) —

    in case you call this method before setting a locale or a payment_method_id



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/zaypay/price_setting.rb', line 154

def create_payment(options={})
  raise Zaypay::Error.new(:locale_not_set, "locale was not set for your price setting") if @locale.nil?
  raise Zaypay::Error.new(:payment_method_id_not_set, "payment_method_id was not set for your price setting") if @payment_method_id.nil?
  query = {:payment_method_id => payment_method_id}
  query.merge!(options)
  amount = query.delete(:amount)
  post "/#{amount}/#{@locale}/pay/#{price_setting_id}/payments", query do |data|
    payment_hash data
  end
end

#list_countries(options = {}) ⇒ Array

Returns an array of countries that are available to your Price Setting.

Parameters:

  • options (Hash) (defaults to: {}) —

    an options-hash that can take an :amount option, in case you want to use dynamic pricing

Returns:

  • (Array) —

    an array of countries, each represented by a hash with :code and :name



111
112
113
114
115
 
# File 'lib/zaypay/price_setting.rb', line 111

def list_countries(options={})
  get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
    Zaypay::Util.arrayify_if_not_an_array(data[:countries][:country])
  end
end

#list_languages(options = {}) ⇒ Array

Returns an array of languages that are available to your Price Setting.

Parameters:

  • options (Hash) (defaults to: {}) —

    an options-hash that can take an :amount option, in case you want to use dynamic pricing

Returns:

  • (Array) —

    an array of languages, each represented by a hash with :code, :english_name, :native_name



121
122
123
124
125
 
# File 'lib/zaypay/price_setting.rb', line 121

def list_languages(options={})
  get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
    data[:languages][:language]
  end
end

#list_locales(options = {}) ⇒ Hash

Returns a hash containing the countries and languages that are available to your Price Setting.

Parameters:

  • options (Hash) (defaults to: {}) —

    an options-hash that can take an :amount option, in case you want to use dynamic amounts

Returns:

  • (Hash) —

    a hash containing subhashes of countries and languages



100
101
102
103
104
105
 
# File 'lib/zaypay/price_setting.rb', line 100

def list_locales(options={})
  get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
    {:countries => Zaypay::Util.arrayify_if_not_an_array(data[:countries][:country]),
     :languages => data[:languages][:language]}
  end
end

#list_payment_methods(options = {}) ⇒ Array

Returns an array of payment methods that are available to your Price Setting with a given locale

Parameters:

  • options (Hash) (defaults to: {}) —

    an options-hash that can take an :amount option, in case you want to use dynamic amounts

Returns:

  • (Array) —

    an array of payment methods, each represented by a hash.

Raises:

  • (Zaypay::Error) —

    in case you call this method before setting a locale



132
133
134
135
136
137
 
# File 'lib/zaypay/price_setting.rb', line 132

def list_payment_methods(options={})
  raise Zaypay::Error.new(:locale_not_set, "locale was not set for your price setting") if @locale.nil?
  get "/#{options[:amount]}/#{@locale}/pay/#{price_setting_id}/payments/new" do |data|
    Zaypay::Util.arrayify_if_not_an_array(data[:payment_methods][:payment_method])
  end
end

#locale_for_ip(ip) ⇒ Hash

Returns the default locale as a hash for a given ip_address.

It is similar to #locale_string_for_ip, except that this method returns the locale as a hash This method comes in handy when you want to preselect only the langauge or the country for your customer

Example: 

# We take an ip-address from Great Britain for example:
ip = "212.58.226.75"
@price_setting.locale_string_for_ip(ip)
=> { :country => 'GB', :language => 'en' }

Parameters:

  • ip (String) —

    an ip-address (e.g. from your site’s visitors)

Returns:

  • (Hash) —

    a hash with :country and :language as keys



76
77
78
79
80
81
 
# File 'lib/zaypay/price_setting.rb', line 76

def locale_for_ip(ip)
  get "/#{ip}/pay/#{price_setting_id}/locale_for_ip" do |data|
    parts = data[:locale].split('-')
    {:country => parts[1], :language => parts[0]}
  end
end

#locale_string_for_ip(ip) ⇒ String

Returns the default locale as a string for a given ip_address, with the first part representing the language, the second part the country

This method comes in handy when you want to preselect the language and country when your customer creates a payment on your website.

Example: 

# We take an ip-address from Great Britain for example:
ip = "212.58.226.75"
@price_setting.locale_string_for_ip(ip)
=> 'en-GB'

Also see #locale_for_ip

Parameters:

  • ip (String) —

    an ip-address (e.g. from your site’s visitors)

Returns:

  • (String) —

    a string that represents the default locale for the given IP, in a language-country format.



56
57
58
59
60
61
 
# File 'lib/zaypay/price_setting.rb', line 56

def locale_string_for_ip(ip)
  get "/#{ip}/pay/#{price_setting_id}/locale_for_ip" do |data|
    parts = data[:locale].split('-')
    Zaypay::Util.stringify_locale_hash({:country => parts[1], :language => parts[0]})
  end
end

#mark_payload_provided(payment_id) ⇒ Hash

Posts a request to the Zaypay platform to mark that you have delivered the ‘goodies’ to your customer.

Please refer to README for more details.

Parameters:

  • payment_id (Integer) —

    the payment’s id

Returns:

  • (Hash) —

    a hash containing data of the specified payment



194
195
196
197
198
 
# File 'lib/zaypay/price_setting.rb', line 194

def mark_payload_provided(payment_id)
  post "///pay/#{price_setting_id}/payments/#{payment_id}/mark_payload_provided" do |data|
    payment_hash data
  end
end

#show_payment(payment_id) ⇒ Hash

Returns the specified payment as a hash.

Parameters:

  • payment_id (Integer) —

    your payment’s id

Returns:

  • (Hash) —

    a hash containing data of the specified payment



169
170
171
172
173
 
# File 'lib/zaypay/price_setting.rb', line 169

def show_payment(payment_id)
  get "///pay/#{price_setting_id}/payments/#{payment_id}" do |data|
    payment_hash data
  end
end

#verification_code(payment_id, verification_code) ⇒ Hash

Submits a verification code to the Zaypay platform.

In some countries, the end-user must submit a verification code in order to complete a payment. Please refer to the README for more details

Parameters:

  • payment_id (Integer) —

    the id of the payment that needs to be finalized

  • verification_code (Integer) —

    a code that the end-user receives through an sms and that he must submit to complete this payment

Returns:

  • (Hash) —

    a hash containing data of the specified payment



182
183
184
185
186
 
# File 'lib/zaypay/price_setting.rb', line 182

def verification_code(payment_id, verification_code)
  post "///pay/#{price_setting_id}/payments/#{payment_id}/verification_code", :verification_code => verification_code do |data|
    payment_hash data
  end
end