Project

payson_api

0.01
Low commit activity in last 3 years
No release in over a year
Client that enables access to the Payson payment gateway API.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 13
~> 1.15
~> 3.4
 Project Readme

Payson API

A zero dependency, pure Ruby utility to handle requests against the Payson payment gateway API.

Supported Ruby versions

  • 2.6
  • 2.7
  • 3.0

Installation

Put this line in your Gemfile:

gem 'payson_api'

Then bundle:

$ bundle

Usage (v2)

This explains how to use this gem with the Payson Checkout v2 API.

General configuration options

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

PaysonAPI::V2.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 their documentation.

For more detailed testing you may create your own test agent for use in the test environment. Use config.test_mode = true

Showing account info

account = PaysonAPI::V2::Client.get_account

Creating a checkout

request = PaysonAPI::V2::Requests::CreateCheckout.new
request.merchant.checkout_uri = 'http://localhost/checkout'
request.merchant.confirmation_uri = 'http://localhost/confirmation'
request.merchant.notification_uri = 'http://localhost/notification'
request.merchant.terms_uri = 'http://localhost/terms'
request.order.currency = 'sek'
request.order.items << PaysonAPI::V2::Requests::OrderItem.new.tap do |item|
  item.name = 'My product name'
  item.unit_price = 1000
  item.quantity = 3
  item.reference = 'product-1'
end

checkout = PaysonAPI::V2::Client.create_checkout(request)

# Continue by rendering the HTML from checkout.snippet.

Updating a checkout

checkout = PaysonAPI::V2::Client.get_checkout(checkout_id)

request = PaysonAPI::V2::Requests::UpdateCheckout.new
request.id = checkout.id
request.status = checkout.status
request.merchant.checkout_uri = checkout.merchant.checkout_uri
request.merchant.confirmation_uri = checkout.merchant.confirmation_uri
request.merchant.notification_uri = checkout.merchant.notification_uri
request.merchant.terms_uri = checkout.merchant.terms_uri
request.order.currency = 'eur'
request.order.items << PaysonAPI::V2::Requests::OrderItem.new.tap do |item|
  item.name = 'My product name'
  item.unit_price = 200
  item.quantity = 3
  item.reference = 'product-1'
end
request.order.items << PaysonAPI::V2::Requests::OrderItem.new.tap do |item|
  item.name = 'Another product name'
  item.unit_price = 600
  item.quantity = 1
  item.reference = 'product-2'
end

checkout = PaysonAPI::V2::Client.update_checkout(request)

Usage (v1)

This explains how to use the Payson 1.0 API.

General configuration options

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

PaysonAPI::V1.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}[https://tech.payson.se/#Testing/sandbox].

For more detailed testing you may create your own test agent for use in the test environment. Use config.test_mode = true

Initiating a payment

payment = PaysonAPI::V1::Requests::Payment.new
payment.return_url = 'http://localhost/payson/success'
payment.cancel_url = 'http://localhost/payson/cancel'
payment.ipn_url = 'http://localhost/payson/ipn'
payment.memo = 'Sample order description'
payment.sender = PaysonAPI::V1::Sender.new.tap do |s|
  s.email = 'mycustomer@mydomain.com'
  s.first_name = 'My'
  s.last_name = 'Customer'
end

payment.receivers = []
payment.receivers << PaysonAPI::V1::Receiver.new.tap do |r|
  r.email = 'me@mydomain.com'
  r.amount = 100
  r.first_name = 'Me'
  r.last_name = 'Just me'
  r.primary = true
end

payment.order_items = []
payment.order_items << PaysonAPI::V1::OrderItem.new.tap do |i|
  i.description = 'Order item description'
  i.unit_price = 100
  i.quantity = 1
  i.tax = 0
  i.sku = 'MY-ITEM-1'
end

response = PaysonAPI::V1::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::V1::Requests::PaymentDetails.new(token)

response = PaysonAPI::V1::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::V1::Requests::PaymentUpdate.new(token, action)

response = PaysonAPI::V1::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::V1::Responses::IPN.new(request_body)

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

    validation = PaysonAPI::V1::Client.validate_ipn(ipn_request)

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

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

Todo

Nothing at the moment.

Project Status

Build Status Gem Version

Questions, Feedback

Feel free to message me on GitHub.

Copyright

Copyright (c) 2021 Christopher Svensson.