Payson API

A simple utility to handle requests against the Payson payment gateway API.

Supported versions

Ruby 1.9.3, 2.0.0, 2.1.0

Install

Put this line in your Gemfile:

gem 'payson_api'

Then bundle:

$ bundle

Usage

General configuration options

You need to configure the gem with your own Payson credentials through the PaysonAPI.configure method:

PaysonAPI.configure do |config|
  config.api_user_id = 'XXXX'
  config.api_password = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
end

Please note that if config.api_user_id is set to 4, the client will go into test mode. Valid test access credentials could be found in documentation.

Initiating a payment

return_url = 'http://localhost/payson/success'
cancel_url = 'http://localhost/payson/cancel'
ipn_url = 'http://localhost/payson/ipn'
memo = 'Sample order description'

receivers = []
receivers << PaysonAPI::Receiver.new(
  email = '[email protected]',
  amount = 100,
  first_name = 'Me',
  last_name = 'Just me',
  primary = true
)

sender = PaysonAPI::Sender.new(
  email = '[email protected]',
  first_name = 'My',
  last_name = 'Customer'
)

order_items = []
order_items << PaysonAPI::OrderItem.new(
  description = 'Order item description',
  unit_price = 100,
  quantity = 1,
  tax = 0,
  sku = 'MY-ITEM-1'
)

payment = PaysonAPI::Request::Payment.new(
  return_url,
  cancel_url,
  ipn_url,
  memo,
  sender,
  receivers
)
payment.order_items = order_items

response = PaysonAPI::Client.initiate_payment(payment)

if response.success?
  # Redirect to response.forward_url
else
  puts response.errors
end

Requesting payment details

token = 'token-received-from-payment-request'

payment_details = PaysonAPI::Request::PaymentDetails.new(token)

response = PaysonAPI::Client.get_payment_details(payment_details)

if response.success?
  # Do stuff with response object
else
  puts response.errors
end

Updating a payment

token = 'token-received-from-payment-request'
action = 'CANCELORDER'

payment_update = PaysonAPI::Request::PaymentUpdate.new(token, action)

response = PaysonAPI::Client.update_payment(payment_update)

if response.success?
  # Do stuff with response object
else
  puts response.errors
end

Validating an IPN response

This example assumes the use of the Rails web framework.

class Payson < ApplicationController
  def ipn_responder
    request_body = request.body.read
    ipn_response = PaysonAPI::Response::IPN.new(request_body)

    # Do business stuff, e.g. update the corresponding order:
    #   order = Order.find_by_payson_token(ipn_response.token)
    #   order.payson_status = ipn_response.status
    #   order.save!

    # Create a new IPN request object containing the raw response from above
    ipn_request = PaysonAPI::Request::IPN.new(ipn_response.raw)

    validate = PaysonAPI::Client.validate_ipn(ipn_request)

    unless validate.verified?
      raise "Something went terribly wrong."
    end
  end
end

Todo

Nothing at the moment. Will focus on writing more thourough test cases and look over the code all in all.

Build Status <img src=“https://secure.travis-ci.org/stoffus/payson_api.png”/>

Questions, Feedback

Feel free to message me on Github (stoffus).