payson_api 0.3.2 → 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 66f555c3be4e18baaad0ed1785a94c4c9b248d62aabf7cbb1caeab6c3e55ae17
+  data.tar.gz: 6d95db7cf0198afa8ebae7fee4d077c87b306982eb70e533f71248fa7fbbbb4a
+SHA512:
+  metadata.gz: 0dbfff1f59b35aa89efed837854bc9b5afd3c7e6a4dceec2574715e54ceb60bd210b104803ede5f7ab8edf76999d3f037420aee9241789be178067352d37d238
+  data.tar.gz: cb319533f28f26526b83bffc112a5ebd6ba47ed82b16ff2724066d23032f6dea4ab00a2045ff883b15a3c34570f0bac914e27a491f56267496948c8c7445fa9e

data/MIT-LICENSE

@@ -1,20 +1,19 @@
-Copyright (c) 2012 Christopher Svensson
+Copyright (c) 2021 Christopher Svensson
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,228 @@
+# Payson API
+
+A simple utility to handle requests against the Payson payment gateway API.
+
+## Supported Ruby versions
+
+* 2.6
+* 2.7
+* 3.0
+
+## Install
+
+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](https://tech.payson.se/paysoncheckout2).
+
+### General configuration options
+
+You need to configure the gem with your own Payson credentials through the `PaysonAPI::V2.configure` method:
+
+```ruby
+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](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`
+
+### Showing account info
+
+```ruby
+account = PaysonAPI::V2::Client.get_account
+```
+
+### Creating a checkout
+
+```ruby
+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
+```
+
+### Updating a checkout
+
+```ruby
+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](https://tech.payson.se/paysoncheckout1).
+
+### General configuration options
+
+You need to configure the gem with your own Payson credentials through the `PaysonAPI::V1.configure` method:
+
+```ruby
+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
+
+```ruby
+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 = sender
+
+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
+
+```ruby
+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
+
+```ruby
+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.
+
+```ruby
+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)
+
+    validate = PaysonAPI::V1::Client.validate_ipn(ipn_request)
+
+    unless validate.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
+
+Document the code for the Payson Checkout v2 processes.
+
+## Build Status
+
+[![Build Status](https://travis-ci.org/stoffus/payson_api.svg?branch=master)](https://travis-ci.org/stoffus/payson_api)
+
+## Questions, Feedback
+
+Feel free to message me on Github (stoffus).
+
+## Copyright
+
+Copyright (c) 2021 Christopher Svensson.

data/lib/payson_api.rb

@@ -1,25 +1,58 @@
-required_files = [
-  'config',
-  'client',
-  'envelope',
-  'funding',
-  'order_item',
-  'receiver',
-  'remote_error',
-  'request/ipn',
-  'request/payment_details',
-  'request/payment_update',
-  'request/payment',
-  'response/ipn',
-  'response/payment_details',
-  'response/payment_update',
-  'response/payment',
-  'response/validate',
-  'sender',
-  'shipping_address',
-  'version'
+# frozen_string_literal: true
+
+require_relative 'payson_api/version'
+
+required_files_v1 = %w[
+  config
+  client
+  envelope
+  errors/unknown_currency_error
+  errors/unknown_fees_payer_error
+  errors/unknown_funding_constraint_error
+  errors/unknown_guarantee_offering_error
+  errors/unknown_locale_error
+  errors/unknown_payment_action_error
+  funding
+  order_item
+  receiver
+  remote_error
+  requests/ipn
+  requests/payment_details
+  requests/payment_update
+  requests/payment
+  responses/ipn
+  responses/payment_details
+  responses/payment_update
+  responses/payment
+  responses/validate
+  sender
+  shipping_address
+]
+
+required_files_v2 = %w[
+  config
+  client
+  errors/validation_error
+  errors/unauthorized_error
+  models/account
+  models/checkout
+  models/customer
+  models/merchant
+  models/order_item
+  models/order
+  requests/order_item
+  requests/customer
+  requests/merchant
+  requests/order
+  requests/create_checkout
+  requests/update_checkout
+  requests/list_checkouts
 ]
 
-required_files.each do |file|
-  require "payson_api/#{file}"
+required_files_v1.each do |file|
+  require_relative "payson_api/v1/#{file}"
+end
+
+required_files_v2.each do |file|
+  require_relative "payson_api/v2/#{file}"
 end

data/lib/payson_api/v1/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'net/https'
+
+module PaysonAPI
+  module V1
+    class Client
+      def self.initiate_payment(payment_data)
+        response = payson_request(
+          PAYSON_API_PAY_ACTION,
+          payment_data.to_hash
+        )
+        response_hash = params_to_hash(response.body)
+        PaysonAPI::V1::Responses::Payment.new(response_hash)
+      end
+
+      def self.get_payment_details(payment_details_data)
+        response = payson_request(
+          PAYSON_API_PAYMENT_DETAILS_ACTION,
+          payment_details_data.to_hash
+        )
+        response_hash = params_to_hash(response.body)
+        PaysonAPI::V1::Responses::PaymentDetails.new(response_hash)
+      end
+
+      def self.update_payment(payment_update_data)
+        response = payson_request(
+          PAYSON_API_PAYMENT_DETAILS_ACTION,
+          payment_update_data.to_hash
+        )
+        response_hash = params_to_hash(response.body)
+        PaysonAPI::V1::Responses::PaymentUpdate.new(response_hash)
+      end
+
+      def self.validate_ipn(ipn_data)
+        response = payson_request(
+          PAYSON_API_PAYMENT_VALIDATE_ACTION,
+          ipn_data.to_s
+        )
+        PaysonAPI::V1::Responses::Validate.new(response.body)
+      end
+
+      def self.hash_to_params(hash)
+        hash.map { |k, v| "#{k}=#{URI.encode_www_form_component(v.to_s)}" }.join('&')
+      end
+
+      def self.params_to_hash(params)
+        {}.tap do |hash|
+          params.split('&').each do |param|
+            key, val = param.split('=')
+            hash[key] = URI.decode_www_form_component(val)
+          end
+        end
+      end
+
+      def self.payson_request(action, data)
+        path = format('/%<api_version>s/%<action>s/', api_version: PAYSON_API_VERSION, action: action)
+        url = PaysonAPI::V1.api_base_url + path
+        headers = {
+          'PAYSON-SECURITY-USERID' => PaysonAPI::V1.config.api_user_id,
+          'PAYSON-SECURITY-PASSWORD' => PaysonAPI::V1.config.api_password,
+          'Content-Type' => 'application/x-www-form-urlencoded'
+        }
+        post(url, data, headers)
+      end
+
+      def self.post(url, data, headers)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.body = data.is_a?(Hash) ? hash_to_params(data) : data
+        headers.each do |name, value|
+          req[name] = value
+        end
+        http.request(req)
+      end
+    end
+  end
+end

data/lib/payson_api/v1/config.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PaysonAPI
+  module V1
+    module_function
+
+    PAYSON_WWW_HOST_ENDPOINT = 'https://www.payson.se'
+    PAYSON_WWW_PAY_FORWARD_URL = '/paysecure/?token=%s'
+
+    PAYSON_API_ENDPOINT = 'https://api.payson.se'
+    PAYSON_API_VERSION = '1.0'
+    PAYSON_API_PAY_ACTION = 'Pay'
+    PAYSON_API_PAYMENT_DETAILS_ACTION = 'PaymentDetails'
+    PAYSON_API_PAYMENT_UPDATE_ACTION = 'PaymentUpdate'
+    PAYSON_API_PAYMENT_VALIDATE_ACTION = 'Validate'
+
+    PAYSON_API_TEST_ENDPOINT = 'https://test-api.payson.se'
+    PAYSON_WWW_HOST_TEST_ENDPOINT = 'https://test-www.payson.se'
+
+    LOCALES = %w[SV EN FI].freeze
+    CURRENCIES = %w[SEK EUR].freeze
+    FEES_PAYERS = %w[EACHRECEIVER SENDER PRIMARYRECEIVER SECONDARYONLY].freeze
+    FUNDING_CONSTRAINTS = %w[CREDITCARD BANK INVOICE SMS].freeze
+    GUARANTEE_OFFERINGS = %w[OPTIONAL REQUIRED NO].freeze
+    PAYMENT_STATUSES = %w[CREATED PENDING PROCESSING COMPLETED CREDITED
+                          INCOMPLETE ERROR EXPIRED REVERSALERROR ABORTED].freeze
+    PAYMENT_TYPES = %w[TRANSFER GUARANTEE INVOICE].freeze
+    GUARANTEE_STATUSES = %w[WAITINGFORSEND WAITINGFORACCEPTANCE WAITINGFORRETURN
+                            WAITINGFORRETURNACCEPTANCE RETURNNOTACCEPTED NOTRECEIVED RETURNNOTRECEIVED
+                            MONEYRETURNEDTOSENDER RETURNACCEPTED].freeze
+    INVOICE_STATUSES = %w[PENDING ORDERCREATED CANCELED SHIPPED DONE CREDITED].freeze
+    PAYMENT_ACTIONS = %w[CANCELORDER SHIPORDER CREDITORDER REFUND].freeze
+
+    def configure
+      yield @config ||= Configuration.new # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+
+    def config
+      @config
+    end
+
+    class Configuration
+      attr_accessor :api_user_id, :api_password, :test_mode
+    end
+
+    configure do |config|
+      config.api_user_id = 'XXXX'
+      config.api_password = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
+    end
+
+    def test?
+      @config.test_mode || @config.api_user_id == '4'
+    end
+
+    def api_base_url
+      test? ? PAYSON_API_TEST_ENDPOINT : PAYSON_API_ENDPOINT
+    end
+
+    def forward_url(token)
+      (test? ? PAYSON_WWW_HOST_TEST_ENDPOINT : PAYSON_WWW_HOST_ENDPOINT) + PAYSON_WWW_PAY_FORWARD_URL % token
+    end
+  end
+end