The Zaypay Gem allows your Ruby application to make HTTP-requests to the Zaypay API to retrieve information regarding your payments, price settings, etc.

Removed redundant dependencies. Tested for Ruby 1.8.7 and 1.9.3.

Method #ip_country_is_configured? has been renamed to #country_has_been_configured_for_ip

sudo gem install zaypay

Please check out github.com/zaypay for Ruby on Rails demo-applications that use the Zaypay gem as a dependency. They also demonstrate how to use the Zaypay gem to check status of a payment, handle reporting etc…

All communications to the Zaypay API go through Price Settings. Once you have signed up for an account with Zaypay, you can create a Price Setting, in which you define the price of your product (or service), price margins, as well as the payment methods (e.g. phone or sms). For more info check www.zaypay.com

Every Price Setting has its own id and api-key, the latter is only known to you and should remain as such.

Whenever you create an instance of Zaypay::PriceSetting, you need to provide it a price_setting_id and api_key.

# Example
Zaypay::PriceSetting.new(34567,"829e72d0f3b2e5bf764d667e98cf96a6")

However if you are using Ruby On Rails, we would recommend you to list your price_setting ids and api_keys in config/zaypay.yml

# config/zaypay.yml
15347: b483bc8fga615234567890abcdef1234
22354: d667e98cf96a6829e72d0f3b2e5bf764
default: 15347

By doing so, you can call

price_setting = Zaypay::PriceSetting.new(22354)
=> #<Zaypay::PriceSetting:0x22a65b4 @key="d667e98cf96a6829e72d0f3b2e5bf764", @price_setting_id=22354>
# it finds the corresponding API-key automatically

By providing it an optional default value, you can instantiate it without an argument

Zaypay::PriceSetting.new
=> #<Zaypay::PriceSetting:0x22a65b4 @key="b483bc8fga615234567890abcdef1234", @price_setting_id=15347>
# in this case, it will look for the default key, and assign the price_setting id and api_key accordingly

This is useful if you want to know your customers location so you can provide him a preselected country and/or language. It returns a hash with language and country as keys.

price_setting.locale_for_ip('82.170.248.207')
=> {:language=>"nl", :country=>"NL"}

# For example, you might want to set the default value for a language select_tag
price_setting.locale_for_ip('82.170.248.207')[:language]
=> 'nl'

This method returns the locale as a String. Whenever you call #list_payment_methods or #create_payment, you will need to set the locale first.

price_setting.locale_string_for_ip('82.170.248.207')
=> "nl-NL"

With this method, you can check whether the country of the incoming request has been configured for your price_setting. It either returns nil or a hash with :country and :locale as keys

price_setting.ip_country_is_configured?('82.170.248.207')
=> {:country => {:name => 'Netherlands', :code => 'NL'}, :locale => {:country => 'NL', :language => 'nl'}}

As an option, you can pass it an optional amount, to see whether that country has been configured to accept payments for a specific amount.

>> price_setting.ip_country_is_configured?('82.170.248.207', {:amount => 2})

This methods returns a hash of with languages and countries that are available to your Price Setting as arrays.

price_setting.list_locales
{:languages=>
  [{"native_name"=>"français", "code"=>"fr", "english_name"=>"French"},
   {"native_name"=>"Nederlands", "code"=>"nl", "english_name"=>"Dutch"},
   {"native_name"=>"English", "code"=>"en", "english_name"=>"English"}],
 :countries=>
  [{"name"=>"Australia", "code"=>"AU"},
   {"name"=>"Austria", "code"=>"AT"},
   ...
   ...
   {"name"=>"United Kingdom", "code"=>"GB"},
   {"name"=>"United States of America", "code"=>"US"}]}

# Example with optional amount, returns available locales for that specific amount
price_setting.list_locales({:amount => 2})

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

price_setting.list_countries
=> [{"name"=>"Australia", "code"=>"AU"},
    {"name"=>"Austria", "code"=>"AT"} }

# Example with optional amount, returns available countries for that specific amount
price_setting.list_countries({:amount => 2})

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

price_setting.list_languages
=> [{"native_name"=>"français", "code"=>"fr", "english_name"=>"French"},
    {"native_name"=>"Nederlands", "code"=>"nl", "english_name"=>"Dutch"}]

Once the locale has been set, you can display all payment methods available to your Price Setting for the given locale. NOTE: You must set the locale first before calling this method, otherwise an error will be raised.

price_setting.locale('nl-NL')
price_setting.list_payment_methods('nl-NL')
=> {:payment_methods=>
    [{"charged_amount"=>#<BigDecimal:243e5e8,'0.8E0',4(8)>,
      "name"=>"phone",
      "payment_method_id"=>1,
      "very_short_instructions"=>"betaal per telefoon",
      "very_short_instructions_with_amount"=>"betaal € 0,80 per telefoon",
      "eur_charged_amount"=>#<BigDecimal:243e200,'0.8E0',4(8)>,
      "formatted_amount"=>"€ 0,80",
      "payout"=>
       #<BigDecimal:243dfa8,'0.5599999999 9999999999 9999999999 8E0',32(36)>},
     {"charged_amount"=>#<BigDecimal:243db70,'0.8E0',4(8)>,
      "name"=>"sms",
      "payment_method_id"=>2,
      "very_short_instructions"=>"betaal per sms",
      "very_short_instructions_with_amount"=>"betaal € 0,80 per sms",
      "eur_charged_amount"=>#<BigDecimal:243d788,'0.8E0',4(8)>,
      "formatted_amount"=>"€ 0,80",
      "payout"=>#<BigDecimal:243d38c,'0.26E0',4(8)>}]}

# Example with an optional amount, returns available payment_methods for that specific amount
price_setting.list_payment_methods('nl-NL', {:amount => 5})

# Now that you know the payment_methods that are available, you can set the payment_method_id for your Price Setting
price_setting.price_setting_id = 2
# Once the locale and the payment_method_id have been set, you can proceed to create a payment

After the locale and the payment_method_id have been set, we can finally make a payment. NOTE: Locale and payment_method_id must be set before calling #create_payment, otherwise an error will be thrown

You can also pass in your own custom variables, which you can use for your own reference whenever you check the details of the payment. Also, in case you have activated the reporting feature in your price-setting (on the Zaypay platform), whenever the status of the payment has been updated, a query will be sent to your report-url (as configured in your Price Setting on zaypay.com) including those custom parameters.

price_setting.locale('nl-NL')
price_setting.price_setting_id = 2
ps.create_payment(:product_id => '1234')
=> {:payment=>{:created_at=>2012-08-17 15:10:11 UTC, 
               :id=>424729279, 
               :locale=>"nl-NL", 
               :paycode=>"3065", 
               :payload_provided=>false, 
               :total_amount=>#<BigDecimal:7fbb8def3a80,'0.55E0',9(18)>, 
               :currency=>"EUR", 
               :amount_euro=>0.55, 
               :total_payout=>#<BigDecimal:7fbb8def3710,'0.21E0',9(18)>, 
               :number=>"7711", 
               :formatted_number=>"7711", 
               :keyword=>"PAY", 
               :platform=>"sms", 
               :human_platform=>"sms", 
               :messages_to_be_sent=>1, 
               :messages_left_to_be_sent=>1, 
               :partly_customer_phone_number=>"unknown", 
               :customer_phone_number_hash=>"unknown", 
               :customer_mo_message=>"unknown", 
               :verification_needed=>false, 
               :your_variables=>"product_id=1234", 
               :status=>"prepared", 
               :payment_method_id=>2}, 
    :instructions=>{:status_string=>"De betaling is voorbereid", 
                    :very_short_instructions=>"betaal per sms", 
                    :very_short_instructions_with_amount=>"betaal € 0,55 per sms", 
                    :short_instructions=>"SMS de tekst PAY 3065 naar nummer 7711.", 
                    :long_instructions=>"SMS de tekst PAY 3065 naar telefoonnummer 7711. Je zal 1 bericht ontvangen. Hiermee is dan € 0,55 betaald. Verder betaal je het normale tarief voor het versturen van één SMSje. ", 
                    :disclaimer=>"Je staat op het punt om met echt geld te betalen. Als je jonger bent dan 13 jaar, moet je hiervoor toestemming hebben van je ouders."}}

# You can also have :payalogue_id or :amount as options
ps.create_payment(:product_id => '1234', :payalogue_id => '123456', :amount => 3)

A payment that is already in existence can be fetched with this method. It returns a hash representing the payment that you requested.

In most cases it also provides the payment instructions, unless when the payment has no ‘live’ status, as there is no way for your customer to interact with this payment anymore. This happens when it becomes ‘paid’ for instance, or when it has expired because your customer decided not to pay after all.

A particular useful scenario for this method is when your report-url receives a query with a payment_id and status. You can verify whether the information received at your report-url is genuinely from Zaypay by calling the show_payment method and compare the payment-statuses. You might want to update certain records within your application when the payment status on the Zaypay platform is really set to ‘paid’.

# Example
payment = price_setting.show_payment(123456)
set_purchase_to_paid if payment[:status] == 'paid'

In some countries, due to local regulations, we send your customer a verification code in the final (premium) message. Payments that require verification code come with a :verification_needed key set to TRUE.

For such payments, you have to present the customer a form to submit the verification_code if you are not using the Payalogue. Once you receive the verification code from the customer, you can make a call to Zaypay through the #verification_code method. This method returns a hash that represents a payment, and if the user has entered the verification code correctly, you will get a payment with status “paid”. Your customer has 3 attempts to enter the verification code

Please refer to the API integration demo application on {:link www.github.com/zaypay} to see this method in action.

# Example
payment_id = 123456
payment = price_setting.verification_code(payment_id, 98765)
# returns a hash representing a payment
payment[:payment][:tries_left]
# returns the number of tries left to submit the verification code. The end-user has 3 attempts to do so.
payment[:payment][:verification_needed]
# returns a boolean value regarding whether the end_user needs to enter the verification code

This method allows you to register the status of product delivery on the Zaypay platform.

The idea is that once your customer has paid, you must deliver the product (be it a file or site access) that he/she has paid for. But in certain cases, you might want to grant him access only once. In these cases, you can use the #mark_payload_provided method to track if a customer is misusing the system without having to keep track of all payments in your own database.

# Example
payment_id = 123456
payment = price_setting.mark_payload_provided(payment_id)
# returns a hash representing a payment
payment[:payment][:payload_provided] 
# returns a boolean value

zaypay.com/api_integration_guide

Copyright © 2012 Zaypay. Release under MIT license. See the attached MIT-License file.