vantiv 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 923cb51d4a0626d8b63cb9139ff3961ea5bbbd96
-  data.tar.gz: 5ce0a976b96f07c76e1251d5c4de9b453b26b56f
+  metadata.gz: 4eafce70c91d564dbbab06586a1fc13f0a7f1458
+  data.tar.gz: b5abe4e788d601c489d882db8ac0b9f32dbacf59
 SHA512:
-  metadata.gz: 4209143635bf22f01654e50a1dbddd61b331a1329b0a9d5a4fb26b74da986260a2e3c7c6cfee33667cfec3ef6b200fc862ae2724cf4fe85b903a255d3e7dd2f3
-  data.tar.gz: 3b61c32775ed45e78a0cd3f1454acd7729b56abbf9e7bb6743ff7e8f20a60bdfc524c15c49bb15fb843a487517f1c061bd3216ef447723e4dd63c8ffd67239e1
+  metadata.gz: b85dc5bc03b74980e17ab655bd63b0999931a3e512ac4a28ef8a1bd3ee635b26d04e5a5f386930ac7fe722f573c7dac037c86415da70baf3bd484f1014969ae4
+  data.tar.gz: 97b171c491f1503d1e5eb259d1140ce1e64487297eb8173588450a69eeed428c6a302c3e2a1c6760282143b7c6f70611e247c00fe4f16d80fa2e3cf800ce45e4

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+Vantiv Ruby Changes
+
+0.2.0
+-----------
+
+NOTE: API change occurs in this version bump on:
+
+1. `Vantiv.auth` and `Vantiv.auth_capture` now require `expiry_month`
+   and `expiry_year` to be passed. Merchants are responsible for persisting
+   this data.
+2. `Vantiv.credit`'s `amount` argument is now optional.
+
+- Send expiration data on live transactions
+  - Major miscommunication from Vantiv during development that sending
+    expiration data on authorizations and auth_captures (Sale) was
+    not necessary.
+  - Expiration data is required for card-not-present transactions
+  - In actuality, majority of transactions will work without expiry
+    data but a significant number of them will fail with "Invalid Transaction"
+    and "Do No Honor" response codes.
+- Make amount in credit endpoint optional; with no amount passed, Vantiv
+  credits full amount of original transaction
+- Strip non-numeric characters from credit card numbers:
+  - Numbers input with spaces or delimeters are acceptable for direct
+    tokenization as a result
+- Cast arguments accepted to strings in Request Bodies
+- Retry requests when Vantiv doesn't respond with JSON
+  - Sometimes, Vantiv's API doesn't respond with JSON (typically, when
+    a service is down or something)
+  - It seems safe to retry requests in that case, up to 3 times.
+- Add mocked sandbox responses for all other endpoints:
+  - Auth
+  - Capture
+  - Auth Reversal
+  - Credit
+  - Refund
+  - Void
+
+0.1.0
+-----------
+
+- Add a mocked sandbox structure for gem to operate in test:
+  - Allows gem to operate in a test environment without making real
+    network requests, while still behaving identically to certification
+    Environment
+  - Only difference is that mocked sandbox has consistent payment account
+    IDs per card number, available on TestCard object
+    #mocked_sandbox_payment_account_id
+  - Intially only for direct tokenization endpoint
+- Implement direct tokenization, allowing merchants to both use eProtect or
+  tokenize with Vantiv directly.
+- Implement auth reversal
+- Implement refunds
+- Implement credits
+- Implement voids
+- Add TravisCI for CI
+- Add paypage server and paypage driver, objects to run a basic version of
+  an eProtect page. Enables retrieving paypageRegistrationIDs in order to test
+  usage to tokenize via eProtect.
+- Add script to run all Devhub certification environment validation tests
+  via script:
+  - Allows merchants to install gem and certify quickly, rather than manually
+
+

data/README.md

@@ -6,7 +6,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'vantiv-ruby'
+gem 'vantiv'
 ```
 
 And then execute:
@@ -15,7 +15,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install vantiv-ruby
+    $ gem install vantiv
 
 ## Configuration
 
@@ -53,7 +53,7 @@ Navigate to your application's page in DevHub's developer portal (apideveloper.v
 
 ## Usage
 
-The vantiv-ruby gem provides a simple ruby client for interacting with Vantiv's DevHub API. This API wraps their Litle/XML API and provides an API that uses json. This gem provides a way for a merchant to:
+The vantiv gem provides a simple ruby client for interacting with Vantiv's DevHub API. This API wraps their Litle/XML API and provides an API that uses json. This gem provides a way for a merchant to:
 
 1. Use Vantiv's eProtect feature to tokenize sensitive card information directly to Vantiv's servers.
 2. Run the following transactions on customers' accounts:
@@ -181,7 +181,23 @@ In the server, once a temporary token has been received, a permanent token can b
 Vantiv.tokenize(temporary_token: 'temporary-token-here')
 ```
 
-This will return a TokenizationResponse object, which responds to `success?` and `failure?`, and which returns the `payment_account_id` retrieved from Vantiv. The merchant should save this token for use on future transactions.
+This will return a TokenizationResponse object, which responds to `success?` and `failure?`, and which returns a `card_type` and the `payment_account_id` retrieved from Vantiv. The merchant should save this token for use on future transactions.
+
+The `card_type` corresponds with the type of account that was used in the transaction and has the following enumerations:
+
+| Enumeration | Description |
+| ------------- | ------------- |
+| MC | MasterCard |
+| VI | Visa |
+| AX | American Express |
+| DC | Diner’s Club |
+| DI | Discover |
+| PP | PayPal |
+| JC | JCB (Japanese Credit Bureau) |
+| BL | PayPal Credit |
+| EC | eCheck |
+| GC | Gift Card |
+| “” | (empty) Card type unknown or undefined |
 
 NOTES: There are a few gotchas with tokenization, namely:
 

data/cert_fixtures/L_EP_1.json

@@ -9,7 +9,9 @@
       "PartialApprovedFlag": "false"
     },
     "Card": {
-      "PaypageRegistrationID": "${eProtect.4457010000000009}"
+      "PaypageRegistrationID": "${eProtect.4457010000000009}",
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/cert_fixtures/L_EP_2.json

@@ -9,7 +9,9 @@
       "PartialApprovedFlag": "false"
     },
     "Card": {
-      "PaypageRegistrationID": "${eProtect.5435101234510196}"
+      "PaypageRegistrationID": "${eProtect.5435101234510196}",
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/cert_fixtures/L_EP_3.json

@@ -2,7 +2,9 @@
   "endpoint": "TOKENIZATION",
   "body": {
     "Card": {
-      "PaypageRegistrationID": "${eProtect.6011010140000004}"
+      "PaypageRegistrationID": "${eProtect.6011010140000004}",
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     },
     "Transaction": {
       "CustomerID": "123"

data/cert_fixtures/L_EP_4.json

@@ -10,6 +10,10 @@
     },
     "PaymentAccount": {
       "PaymentAccountID": "#{L_EP_1.litleOnlineResponse.authorizationResponse.tokenResponse.PaymentAccountID}"
+    },
+    "Card": {
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/cert_fixtures/L_EP_5.json

@@ -10,6 +10,10 @@
     },
     "PaymentAccount": {
       "PaymentAccountID": "#{L_EP_2.litleOnlineResponse.saleResponse.tokenResponse.PaymentAccountID}"
+    },
+    "Card": {
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/cert_fixtures/L_EP_6.json

@@ -9,7 +9,9 @@
       "PartialApprovedFlag": "false"
     },
     "Card": {
-      "PaypageRegistrationID": "cDZJcmd1VjNlYXNaSlRMTGpocVZQY1NWVXE4ZW5UTko4NU9KK3p1L1p1Vzg4YzVPQVlSUHNITG1JN2I0NzlyTg=="
+      "PaypageRegistrationID": "cDZJcmd1VjNlYXNaSlRMTGpocVZQY1NWVXE4ZW5UTko4NU9KK3p1L1p1Vzg4YzVPQVlSUHNITG1JN2I0NzlyTg==",
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/cert_fixtures/L_EP_7.json

@@ -9,7 +9,9 @@
       "PartialApprovedFlag": "false"
     },
     "Card": {
-      "PaypageRegistrationID": "RGFQNCt6U1d1M21SeVByVTM4dHlHb1FsVkUrSmpnWXhNY0o5UkMzRlZFanZiUHVnYjN1enJXbG1WSDF4aXlNcA=="
+      "PaypageRegistrationID": "RGFQNCt6U1d1M21SeVByVTM4dHlHb1FsVkUrSmpnWXhNY0o5UkMzRlZFanZiUHVnYjN1enJXbG1WSDF4aXlNcA==",
+      "ExpirationMonth": "01",
+      "ExpirationYear": "16"
     }
   }
 }

data/exe/vantiv-certify-app

@@ -11,6 +11,7 @@ Vantiv.configure do |config|
   config.license_id = ENV["LICENSE_ID"]
   config.acceptor_id = ENV["ACCEPTOR_ID"]
   config.paypage_id = ENV["PAYPAGE_ID"]
+  config.environment = Vantiv::Environment::CERTIFICATION
 
   config.default_report_group = '1'
 end

data/lib/vantiv.rb

@@ -37,12 +37,14 @@ module Vantiv
     ).run
   end
 
-  def self.auth(amount:, payment_account_id:, customer_id:, order_id:)
+  def self.auth(amount:, payment_account_id:, customer_id:, order_id:, expiry_month:, expiry_year:)
     body = Api::RequestBody.for_auth_or_sale(
       amount: amount,
       order_id: order_id,
       customer_id: customer_id,
-      payment_account_id: payment_account_id
+      payment_account_id: payment_account_id,
+      expiry_month: expiry_month,
+      expiry_year: expiry_year
     )
     Api::Request.new(
       endpoint: Api::Endpoints::AUTHORIZATION,
@@ -77,12 +79,14 @@ module Vantiv
     ).run
   end
 
-  def self.auth_capture(amount:, payment_account_id:, customer_id:, order_id:)
+  def self.auth_capture(amount:, payment_account_id:, customer_id:, order_id:, expiry_month:, expiry_year:)
     body = Api::RequestBody.for_auth_or_sale(
       amount: amount,
       order_id: order_id,
       customer_id: customer_id,
-      payment_account_id: payment_account_id
+      payment_account_id: payment_account_id,
+      expiry_month: expiry_month,
+      expiry_year: expiry_year
     )
     Api::Request.new(
       endpoint: Api::Endpoints::SALE,
@@ -93,7 +97,7 @@ module Vantiv
 
   # NOTE: ActiveMerchant's #refund... only for use on a capture or sale it seems
   #       -> 'returns' are refunds too, credits are tied to a sale/capture, returns can be willy nilly
-  def self.credit(transaction_id:, amount:)
+  def self.credit(transaction_id:, amount: nil)
     body = Api::RequestBody.for_credit(
       amount: amount,
       transaction_id: transaction_id
@@ -105,12 +109,14 @@ module Vantiv
     ).run
   end
 
-  def self.refund(amount:, payment_account_id:, customer_id:, order_id:)
+  def self.refund(amount:, payment_account_id:, customer_id:, order_id:, expiry_month:, expiry_year:)
     body = Api::RequestBody.for_return(
       amount: amount,
       customer_id: customer_id,
       order_id: order_id,
-      payment_account_id: payment_account_id
+      payment_account_id: payment_account_id,
+      expiry_month: expiry_month,
+      expiry_year: expiry_year
     )
     Api::Request.new(
       endpoint: Api::Endpoints::RETURN,

data/lib/vantiv/api/live_transaction_response.rb

@@ -5,8 +5,10 @@ module Vantiv
         approved: '000',
         insufficient_funds: '110',
         invalid_account_number: '301',
+        pick_up_card: '303',
         expired_card: '305',
-        token_not_found: '822'
+        token_not_found: '822',
+        token_invalid: '823'
       }
 
       LIVE_TRANSACTION_RESPONSE_NAMES = {

data/lib/vantiv/api/request_body.rb

@@ -1,13 +1,17 @@
 module Vantiv
   module Api
     module RequestBody
-      def self.for_auth_or_sale(amount:, customer_id:, order_id:, payment_account_id:)
+      def self.for_auth_or_sale(amount:, customer_id:, order_id:, payment_account_id:, expiry_month:, expiry_year:)
         RequestBodyGenerator.run(
           transaction_element(
             amount: amount,
             order_id: order_id,
             customer_id: customer_id
           ),
+          card_element_for_live_transactions(
+            expiry_month: expiry_month,
+            expiry_year: expiry_year
+          ),
           payment_account_element(payment_account_id: payment_account_id)
         )
       end
@@ -30,7 +34,7 @@ module Vantiv
         )
       end
 
-      def self.for_return(amount:, customer_id:, order_id:, payment_account_id:)
+      def self.for_return(amount:, customer_id:, order_id:, payment_account_id:, expiry_month:, expiry_year:)
         transaction = transaction_element(
           amount: amount,
           order_id: order_id,
@@ -39,6 +43,10 @@ module Vantiv
         transaction["Transaction"].delete("PartialApprovedFlag")
         RequestBodyGenerator.run(
           transaction,
+          card_element_for_live_transactions(
+            expiry_month: expiry_month,
+            expiry_year: expiry_year
+          ),
           payment_account_element(payment_account_id: payment_account_id)
         )
       end
@@ -53,10 +61,10 @@ module Vantiv
         RequestBodyGenerator.run(
           {
             "Card" => {
-              "AccountNumber" => card_number,
-              "ExpirationMonth" => expiry_month,
-              "ExpirationYear" => expiry_year,
-              "CVV" => cvv
+              "AccountNumber" => card_number.to_s.gsub(/\D*/, ""),
+              "ExpirationMonth" => format_expiry(expiry_month),
+              "ExpirationYear" => format_expiry(expiry_year),
+              "CVV" => cvv.to_s
             }
           }
         )
@@ -74,6 +82,15 @@ module Vantiv
         }
       end
 
+      def self.card_element_for_live_transactions(expiry_month:, expiry_year:)
+        {
+          "Card" => {
+            "ExpirationMonth" => format_expiry(expiry_month),
+            "ExpirationYear" => format_expiry(expiry_year)
+          }
+        }
+      end
+
       def self.tied_transaction_element(transaction_id:, amount: nil)
         res = {
           "Transaction" => {
@@ -89,7 +106,7 @@ module Vantiv
       def self.transaction_element(amount:, customer_id:, order_id:)
         {
           "Transaction" => {
-            "ReferenceNumber" => order_id,
+            "ReferenceNumber" => order_id.to_s,
             "TransactionAmount" => '%.2f' % (amount / 100.0),
             "OrderSource" => Vantiv.order_source,
             "CustomerID" => customer_id,
@@ -105,7 +122,10 @@ module Vantiv
           }
         }
       end
-    end
 
+      def self.format_expiry(raw_value)
+        raw_value.to_s.reverse[0..1].reverse.rjust(2, "0")
+      end
+    end
   end
 end

data/lib/vantiv/api/response.rb

@@ -15,17 +15,17 @@ module Vantiv
       end
 
       def api_level_failure?
-        !httpok ||
-          # NOTE: this kind of sucks, but at the commit point, the DevHub
-          #   Api sometimes gives 200OK when litle had a parse issue and returns
-          #   'Error validating xml data...' instead of an actual error
-          @body["litleOnlineResponse"]["@message"].match(/error/i)
+        !httpok || litle_response_has_error?
       end
 
       def message
         litle_transaction_response["message"]
       end
 
+      def error_message
+        api_level_failure? ? api_level_error_message : message
+      end
+
       def response_code
         litle_transaction_response["response"]
       end
@@ -36,6 +36,17 @@ module Vantiv
 
       private
 
+      def litle_response_has_error?
+        # NOTE: this kind of sucks, but at the commit point, the DevHub
+        #   Api sometimes gives 200OK when litle had a parse issue and returns
+        #   'Error validating xml data...' instead of an actual error
+        !!@body["litleOnlineResponse"]["@message"].match(/error/i)
+      end
+
+      def api_level_error_message
+        body["errormsg"]
+      end
+
       attr_reader :transaction_response_name
 
       def litle_response

data/lib/vantiv/api/tokenization_response.rb

@@ -26,6 +26,10 @@ module Vantiv
         success? ? litle_transaction_response["PaymentAccountID"] : nil
       end
 
+      def card_type
+        success? ? litle_transaction_response["Type"] : nil
+      end
+
       def invalid_card_number?
         response_code == RESPONSE_CODES[:credit_card_number_invalid]
       end

data/lib/vantiv/mocked_sandbox/api_request.rb

@@ -1,6 +1,7 @@
 module Vantiv
   module MockedSandbox
     class ApiRequest
+      class EndpointNotMocked < StandardError; end
       class FixtureNotFound < StandardError; end
 
       def self.run(endpoint:, body:)
@@ -17,6 +18,22 @@ module Vantiv
           if direct_post?
             load_fixture("tokenize_by_direct_post", card_number)
           end
+        elsif endpoint == Api::Endpoints::SALE
+          load_fixture("auth_capture", card_number_from_payment_account_id)
+        elsif endpoint == Api::Endpoints::AUTHORIZATION
+          load_fixture("auth", card_number_from_payment_account_id)
+        elsif endpoint == Api::Endpoints::CAPTURE
+          load_fixture("capture")
+        elsif endpoint == Api::Endpoints::AUTH_REVERSAL
+          load_fixture("auth_reversal")
+        elsif endpoint == Api::Endpoints::CREDIT
+          load_fixture("credit")
+        elsif endpoint == Api::Endpoints::RETURN
+          load_fixture("refund", card_number_from_payment_account_id)
+        elsif endpoint == Api::Endpoints::VOID
+          load_fixture("void")
+        else
+          raise EndpointNotMocked.new("#{endpoint} is not mocked!")
         end
         {
           httpok: fixture["httpok"],
@@ -37,11 +54,22 @@ module Vantiv
         request_body["Card"]["AccountNumber"]
       end
 
-      def load_fixture(api_method, card_number)
+      def card_number_from_payment_account_id
+        TestCard.find_by_payment_account_id(
+          request_body["PaymentAccount"]["PaymentAccountID"]
+        ).card_number
+      end
+
+      def load_fixture(api_method, card_number = nil)
+        fixture_file_name = card_number ? "#{api_method}--#{card_number}" : api_method
         begin
-          self.fixture = File.open("#{MockedSandbox.fixtures_directory}#{api_method}--#{card_number}.json.erb", 'r') do |f|
+          self.fixture = File.open("#{MockedSandbox.fixtures_directory}#{fixture_file_name}.json.erb", 'r') do |f|
             raw_fixture = JSON.parse(f.read)
-            raw_fixture["response_body"] = raw_fixture["response_body"].to_json
+            # Prevent rails overridden version of to_json from encoding erb sepcial characters
+            raw_fixture["response_body"] = JSON::Ext::Generator::GeneratorMethods::Hash
+              .instance_method(:to_json)
+              .bind(raw_fixture["response_body"])
+              .call
             raw_fixture
           end
         rescue Errno::ENOENT