tappay_ruby 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cbe85ab3afecf239323a807b1a2d55311d1bcb3ad471a85681170eb52770a06
-  data.tar.gz: f9d027824f0691aeb7487febc2155d7e31d5a487d2fe3562b79bdb009ca401c9
+  metadata.gz: '079c12112d7324813f5fed82b293db20a238b0232a9b08e038189b76f523b745'
+  data.tar.gz: 3a980d58f677236213f6df7cecb3ef431ee2c352725b410e7279ef6e38796014
 SHA512:
-  metadata.gz: d98f0e74412ca52ecc67c9f9cf6a24a574f5d4f409aa0c4dda9f9e6ab073d3c775aeafda4cf49140e702e0e6c1e43add2843cda020a5190b40a504e6a5ec82ae
-  data.tar.gz: 3b13ec89b5d01fa9b92fe0c5586c89d17462aedeced858178333200c0417070cfe7285f9011da8b3dd2f3b366ac67c3fd45c6a5cb69494dc64325ed4e0aacdea
+  metadata.gz: 29470a1418a5bd920ae3c198b8581e1b6dfda7982bcfd7587f6a68c637a41762089d9336e2de15664b3f81618d9dd0bf2f632729df4cf65d140623c1e744338a
+  data.tar.gz: 8775276b65bdb9203c1c7621ed5da4147029387849fa0f758060b3339abd4868a1ffcb31110d411c166233ca955e1173ca4eda5c34c310c42660a6a8bff5778f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-2026 Zac
+
+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 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

@@ -46,6 +46,49 @@ Or install it yourself as:
 $ gem install tappay_ruby
 ```
 
+## Upgrading from 1.x to 2.0
+
+Four changes need action. Each replaces a silent wrong answer with a loud one.
+
+**Transaction query timestamps are milliseconds.** 1.x documented seconds.
+TapPay accepts a seconds-magnitude range but matches nothing against it, so
+`Transaction::Query` returned an empty list for every query. Multiply by 1000:
+
+```ruby
+# before - always returned []
+time: { start_time: 30.days.ago.to_i, end_time: Time.now.to_i }
+# after
+time: { start_time: 30.days.ago.to_i * 1000, end_time: Time.now.to_i * 1000 }
+```
+
+Out-of-scale values now raise `Tappay::ValidationError` rather than returning
+nothing.
+
+**`Response#success?` reflects TapPay's `status`, not the HTTP code.** TapPay
+answers a declined card with HTTP 200 and a non-zero `status`, so 1.x reported
+failed payments as successful. If you were already checking
+`result['status'] == 0` yourself, nothing changes; you can now use `success?`
+instead. See [Checking the result](#checking-the-result) for what it does and
+does not promise.
+
+**Trade records carry every field TapPay returns.** 1.x kept 12 of roughly 32.
+`transaction_time` and `tsp` are gone - they matched nothing in the response
+and were always `nil`. The transaction timestamp is `time`, in milliseconds.
+Fields such as `refunded_amount`, `is_captured`, `original_amount`,
+`bank_result_code` and `bank_result_msg` are now available.
+
+**Some public constants are gone.** Grep before upgrading:
+
+```bash
+rg 'Tappay::(PaymentError|RefundError|QueryError)|api_version|Endpoints::Bind|trade_history_url|cap_url'
+```
+
+`Tappay::PaymentError`, `Tappay::RefundError` and `Tappay::QueryError` were
+never raised by the gem, so they never caught anything - use `success?`.
+Removing them matters because `rescue Tappay::PaymentError` now raises
+`NameError` when the rescue clause is evaluated, which happens only once some
+other exception is already in flight.
+
 ## Configuration
 
 There are several ways to configure the gem:
@@ -59,6 +102,7 @@ Tappay.configure do |config|
   config.merchant_id = 'YOUR_MERCHANT_ID'
   config.jko_pay_merchant_id = 'YOUR_JKO_PAY_MERCHANT_ID'  # Optional, falls back to merchant_id if not set
   config.line_pay_merchant_id = 'YOUR_LINE_PAY_MERCHANT_ID'  # Optional, falls back to merchant_id if not set
+  config.currency = 'TWD'  # Optional, default for payments that do not pass :currency
 end
 ```
 
@@ -103,7 +147,7 @@ result = Tappay::CreditCard::Pay.by_prime(
     name: 'Test User',
     email: 'test@example.com'
   }
-)
+).execute
 
 # Payment with saved card token
 result = Tappay::CreditCard::Pay.by_token(
@@ -113,7 +157,7 @@ result = Tappay::CreditCard::Pay.by_token(
   currency: 'TWD',
   details: 'Order Details',
   ccv_prime: 'ccv_prime_from_tappay'  # Optional: CVV verification
-)
+).execute
 
 # Instalment payment (3-30 months)
 result = Tappay::CreditCard::Instalment.by_prime(
@@ -126,7 +170,7 @@ result = Tappay::CreditCard::Instalment.by_prime(
     name: 'Test User',
     email: 'test@example.com'
   }
-)
+).execute
 
 # Instalment payment with saved card token
 result = Tappay::CreditCard::Instalment.by_token(
@@ -136,7 +180,7 @@ result = Tappay::CreditCard::Instalment.by_token(
   instalment: 12,
   details: 'Order Details',
   ccv_prime: 'ccv_prime_from_tappay'  # Optional: CVV verification
-)
+).execute
 ```
 
 ### Line Pay
@@ -247,11 +291,11 @@ result = payment.execute
 Query transaction records with required time range:
 
 ```ruby
-# Query transactions within a specific time range
+# time is required; TapPay caps the range at 90 days
 result = Tappay::Transaction::Query.new(
   time: {
-    start_time: 1706198400,  # Unix timestamp for start time
-    end_time: 1706284800     # Unix timestamp for end time
+    start_time: 1706198400000,  # Unix timestamp in MILLISECONDS
+    end_time: 1706284800000     # Unix timestamp in MILLISECONDS
   },
   order_number: 'ORDER123',  # Optional: filter by order number
   records_per_page: 50,      # Optional: default is 50
@@ -270,7 +314,65 @@ result[:trade_records].each do |record|
 end
 ```
 
-Note: The `time` parameter with both `start_time` and `end_time` is required for querying transactions.
+Every field TapPay returns for a trade record is passed through verbatim, with
+keys symbolized (recursively, so nested objects like `refund_info` and
+`card_info` are symbol-keyed too). The gem does not whitelist fields, so
+`refunded_amount`, `is_captured`, `bank_result_code`, `bank_result_msg`,
+`original_amount`, `time` and the various `*_millis` timestamps are all
+available, and fields TapPay adds later work without a gem upgrade. The exact
+key set varies by payment method. See
+`spec/fixtures/transaction_query_response.json` for a real response.
+
+Two things worth knowing about the records:
+
+- `amount` is what remains after refunds. A fully refunded transaction reports
+  `amount: 0` with `original_amount` and `refunded_amount` both set to the
+  original charge, so compare `refunded_amount` against `original_amount` to
+  tell a partial refund from a full one.
+- The transaction timestamp is `time` (milliseconds). `transaction_complete_millis`
+  is `0` on records that have not completed.
+
+`status` in the result is TapPay's, not an HTTP code, and **`2` means "End of
+list", not "nothing found"** - it is what you get on the last page, records
+included. Verified against the sandbox: a query returning 33 records answered
+`status: 2`. Treat `0` and `2` alike and read `trade_records`; checking
+`status == 0` before looking drops the final page. `Response#success?` is
+`status == 0`, so it is the wrong question for a query - `Transaction::Query`
+does not use it.
+
+Note: `time` is required and its timestamps are in **milliseconds**, not
+seconds. Seconds are accepted by TapPay but match nothing, so the gem rejects
+them with a `ValidationError` rather than returning an empty list. TapPay caps
+the range at 90 days.
+
+### Checking the result
+
+`Pay.by_prime` and friends return an unexecuted payment object - call
+`execute` to send the request. TapPay reports business failures (declined
+card, insufficient funds, expired card) as **HTTP 200 with a non-zero
+`status`**, so `success?` checks that status rather than the HTTP code:
+
+```ruby
+result = Tappay::CreditCard::Pay.by_prime(...).execute
+
+if result.success?          # status == 0
+  result['rec_trade_id']
+else
+  result['status']          # e.g. 10003
+  result['msg']             # e.g. 'Card is declined'
+end
+```
+
+**`success?` does not mean the money has moved.** It means TapPay accepted and
+processed the request. What that implies depends on the payment method:
+
+- **Credit card** - the transaction was authorised. Capture is asynchronous;
+  confirm it with `is_captured` from a `Transaction::Query`.
+- **LINE Pay / JKO Pay / iPass Money** - only that a `payment_url` was created.
+  The customer has not paid yet. Redirect them to `result['payment_url']`, and
+  treat your `backend_notify_url` callback plus a `Transaction::Query` as the
+  authoritative answer. TapPay's own guidance is to query the Record API before
+  showing a result page to the customer.
 
 ### Error Handling
 
@@ -281,8 +383,12 @@ begin
   result = Tappay::CreditCard::Pay.by_prime(
     prime: 'prime_from_tappay_sdk',
     amount: 100,
+    details: 'Order Details',
     order_number: 'ORDER-123'
-  )
+  ).execute
+
+  # TapPay reports declined cards as HTTP 200 with a non-zero status.
+  raise "Payment failed: #{result['msg']}" unless result.success?
 rescue Tappay::ValidationError => e
   # Handle validation errors (e.g., missing required fields)
   puts "Validation error: #{e.message}"
@@ -292,9 +398,78 @@ rescue Tappay::Error => e
 end
 ```
 
+The gem raises `Tappay::ValidationError` (bad or missing options),
+`Tappay::ConfigurationError` (authentication rejected) and
+`Tappay::ConnectionError` (timeout, unreachable endpoint, unparseable
+response), all of which inherit from `Tappay::Error`. Business failures are
+not exceptions - check `success?`.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`bundle exec rspec` for the tests, or `bin/console` for an interactive prompt.
+
+### Mutation testing
+
+Line coverage says a line ran, not that anything checked what it did. Both bugs
+fixed in 2.0.0 - a field name that never matched the API and a time filter in
+the wrong unit - sat under 100% line coverage for the life of the gem.
+
+[Mutant](https://github.com/mbj/mutant) changes the source in small ways (flips
+a boolean, drops a call, swaps an operator) and reruns the suite. A mutation
+that survives marks behaviour nothing asserts.
+
+```bash
+bundle config set --local with mutant
+bundle install
+bundle exec mutant run
+```
+
+It needs Ruby >= 3.3, so it lives in an optional bundle group rather than the
+gemspec - the gem itself supports >= 2.7. Scope is `config/mutant.yml`:
+`Transaction::Query`, `Response`, and the two payment base classes that five
+payment methods now share.
+
+The current score is 95.34% (676 of 709). Mutant exits non-zero whenever
+anything survives, and the 33 survivors here are equivalent mutations that no
+test can distinguish - inside `module Tappay`, `Client.new` and
+`Tappay::Client.new` are the same call, and `is_a?(Hash)` and
+`instance_of?(Hash)` differ only for a Hash subclass nothing passes. Each one
+is listed in `config/mutant.yml` with its reason, and CI gates on the score
+rather than the exit code.
+
+If the score drops, an assertion went missing. Read the new survivor rather
+than lowering the floor: the first run here scored 77.90%, and every one of
+those gaps was genuine - including two tests that passed whether or not the
+code they covered was there at all.
+
+### Contract tests against the sandbox
+
+Stubbed tests assert the gem against its own assumptions, so they cannot catch
+the gem being wrong about TapPay. Every bug fixed in 2.0.0 was exactly that -
+a field name that did not exist, a time filter in the wrong unit - and all of
+them survived a suite with 100% line coverage. One real call catches the lot.
+
+```bash
+export TAPPAY_SANDBOX_PARTNER_KEY=...
+bundle exec rspec spec/contract --tag contract
+```
+
+The specs are excluded from the default run and skip with an explanation if
+the key is unset, so a clone without credentials behaves normally. Nothing is
+written: the Record API is read-only and needs only a partner key.
+
+They check that a millisecond window is accepted, that every field
+`spec/fixtures/transaction_query_response.json` claims still exists in the live
+response, that the transaction timestamp is `time` in milliseconds, and that
+the amounts and capture state refunds reconcile against are all present. New
+fields TapPay has added are reported rather than failed - the gem passes
+everything through, so they break nothing; the fixture just wants re-capturing.
+
+Only `Transaction::Query` is covered. Charging needs a `prime`, which the
+frontend SDK mints from a test card - it is single-use, expires in seconds, and
+there is no server-side way to obtain one, so payment and refund flows cannot
+be driven from a test suite without automating a browser.
 
 ## Contributing
 

data/lib/tappay/apple_pay/pay.rb

@@ -1,32 +1,9 @@
-require 'json'
+# frozen_string_literal: true
 
 module Tappay
   module ApplePay
-    class Pay < PaymentBase
-
-      def endpoint_url
-        Tappay::Endpoints::Payment.pay_by_prime_url
-      end
-
-      private
-
-      def get_merchant_id
-        return nil if Tappay.configuration.merchant_group_id
-
-        Tappay.configuration.apple_pay_merchant_id || super
-      end
-
-      def additional_required_options
-        [:prime, :cardholder]
-      end
-
-      protected
-
-      def payment_data
-        super.merge(
-          prime: options[:prime]
-        )
-      end
+    class Pay < PrimePayment
+      uses_merchant_id :apple_pay_merchant_id
     end
   end
 end

data/lib/tappay/client.rb

@@ -62,24 +62,48 @@ module Tappay
     attr_reader :code, :body, :headers
 
     def initialize(net_http_response)
-      @response = net_http_response
       @code = net_http_response.code.to_i
       @body = net_http_response.body
       @headers = net_http_response.to_hash
     end
 
+    # Every TapPay endpoint answers with a JSON object, so a body that is not
+    # one means something other than TapPay replied - a maintenance page, a
+    # proxy, a WAF. Returning the raw body instead turned
+    # `parsed_response['status']` into a String#[] substring search, which
+    # answers nil without complaining. Raise rather than hand back something
+    # that reads like a result.
     def parsed_response
-      @parsed_response ||= JSON.parse(@body)
+      @parsed_response ||= JSON.parse(@body.to_s).then do |parsed|
+        raise ConnectionError, unexpected_body unless parsed.is_a?(Hash)
+
+        parsed
+      end
     rescue JSON::ParserError
-      @body
+      raise ConnectionError, unexpected_body
     end
 
+    # TapPay signals business failures (declined card, insufficient funds,
+    # expired card) with HTTP 200 and a non-zero `status`, so the HTTP code
+    # alone says nothing. Client only builds a Response once validate_response
+    # has accepted the HTTP code, so `status` is the only question left.
+    #
+    # This means "TapPay processed the request", not "the money moved": for a
+    # credit card the transaction is authorised but capture is asynchronous,
+    # and for LINE Pay / JKO Pay / iPass Money it means only that a payment_url
+    # was created and the customer has yet to pay. Confirm with Transaction::Query.
     def success?
-      @code >= 200 && @code < 300
+      parsed_response['status'] == 0
     end
 
     def [](key)
       parsed_response[key]
     end
+
+    private
+
+    def unexpected_body
+      "Expected a JSON object from TapPay, got: #{@body.to_s[0, 200]}"
+    end
   end
 end

data/lib/tappay/configuration.rb

@@ -6,15 +6,9 @@ module Tappay
                  :line_pay_merchant_id, :jko_pay_merchant_id, :currency,
                  :google_pay_merchant_id, :apple_pay_merchant_id,
                  :ipass_money_merchant_id
-    attr_writer :api_version
 
     def initialize
       @mode = :sandbox
-      @api_version = '3'
-    end
-
-    def api_version
-      @api_version.to_s
     end
 
     def sandbox?

data/lib/tappay/credit_card/pay.rb

@@ -49,7 +49,7 @@ module Tappay
       private
 
       def additional_required_options
-        [:card_key, :card_token, :currency]
+        [:card_key, :card_token]
       end
     end
   end

data/lib/tappay/endpoints.rb

@@ -33,26 +33,6 @@ module Tappay
         def query_url
           "#{Endpoints.base_url}/tpc/transaction/query"
         end
-
-        def trade_history_url
-          "#{Endpoints.base_url}/tpc/transaction/trade-history"
-        end
-
-        def cap_url
-          "#{Endpoints.base_url}/tpc/transaction/cap"
-        end
-      end
-    end
-
-    module Bind
-      class << self
-        def bind_card_url
-          "#{Endpoints.base_url}/tpc/card/bind"
-        end
-
-        def remove_card_url
-          "#{Endpoints.base_url}/tpc/card/remove"
-        end
       end
     end
   end

data/lib/tappay/errors.rb

@@ -4,7 +4,4 @@ module Tappay
   class ConfigurationError < Error; end
   class ConnectionError < Error; end
   class ValidationError < Error; end
-  class PaymentError < Error; end
-  class RefundError < Error; end
-  class QueryError < Error; end
 end

data/lib/tappay/google_pay/pay.rb

@@ -1,32 +1,9 @@
-require 'json'
+# frozen_string_literal: true
 
 module Tappay
   module GooglePay
-    class Pay < PaymentBase
-
-      def endpoint_url
-        Tappay::Endpoints::Payment.pay_by_prime_url
-      end
-
-      private
-
-      def get_merchant_id
-        return nil if Tappay.configuration.merchant_group_id
-
-        Tappay.configuration.google_pay_merchant_id || super
-      end
-
-      def additional_required_options
-        [:prime, :cardholder]
-      end
-
-      protected
-
-      def payment_data
-        super.merge(
-          prime: options[:prime]
-        )
-      end
+    class Pay < PrimePayment
+      uses_merchant_id :google_pay_merchant_id
     end
   end
 end

data/lib/tappay/ipass_money/pay.rb

@@ -2,63 +2,8 @@
 
 module Tappay
   module IPassMoney
-    class Pay < PaymentBase
-      def endpoint_url
-        Tappay::Endpoints::Payment.pay_by_prime_url
-      end
-
-      private
-
-      def get_merchant_id
-        # If merchant_group_id is set, it takes precedence
-        return nil if Tappay.configuration.merchant_group_id
-
-        # Otherwise, use ipass_money_merchant_id or fall back to default merchant_id
-        Tappay.configuration.ipass_money_merchant_id || super
-      end
-
-      def additional_required_options
-        [:prime, :frontend_redirect_url, :backend_notify_url, :cardholder]
-      end
-
-      def validate_options!
-        super
-        validate_result_url_format!
-      end
-
-      def validate_result_url_format!
-        # First validate that if result_url is provided, it's a hash with required fields
-        if options.key?(:result_url)
-          raise ValidationError, "result_url must be a hash" unless options[:result_url].is_a?(Hash)
-
-          result_url = options[:result_url]
-          required_fields = %w[frontend_redirect_url backend_notify_url]
-          missing = required_fields.select { |field| result_url[field.to_sym].nil? && result_url[field].nil? }
-
-          if missing.any?
-            raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-          end
-        end
-
-        # Then validate frontend_redirect_url and backend_notify_url are present and not empty
-        if !options[:frontend_redirect_url].to_s.strip.empty? && !options[:backend_notify_url].to_s.strip.empty?
-          return
-        end
-
-        raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-      end
-
-      protected
-
-      def payment_data
-        super.merge(
-          prime: options[:prime],
-          result_url: {
-            frontend_redirect_url: options[:frontend_redirect_url],
-            backend_notify_url: options[:backend_notify_url]
-          }
-        )
-      end
+    class Pay < RedirectPayment
+      uses_merchant_id :ipass_money_merchant_id
     end
   end
 end

data/lib/tappay/jko_pay/pay.rb

@@ -2,63 +2,8 @@
 
 module Tappay
   module JkoPay
-    class Pay < PaymentBase
-      def endpoint_url
-        Tappay::Endpoints::Payment.pay_by_prime_url
-      end
-
-      private
-
-      def get_merchant_id
-        # If merchant_group_id is set, it takes precedence
-        return nil if Tappay.configuration.merchant_group_id
-
-        # Otherwise, use jko_pay_merchant_id or fall back to default merchant_id
-        Tappay.configuration.jko_pay_merchant_id || super
-      end
-
-      def additional_required_options
-        [:prime, :frontend_redirect_url, :backend_notify_url, :cardholder]
-      end
-
-      def validate_options!
-        super
-        validate_result_url_format!
-      end
-
-      def validate_result_url_format!
-        # First validate that if result_url is provided, it's a hash with required fields
-        if options.key?(:result_url)
-          raise ValidationError, "result_url must be a hash" unless options[:result_url].is_a?(Hash)
-
-          result_url = options[:result_url]
-          required_fields = %w[frontend_redirect_url backend_notify_url]
-          missing = required_fields.select { |field| result_url[field.to_sym].nil? && result_url[field].nil? }
-
-          if missing.any?
-            raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-          end
-        end
-
-        # Then validate frontend_redirect_url and backend_notify_url are present and not empty
-        if !options[:frontend_redirect_url].to_s.strip.empty? && !options[:backend_notify_url].to_s.strip.empty?
-          return
-        end
-
-        raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-      end
-
-      protected
-
-      def payment_data
-        super.merge(
-          prime: options[:prime],
-          result_url: {
-            frontend_redirect_url: options[:frontend_redirect_url],
-            backend_notify_url: options[:backend_notify_url]
-          }
-        )
-      end
+    class Pay < RedirectPayment
+      uses_merchant_id :jko_pay_merchant_id
     end
   end
 end

data/lib/tappay/line_pay/pay.rb

@@ -2,63 +2,8 @@
 
 module Tappay
   module LinePay
-    class Pay < PaymentBase
-      def endpoint_url
-        Tappay::Endpoints::Payment.pay_by_prime_url
-      end
-
-      private
-
-      def get_merchant_id
-        # If merchant_group_id is set, it takes precedence
-        return nil if Tappay.configuration.merchant_group_id
-
-        # Otherwise, use line_pay_merchant_id or fall back to default merchant_id
-        Tappay.configuration.line_pay_merchant_id || super
-      end
-
-      def additional_required_options
-        [:prime, :frontend_redirect_url, :backend_notify_url, :cardholder]
-      end
-
-      def validate_options!
-        super
-        validate_result_url_format!
-      end
-
-      def validate_result_url_format!
-        # First validate that if result_url is provided, it's a hash with required fields
-        if options.key?(:result_url)
-          raise ValidationError, "result_url must be a hash" unless options[:result_url].is_a?(Hash)
-
-          result_url = options[:result_url]
-          required_fields = %w[frontend_redirect_url backend_notify_url]
-          missing = required_fields.select { |field| result_url[field.to_sym].nil? && result_url[field].nil? }
-
-          if missing.any?
-            raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-          end
-        end
-
-        # Then validate frontend_redirect_url and backend_notify_url are present and not empty
-        if !options[:frontend_redirect_url].to_s.strip.empty? && !options[:backend_notify_url].to_s.strip.empty?
-          return
-        end
-
-        raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
-      end
-
-      protected
-
-      def payment_data
-        super.merge(
-          prime: options[:prime],
-          result_url: {
-            frontend_redirect_url: options[:frontend_redirect_url],
-            backend_notify_url: options[:backend_notify_url]
-          }
-        )
-      end
+    class Pay < RedirectPayment
+      uses_merchant_id :line_pay_merchant_id
     end
   end
 end

data/lib/tappay/payment_base.rb

@@ -4,6 +4,22 @@ module Tappay
   class PaymentBase < Client
     VALID_INSTALMENT_VALUES = [0, 3, 6, 12, 18, 24, 30].freeze
 
+    class << self
+      # Some payment methods get their own merchant ID from TapPay. Declaring
+      # the config key here replaces a get_merchant_id override per class.
+      def uses_merchant_id(key)
+        @merchant_id_key = key
+      end
+
+      # Walks the ancestry, because a class-level ivar is not inherited and
+      # the get_merchant_id overrides this replaced were. Without this, a
+      # subclass of a payment class silently charges the default merchant.
+      def merchant_id_key
+        @merchant_id_key ||
+          (superclass.merchant_id_key if superclass.respond_to?(:merchant_id_key))
+      end
+    end
+
     def initialize(options = {})
       super
       validate_options!
@@ -36,7 +52,7 @@ module Tappay
         partner_key: Tappay.configuration.partner_key,
         amount: options[:amount],
         details: options[:details],
-        currency: options[:currency] || 'TWD',
+        currency: options[:currency] || Tappay.configuration.currency || 'TWD',
         order_number: options[:order_number],
         three_domain_secure: options[:three_domain_secure] || false
       }).tap do |data|
@@ -82,11 +98,11 @@ module Tappay
     end
 
     def get_merchant_id
-      # If merchant_group_id is set, it takes precedence over all other merchant IDs
+      # merchant_group_id takes precedence over every merchant ID.
       return nil if Tappay.configuration.merchant_group_id
 
-      # Otherwise, return the default merchant_id
-      Tappay.configuration.merchant_id
+      key = self.class.merchant_id_key
+      (key && Tappay.configuration.public_send(key)) || Tappay.configuration.merchant_id
     end
 
     def base_required_options
@@ -105,7 +121,12 @@ module Tappay
     end
 
     def validate_result_url!
-      result_url = options[:result_url]
+      validate_result_url_hash!(options[:result_url])
+    end
+
+    # The one definition of what a result_url hash has to look like. Both the
+    # 3DS path above and the redirect payment methods check against this.
+    def validate_result_url_hash!(result_url)
       raise ValidationError, "result_url must be a hash" unless result_url.is_a?(Hash)
 
       required_fields = %w[frontend_redirect_url backend_notify_url]

data/lib/tappay/prime_payment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Tappay
+  # Payment methods charged with a prime from TapPay's SDK, where TapPay also
+  # requires cardholder details. Apple Pay and Google Pay are this and nothing
+  # more; the redirect methods add a result_url on top.
+  class PrimePayment < PaymentBase
+    def endpoint_url
+      Tappay::Endpoints::Payment.pay_by_prime_url
+    end
+
+    protected
+
+    def payment_data
+      super.merge(prime: options[:prime])
+    end
+
+    private
+
+    def additional_required_options
+      [:prime, :cardholder]
+    end
+  end
+end

data/lib/tappay/redirect_payment.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Tappay
+  # Payment methods where TapPay answers with a payment_url and the customer
+  # finishes paying on the provider's own page: LINE Pay, JKO Pay, iPass Money.
+  # A status of 0 here means the URL was created, not that anyone has paid.
+  class RedirectPayment < PrimePayment
+    protected
+
+    def payment_data
+      super.merge(
+        result_url: {
+          frontend_redirect_url: options[:frontend_redirect_url],
+          backend_notify_url: options[:backend_notify_url]
+        }
+      )
+    end
+
+    private
+
+    def additional_required_options
+      super + [:frontend_redirect_url, :backend_notify_url]
+    end
+
+    def validate_options!
+      super
+      validate_redirect_urls!
+    end
+
+    def validate_redirect_urls!
+      validate_result_url_hash!(options[:result_url]) if options.key?(:result_url)
+
+      return unless options[:frontend_redirect_url].to_s.strip.empty? ||
+                    options[:backend_notify_url].to_s.strip.empty?
+
+      raise ValidationError, "result_url must contain both frontend_redirect_url and backend_notify_url"
+    end
+  end
+end

data/lib/tappay/transaction/query.rb

@@ -3,6 +3,14 @@
 module Tappay
   module Transaction
     class Query
+      # TapPay's time filter is in milliseconds. Values at the wrong scale are
+      # accepted by the API but match nothing (seconds land in 1970,
+      # microseconds in the year 50000), so reject them loudly rather than
+      # returning an empty list.
+      # ponytail: magnitude heuristic, only valid for 1973-03-03 .. 5138-11-16
+      MILLIS_FLOOR = 100_000_000_000
+      MILLIS_CEILING = 100_000_000_000_000
+
       def initialize(time:, order_number: nil, bank_transaction_id: nil, records_per_page: 50, page: 0, order_by: nil)
         @time = validate_time!(time)
         @order_number = order_number
@@ -16,15 +24,9 @@ module Tappay
         client = Tappay::Client.new
         response = client.post(Endpoints::Transaction.query_url, request_params)
 
-        {
-          status: response['status'],
-          msg: response['msg'],
-          records_per_page: response['records_per_page'],
-          page: response['page'],
-          total_page_count: response['total_page_count'],
-          number_of_transactions: response['number_of_transactions'],
-          trade_records: parse_trade_records(response['trade_records'])
-        }
+        result = symbolize_keys(response.parsed_response)
+        result[:trade_records] ||= []
+        result
       end
 
       private
@@ -53,7 +55,17 @@ module Tappay
         end
 
         unless time[:start_time].is_a?(Integer) && time[:end_time].is_a?(Integer)
-          raise Tappay::ValidationError, "start_time and end_time must be Unix timestamps (integers)"
+          raise Tappay::ValidationError, "start_time and end_time must be Unix timestamps in milliseconds (integers)"
+        end
+
+        if time[:start_time] < MILLIS_FLOOR || time[:end_time] < MILLIS_FLOOR
+          raise Tappay::ValidationError,
+                "start_time and end_time must be in milliseconds, not seconds (multiply by 1000)"
+        end
+
+        if time[:start_time] >= MILLIS_CEILING || time[:end_time] >= MILLIS_CEILING
+          raise Tappay::ValidationError,
+                "start_time and end_time are too large to be milliseconds (microseconds?)"
         end
 
         if time[:start_time] > time[:end_time]
@@ -63,36 +75,16 @@ module Tappay
         time
       end
 
-      def parse_trade_records(records)
-        return [] unless records&.any?
-
-        records.map do |record|
-          {
-            record_status: record['record_status'],
-            rec_trade_id: record['rec_trade_id'],
-            amount: record['amount'],
-            currency: record['currency'],
-            order_number: record['order_number'],
-            bank_transaction_id: record['bank_transaction_id'],
-            auth_code: record['auth_code'],
-            cardholder: parse_cardholder(record['cardholder']),
-            merchant_id: record['merchant_id'],
-            transaction_time: record['transaction_time'],
-            tsp: record['tsp'],
-            card_identifier: record['card_identifier']
-          }
+      # Pass every field TapPay returns straight through, at the envelope level
+      # as well as per trade record. A whitelist silently drops new fields and
+      # silently returns nil for a mistyped key.
+      def symbolize_keys(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_sym, symbolize_keys(v)] }
+        when Array then value.map { |v| symbolize_keys(v) }
+        else value
         end
       end
-
-      def parse_cardholder(cardholder)
-        return unless cardholder
-
-        {
-          phone_number: cardholder['phone_number'],
-          name: cardholder['name'],
-          email: cardholder['email']
-        }
-      end
     end
   end
 end

data/lib/tappay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tappay
-  VERSION = '1.1.0'
+  VERSION = '2.0.0'
 end

data/lib/tappay.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'csv'
 require 'json'
 require 'net/http'
 require 'uri'
@@ -11,6 +10,8 @@ require_relative "tappay/client"
 require_relative "tappay/errors"
 require_relative "tappay/refund"
 require_relative "tappay/payment_base"
+require_relative "tappay/prime_payment"
+require_relative "tappay/redirect_payment"
 require_relative "tappay/card_holder"
 require_relative "tappay/endpoints"
 require_relative "tappay/transaction/query"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tappay_ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Zac
@@ -115,6 +115,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
 - README.md
 - lib/tappay.rb
 - lib/tappay/apple_pay/pay.rb
@@ -130,6 +131,8 @@ files:
 - lib/tappay/jko_pay/pay.rb
 - lib/tappay/line_pay/pay.rb
 - lib/tappay/payment_base.rb
+- lib/tappay/prime_payment.rb
+- lib/tappay/redirect_payment.rb
 - lib/tappay/refund.rb
 - lib/tappay/transaction/query.rb
 - lib/tappay/version.rb
@@ -155,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby wrapper for TapPay payment gateway
 test_files: []