pci_proxy 1.0.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d2e838d63aadc950a829e6d3b50e7c6fddcfffdb216ae9f7646d4dc06fbb930
-  data.tar.gz: 42b52b3106e60c53a75de4424f445edca6ddc9251c899f12f07dfeadee30b722
+  metadata.gz: 91dcc3b1b4d3f7b715bf9b97096e309041e263839f0c98b9b605ed6fa4b652d9
+  data.tar.gz: 10fe3831fe0b63dccfa142a21bf91983898574245c2c37ea4f62c2729a4f22ed
 SHA512:
-  metadata.gz: e9c4197a8b75b8070f5174d0a64ffd3fdb374ce4e279bc45b0f2386be6ccfdda3172baac6b00c8ac795526ac45e92bd4e19f41a23f959c5df803643d0b46562a
-  data.tar.gz: 11735efca4a2ce834ea0c6a05906b38649796b999eda37e9f6b697d39bce4b494cc1e92ba376d41a67e5ba270376a91388da925173541c2a46a8b09ec76f3b0f
+  metadata.gz: 8a7f74d2b7656f9227f8ead57e15ecbb1abf03ce7b6b0b1e7eedb30c5153571b55b7d7dfc13e41405ff16824ca0257600700fd1ae508c5ff7dd82d2930106f45
+  data.tar.gz: 5246d64cea9102600e09adfe254d25ea9368e4b1d91842f7feda9f9997ef426d2377b1403e241d80d6319a2e6d29f236e933c3ca764ad341743ece1e70dff05b

data/.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.gem
 /.idea/
 /.bundle/
 /.yardoc

data/CHANGELOG.md

@@ -1,7 +1,13 @@
-# PciProxy
+# PciProxy Change Log
 
 A simple client library for [PCI Proxy](https://pci-proxy.com)'s API
 
-#CHANGE LOG
+v1.2.1 - 30th January 2020 - Minor tweaks; cleanups; update documentation
 
-v1.0.0 - 14th January 2020 - Initial release - covers the [Token API](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes/token-api)
+v1.2.0 - 30th January 2020 - Add support for the [Check API](https://docs.pci-proxy.com/use-stored-cards/check)
+
+v1.1.0 - 17th January 2020 - Return an instance of PciProxy::Model::TokenisedCard instead of plain Hash
+
+v1.0.1 - 14th January 2020 - Relax dependency version requirements
+
+v1.0.0 - 14th January 2020 - Initial release - covering the [Token API](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes/token-api)

data/Gemfile.lock

@@ -1,19 +1,19 @@
 PATH
   remote: .
   specs:
-    pci_proxy (1.0.0)
-      faraday (~> 0.17.3)
-      multi_json (~> 1.14.1)
+    pci_proxy (1.2.2)
+      faraday (>= 0.8.9)
+      multi_json (>= 1.10.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    faraday (0.17.3)
+    faraday (1.0.1)
       multipart-post (>= 1.2, < 3)
     minitest (5.13.0)
     multi_json (1.14.1)
     multipart-post (2.1.1)
-    rake (10.5.0)
+    rake (13.0.1)
 
 PLATFORMS
   java
@@ -23,7 +23,7 @@ DEPENDENCIES
   bundler (~> 2.0)
   minitest (~> 5.0)
   pci_proxy!
-  rake (~> 10.0)
+  rake (~> 13.0)
 
 BUNDLED WITH
-   2.1.2
+   2.1.4

data/README.md

@@ -20,7 +20,7 @@ Or install it yourself as:
 
 ## Usage
 
-Initially, this gem only covers the [Token API](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes/token-api), which converts a transactionId from the [secure fields](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes) mechanism into tokenised card PAN and CVV.
+Initially, this gem only covers the [Token API](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes/token-api), which converts a transactionId from the [secure fields](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes) mechanism into tokenised card PAN and CVV, and the [Check API](https://docs.pci-proxy.com/use-stored-cards/check) which allows verification of a card token.
 
 Pull requests are most welcome for coverage of other PCI Proxy APIs :)
 ### Token API - Usage
@@ -35,20 +35,61 @@ And execute a token exchange like so:
 client.execute(transaction_id: '1234567890')
 ```
 
-In the event of a 200 OK response, the JSON response body is returned as a hash, for example:
+In the event of a 200 OK response, an instance of PciProxy::Model::TokenisedCard is returned:
 
 ```ruby
-{"aliasCC"=>"411111GGCMUJ1111", "aliasCVV"=>"vCslSwP0SQ9JXJy-nDzLKHaS"}
+#<PciProxy::Model::TokenisedCard:0x00007fda073453f8 @pan_token="411111GGCMUJ1111", @cvv_token="b8XeAbhQQES6OVWTpOCaAscj", @type_slug=:visa>
 ```
+(```response``` attr_reader value omitted for clarity)
+
+This object has attr_readers for ```pan_token```, ```cvv_token``` and ```type_slug``` which will return one of the following symbols:
+
+```ruby
+[:visa, :mastercard, :amex, :diners, :discovery, :jcb, :elo, :cup, :unknown]
+```
+
+It also has an attr_reader for ```response``` which is the raw parsed JSON response, as a hash.
 
 In the event of an error, a subclass of ```PciProxyAPIError``` will be raised.
 
 The most likely error is that the transactionId temporary token has expired, resulting in:
 
-```ruby
+```
 PciProxy::BadRequestError (HTTP status: 400, Response: Tokenization not found)
 ```
 
+### Check API - Usage
+
+Create an instance of ```PciProxy::Check``` and call ```execute``` as follows:
+
+```ruby
+client = PciProxy::Check.new(api_username: 'username', api_password: 'password')
+```
+
+And execute a card verification like so:
+
+```ruby
+client.execute(reference: 'foo', card_token: '411111GGCMUJ1111', card_type: :visa, expiry_month: 1, expiry_year: 2022)
+```
+
+In all cases (success, denoted by 200 OK from the API, or error, denoted by non-200 response), an instance of ```PciProxy::Model::CheckResult``` is returned.
+
+This object has attr_readers for ```auth_code```, ```transaction_id```, ```status``` and ```error```
+
+It also has an attr_reader for ```response``` which is the raw parsed JSON response, as a hash.
+
+With a successful response, the object's ```status``` attribute will have the value ```:success```, and the ```auth_code``` and ```transaction_id``` values will be available:
+```ruby
+#<PciProxy::Model::CheckResult:0x00007fbda2186fe8 @auth_code="124101", @transaction_id="190828124101219812", @error=nil, @status=:success>
+```
+(```response``` attr_reader value omitted for clarity)
+
+With an unsuccessful response, the object's ```status``` attribute will have the value ```:error```:
+```ruby
+#<PciProxy::Model::CheckResult:0x00007fbda2186fe8 @auth_code=nil, @transaction_id=nil, @error={"code"=>"UNAUTHORIZED", "message"=>"The account is not configured to use this API."}, @status=:error>
+```
+(```response``` attr_reader value omitted for clarity)
+
 ## Changes
 See [Changelog](CHANGELOG.md)
 

data/lib/pci_proxy.rb

@@ -2,7 +2,10 @@ require 'bundler'
 require "pci_proxy/version"
 
 require 'pci_proxy/base'
+require 'pci_proxy/check'
 require 'pci_proxy/token'
+require 'pci_proxy/model/check_result'
+require 'pci_proxy/model/tokenised_card'
 
 module PciProxy
   PciProxyAPIError = Class.new(StandardError)
@@ -19,4 +22,5 @@ module PciProxy
   HTTP_FORBIDDEN_CODE = 403
   HTTP_NOT_FOUND_CODE = 404
   HTTP_UNPROCESSABLE_ENTITY_CODE = 429
+
 end

data/lib/pci_proxy/base.rb

@@ -4,6 +4,8 @@ require 'multi_json'
 module PciProxy
   class Base
 
+    JSON_UTF8_CONTENT_TYPE = 'application/json; charset=UTF-8'.freeze
+
     attr_reader :api_endpoint, :api_username, :api_password
 
     ##
@@ -17,19 +19,35 @@ module PciProxy
     end
 
     ##
-    # Perform the API request
+    # Perform an API request via HTTP GET
     #
     # @param +endpoint+ [String] (Optional) - the API endpoint to hit - defaults to the value of the api_endpoint reader
-    # @param +http_method+ [Symbol] (Optional) - the HTTP method to use - defaults to GET
-    # @param +params+ [Hash] (Optional) - any parameters to supply to the API call
+    # @param +params+ [Hash] (Optional) - any URL parameters to supply to the API call
     #
     # @raise [PciProxyAPIError] in cases where the API responds with a non-200 response code
     # @return [Hash] parsed JSON response
+    def api_get(endpoint: @api_endpoint, params: {}, raise_on_error: true)
+      response = client.get(endpoint, params)
+
+      if raise_on_error == false || response.status == HTTP_OK_CODE
+        return MultiJson.load(response.body)
+      end
+
+      raise error_class(response), "HTTP status: #{response.status}, Response: #{response.body}"
+    end
+
+    ##
+    # Perform an API request via HTTP POST
+    #
+    # @param +endpoint+ [String] (Optional) - the API endpoint to hit - defaults to the value of the api_endpoint reader
+    # @param +body+ [Hash] (Optional) - the API request payload (will be converted to JSON)
     #
-    def request(endpoint: @api_endpoint, http_method: :get, params: {})
-      response = client.public_send(http_method, endpoint, params)
+    # @raise [PciProxyAPIError] in cases where the API responds with a non-200 response code
+    # @return [Hash] parsed JSON response
+    def api_post(endpoint: @api_endpoint, body: {}, raise_on_error: true)
+      response = client.post(endpoint, MultiJson.dump(body), "Content-Type" => JSON_UTF8_CONTENT_TYPE)
 
-      if response.status == HTTP_OK_CODE
+      if raise_on_error == false || response.status == HTTP_OK_CODE
         return MultiJson.load(response.body)
       end
 

data/lib/pci_proxy/check.rb

@@ -0,0 +1,62 @@
+module PciProxy
+  class Check < Base
+
+    SANDBOX_ENDPOINT = 'https://api.sandbox.datatrans.com/v1/transactions/validate'.freeze
+    LIVE_ENDPOINT = 'https://api.datatrans.com/v1/transactions/validate'.freeze
+
+    CHF = 'CHF'.freeze
+    EUR = 'EUR'.freeze
+
+    # error codes
+    # "UNKNOWN_ERROR", "UNRECOGNIZED_PROPERTY", "INVALID_PROPERTY", "INVALID_TRANSACTION_STATUS", "TRANSACTION_NOT_FOUND", "INVALID_JSON_PAYLOAD", "UNAUTHORIZED", "EXPIRED_CARD", "INVALID_CARD", "UNSUPPORTED_CARD", "DUPLICATED_REFNO", "DECLINED", "BLOCKED_BY_VELOCITY_CHECKER", "CLIENT_ERROR" , "SERVER_ERROR"
+
+    ##
+    # Initialise with the specified +api_username+ and +api_password+ from PCI Proxy.
+    #
+    # Defaults to the sandbox API endpoint - to use the live environment,
+    # supply the LIVE_ENDPOINT constant as the value of the +endpoint+ kwarg
+    def initialize(api_username:, api_password:, endpoint: SANDBOX_ENDPOINT)
+      @api_endpoint = endpoint
+      @api_username = api_username
+      @api_password = api_password
+    end
+
+    ##
+    # Perform a check API request to verify the card token
+    #
+    # @param +reference+ [String] - caller's unique reference (any non-empty string value)
+    # @param +card_token+ [String] - card token obtained from the Token API - see PciProxy::Token
+    # @param +card_type+ [Symbol / String] - one of 'visa', 'mastercard' or 'amex'
+    # @param +expiry_month+ [Integer / String] - integer 1-12, or string '01' - '12'
+    # @param +expiry_year+ [Integer / String] - two or four digit year as a string or integer
+    # @param +currency+ [Integer / String] (Optional) - one of 'CHF' or 'EUR' - will default by card type where not specified
+    #
+    # @raise [PciProxyAPIError] in cases where the API responds with a non-200 response code
+    # @return [Hash] result from PCI Proxy, decoded from JSON
+    def execute(reference:, card_token:, card_type:, expiry_month:, expiry_year:, currency: nil)
+      raise "reference is required" if reference.empty?
+      raise "card_token is required" unless card_token && !card_token.empty?
+      raise "card_type must be one of 'visa', 'mastercard' or 'amex'" unless [:visa, :mastercard, :amex].include?(card_type.to_sym)
+      raise "invalid expiry_month" unless (1..12).include?(expiry_month.to_i)
+      raise "invalid expiry_year" unless expiry_year.to_i > 0
+
+      # default the currency where not specified - according to the documentation Amex should use EUR, Visa and MC should use CHF
+      currency ||= :amex == card_type.to_sym ? EUR : CHF
+
+      card = {
+          alias: card_token,
+          expiryMonth: expiry_month.to_s,
+          expiryYear: expiry_year.to_s.chars.last(2).join
+      }
+
+      body = {
+          refno: reference,
+          currency: currency,
+          card: card
+      }
+
+      PciProxy::Model::CheckResult.new(api_post(endpoint: @api_endpoint, body: body, raise_on_error: false))
+    end
+
+  end
+end

data/lib/pci_proxy/model/check_result.rb

@@ -0,0 +1,18 @@
+module PciProxy
+  module Model
+    class CheckResult
+
+      attr_reader :response, :status, :error, :auth_code, :transaction_id
+
+      def initialize(response)
+        @response = response
+        @auth_code = response["acquirerAuthorizationCode"]
+        @transaction_id = response["transactionId"]
+        @error = response["error"]
+
+        @status = @auth_code && @transaction_id && !@error ? :success : :error
+      end
+
+    end
+  end
+end

data/lib/pci_proxy/model/tokenised_card.rb

@@ -0,0 +1,43 @@
+module PciProxy
+  module Model
+    class TokenisedCard
+
+      attr_reader :response, :pan_token, :cvv_token, :type_slug
+
+      def initialize(response)
+        @response = response
+        @pan_token = response["aliasCC"]
+        @cvv_token = response["aliasCVV"]
+        @type_slug = slug_for(response["paymentMethod"])
+      end
+
+      private
+
+      def slug_for(payment_method)
+        return nil if payment_method.nil?
+
+        case payment_method
+        when 'VIS'
+          :visa
+        when 'ECA'
+          :mastercard
+        when 'AMX'
+          :amex
+        when 'DIN'
+          :diners
+        when 'DIS'
+          :discovery
+        when 'JCB'
+          :jcb
+        when 'ELO'
+          :elo
+        when 'CUP'
+          :cup
+        else
+          :unknown
+        end
+
+      end
+    end
+  end
+end

data/lib/pci_proxy/token.rb

@@ -1,24 +1,35 @@
 module PciProxy
   class Token < Base
 
+    SANDBOX_ENDPOINT = 'https://api.sandbox.datatrans.com/upp/services/v1/inline/token'.freeze
+    LIVE_ENDPOINT = 'https://api.datatrans.com/upp/services/v1/inline/token'.freeze
+
     ##
     # Initialise with the specified +api_username+ and +api_password+ from PCI Proxy.
-    def initialize(api_username:, api_password:)
-      @api_endpoint = 'https://api.sandbox.datatrans.com/upp/services/v1/inline/token'.freeze
+    #
+    # Defaults to the sandbox API endpoint - to use the live environment,
+    # supply the LIVE_ENDPOINT constant as the value of the +endpoint+ kwarg
+    def initialize(api_username:, api_password:, endpoint: SANDBOX_ENDPOINT)
+      @api_endpoint = endpoint
       @api_username = api_username
       @api_password = api_password
     end
 
     ##
-    # Perform a token request to turn the specified +transaction_id+ into card and CVV tokens
+    # Perform a token API request to turn the specified +transaction_id+ into card and CVV tokens
     #
     # @param +return_payment_method+ (true/false) - whether or not to return the identified payment method (default: true)
     # @param +cvv_mandatory+ (true/false) - whether or not to consider the CVV alias should be mandatory (default: false)
     #
     # @raise [PciProxyAPIError] in cases where the API responds with a non-200 response code
-    # @return [Hash] result from PCI Proxy, decoded from JSON
+    # @return [PciProxy::Model::TokenisedCard] wrapper object around the JSON response
     def execute(transaction_id:, return_payment_method: true, cvv_mandatory: false)
-      request(params: { transactionId: transaction_id, returnPaymentMethod: return_payment_method, mandatoryAliasCVV: cvv_mandatory })
+      raise "transaction_id is required" unless transaction_id && !transaction_id.empty?
+
+      PciProxy::Model::TokenisedCard.new(api_get(params: {
+          transactionId: transaction_id,
+          returnPaymentMethod: return_payment_method,
+          mandatoryAliasCVV: cvv_mandatory }))
     end
 
   end

data/lib/pci_proxy/version.rb

@@ -1,3 +1,3 @@
 module PciProxy
-  VERSION = "1.0.0"
+  VERSION = "1.2.2"
 end

data/pci_proxy.gemspec

@@ -27,9 +27,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
 
-  spec.add_dependency "faraday", "~> 0.17.3"
-  spec.add_dependency "multi_json", "~> 1.14.1"
+  spec.add_dependency "faraday", ">= 0.8.9"
+  spec.add_dependency "multi_json", ">= 1.10.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pci_proxy
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.2
 platform: ruby
 authors:
 - Rory Sinclair
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-14 00:00:00.000000000 Z
+date: 2020-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -56,30 +56,30 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.3
+        version: 0.8.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.3
+        version: 0.8.9
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.14.1
+        version: 1.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.14.1
+        version: 1.10.0
 description: A ruby library covering the server-server aspects of the PCI-Proxy API
 email:
 - rory@mungler.com
@@ -100,6 +100,9 @@ files:
 - bin/setup
 - lib/pci_proxy.rb
 - lib/pci_proxy/base.rb
+- lib/pci_proxy/check.rb
+- lib/pci_proxy/model/check_result.rb
+- lib/pci_proxy/model/tokenised_card.rb
 - lib/pci_proxy/token.rb
 - lib/pci_proxy/version.rb
 - pci_proxy.gemspec