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.configuredo |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.newrequest.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.tapdo |item|
item.name='My product name'item.unit_price=1000item.quantity=3item.reference='product-1'endcheckout=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.newrequest.id=checkout.idrequest.status=checkout.statusrequest.merchant.checkout_uri=checkout.merchant.checkout_urirequest.merchant.confirmation_uri=checkout.merchant.confirmation_urirequest.merchant.notification_uri=checkout.merchant.notification_urirequest.merchant.terms_uri=checkout.merchant.terms_urirequest.order.currency='eur'request.order.items << PaysonAPI::V2::Requests::OrderItem.new.tapdo |item|
item.name='My product name'item.unit_price=200item.quantity=3item.reference='product-1'endrequest.order.items << PaysonAPI::V2::Requests::OrderItem.new.tapdo |item|
item.name='Another product name'item.unit_price=600item.quantity=1item.reference='product-2'endcheckout=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.configuredo |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.newpayment.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.tapdo |s|
s.email='mycustomer@mydomain.com's.first_name='My's.last_name='Customer'endpayment.receivers=[]payment.receivers << PaysonAPI::V1::Receiver.new.tapdo |r|
r.email='me@mydomain.com'r.amount=100r.first_name='Me'r.last_name='Just me'r.primary=trueendpayment.order_items=[]payment.order_items << PaysonAPI::V1::OrderItem.new.tapdo |i|
i.description='Order item description'i.unit_price=100i.quantity=1i.tax=0i.sku='MY-ITEM-1'endresponse=PaysonAPI::V1::Client.initiate_payment(payment)ifresponse.success?# Redirect to response.forward_urlelseputsresponse.errorsend

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)ifresponse.success?# Do stuff with response objectelseputsresponse.errorsend

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)ifresponse.success?# Do stuff with response objectelseputsresponse.errorsend

Validating an IPN response

This example assumes the use of the Rails web framework.

classPayson < ApplicationControllerdefipn_responderrequest_body=request.body.readipn_response=PaysonAPI::V1::Responses::IPN.new(request_body)# Create a new IPN request object containing the raw response from aboveipn_request=PaysonAPI::V1::Requests::IPN.new(ipn_response.raw)validation=PaysonAPI::V1::Client.validate_ipn(ipn_request)unlessvalidation.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!endend

Todo

Nothing at the moment.

Project Status

Questions, Feedback

Feel free to message me on GitHub.

Copyright

Copyright (c) 2021 Christopher Svensson.