tappay_ruby 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42349c6d543ca1fa3a3bf6ead0e0f6eb9f281c80b28d35811058d2661d084f10
-  data.tar.gz: 82da8ed41bed6cfa50845bf8d9751fb796e8c2373e7978c9e60d35d560c2ccb8
+  metadata.gz: ef378bc35a591f5a2c295d7e2c530e174484e200fde3413978081103c4a7a8e3
+  data.tar.gz: b15ecfb7ad4c2f13093578a4bfc1a5468ad9b014b04fdc3e561128d6f33cfcbb
 SHA512:
-  metadata.gz: bfd22c013a32a3aa5c13bc28c84d94e21f49cdaf71657b6f7cf39e2c0240cff23fe61db6b396ccbb02cdf0571802318689b022bc796e4253ea799bc3837c1898
-  data.tar.gz: 4878db49a06c88e21fc6a5affa06eed404bf2a90feaaa82921824ad27a280977caafe05d945765a43ca21cba41dba78bf52d6bd7cbdf8d59706a62207accacc3
+  metadata.gz: 85a20b681bcd1ba1dd830506a3fab64c81652ae61703790f38866cc6d452926272151918914ffaca2d5f01b5dcdcf94cd251dfc707c77b7fa2926934f8622f8b
+  data.tar.gz: d72a42f89901fbe206b816d24397a6552326e509cb8c7959f05121091179fe0b50b7b61e075afc70a426e07ed1608e04cb1ae8c67a4c1cc50c3a8e7e3806b43f

data/README.md

@@ -1,5 +1,6 @@
 # TapPay Ruby Gem
 
+![Gem Version](https://img.shields.io/gem/v/tappay_ruby)
 [![RSpec](https://github.com/7a6163/tappay/actions/workflows/rspec.yml/badge.svg)](https://github.com/7a6163/tappay/actions/workflows/rspec.yml)
 [![codecov](https://codecov.io/gh/7a6163/tappay/branch/main/graph/badge.svg)](https://codecov.io/gh/7a6163/tappay)
 
@@ -197,6 +198,24 @@ if result['status'] == 0
 end
 ```
 
+## URL Properties
+
+The `result_url` (JSONObject) property is required when using LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付, or when three_domain_secure is true. It contains the following URL fields:
+
+```json
+{
+  "frontend_redirect_url": "https://example.com/redirect",  // Required - URL where consumer will be redirected after completing the transaction
+  "backend_notify_url": "https://example.com/notify",      // Required - URL where your server receives transaction results (only port 443)
+  "go_back_url": "https://example.com/back"               // Optional - URL for 3D verification error cases (E.SUN, Cathay United, Taishin banks)
+}
+```
+
+- `frontend_redirect_url` (String): After the consumer completes the transaction process in LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付, or 3D verification, they will be redirected to this frontend URL. Must start with https.
+
+- `backend_notify_url` (String): URL where your server receives transaction results. Must start with https and only supports port 443.
+
+- `go_back_url` (String): For 3D verification transactions, this URL is used when consumers are redirected to the TapPay Error page due to improper operation. This scenario only occurs with E.SUN Bank, Cathay United Bank, and Taishin Bank. You can define this URL in the transaction request or set it in TapPay Portal > Developer Content > System Settings > Redirect Link Settings. It's strongly recommended to define this field for 3D transactions to ensure consumers can return to complete the transaction or view results.
+
 ## Usage
 
 ### Pay by Prime
@@ -224,7 +243,7 @@ if result['status'] == 0
     card_token = result['card_secret']['card_token']
     # Store card_key and card_token securely for future payments
   end
-  
+
   # Handle payment URL if present (for 3D Secure, LINE Pay, JKO Pay)
   if result['payment_url']
     redirect_to result['payment_url']
@@ -324,6 +343,36 @@ rescue Tappay::ValidationError => e
 end
 ```
 
+### Example Usage with result_url
+
+```ruby
+# Example of payment with result_url for LINE Pay
+result = Tappay::LinePay::Pay.create(
+  prime: 'prime_from_tappay_sdk',
+  amount: 100,
+  merchant_id: 'your_merchant_id',
+  details: 'Product Item',
+  result_url: {
+    frontend_redirect_url: 'https://example.com/payment/complete',
+    backend_notify_url: 'https://example.com/payment/notify',
+    go_back_url: 'https://example.com/payment/error'
+  }
+)
+
+# Example of payment with result_url for 3D verification
+result = Tappay::CreditCard::Pay.by_prime(
+  prime: 'prime_from_tappay_sdk',
+  amount: 100,
+  merchant_id: 'your_merchant_id',
+  three_domain_secure: true,
+  result_url: {
+    frontend_redirect_url: 'https://example.com/3d/complete',
+    backend_notify_url: 'https://example.com/3d/notify',
+    go_back_url: 'https://example.com/3d/error'
+  }
+)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

data/lib/tappay/credit_card/instalment.rb

@@ -23,7 +23,12 @@ module Tappay
       end
 
       def endpoint_url
-        Tappay::Endpoints::CreditCard.payment_by_prime_url
+        Tappay::Endpoints::Payment.pay_by_prime_url
+      end
+
+      def validate_options!
+        super
+        validate_result_url_for_instalment!
       end
 
       private
@@ -31,6 +36,14 @@ module Tappay
       def additional_required_options
         [:prime, :cardholder, :instalment]
       end
+
+      def validate_result_url_for_instalment!
+        return if options[:result_url] && 
+                 options[:result_url][:frontend_redirect_url] && 
+                 options[:result_url][:backend_notify_url]
+
+        raise ValidationError, "result_url with frontend_redirect_url and backend_notify_url is required for instalment payments"
+      end
     end
 
     class InstalmentByToken < PaymentBase
@@ -47,7 +60,12 @@ module Tappay
       end
 
       def endpoint_url
-        Tappay::Endpoints::CreditCard.payment_by_token_url
+        Tappay::Endpoints::Payment.pay_by_token_url
+      end
+
+      def validate_options!
+        super
+        validate_result_url_for_instalment!
       end
 
       private
@@ -55,6 +73,14 @@ module Tappay
       def additional_required_options
         [:card_key, :card_token, :instalment]
       end
+
+      def validate_result_url_for_instalment!
+        return if options[:result_url] && 
+                 options[:result_url][:frontend_redirect_url] && 
+                 options[:result_url][:backend_notify_url]
+
+        raise ValidationError, "result_url with frontend_redirect_url and backend_notify_url is required for instalment payments"
+      end
     end
   end
 end

data/lib/tappay/credit_card/pay.rb

@@ -1,107 +1,9 @@
-module Tappay
-  module CreditCard
-    class PaymentBase < Client
-      def initialize(options = {})
-        super
-        validate_options!
-      end
-
-      def execute
-        post(endpoint_url, payment_data)
-      end
-
-      protected
-
-      def endpoint_url
-        raise NotImplementedError, "Subclass must implement abstract method 'endpoint_url'"
-      end
-
-      def payment_data
-        # Check configuration conflicts first
-        if Tappay.configuration.merchant_group_id && Tappay.configuration.merchant_id
-          raise Tappay::ValidationError, "merchant_group_id and merchant_id cannot be used together"
-        end
-
-        # Get values from options
-        opt_group_id = options[:merchant_group_id]
-        opt_merchant_id = options[:merchant_id]
-
-        # Check for conflicts in options
-        if opt_group_id && opt_merchant_id
-          raise Tappay::ValidationError, "merchant_group_id and merchant_id cannot be used together"
-        end
-
-        # If options has any ID, use it exclusively
-        if opt_group_id || opt_merchant_id
-          merchant_group_id = opt_group_id
-          merchant_id = opt_merchant_id
-        else
-          # If no options, use configuration
-          merchant_group_id = Tappay.configuration.merchant_group_id
-          merchant_id = Tappay.configuration.merchant_id
-        end
-
-        # Check if at least one is provided
-        unless merchant_group_id || merchant_id
-          raise Tappay::ValidationError, "Either merchant_group_id or merchant_id must be provided"
-        end
-
-        {
-          partner_key: Tappay.configuration.partner_key,
-          amount: options[:amount],
-          details: options[:details],
-          currency: options[:currency] || 'TWD',
-          order_number: options[:order_number],
-          three_domain_secure: options[:three_domain_secure] || false
-        }.tap do |data|
-          if merchant_group_id
-            data[:merchant_group_id] = merchant_group_id
-          else
-            data[:merchant_id] = merchant_id
-          end
-          data[:cardholder] = card_holder_data if options[:cardholder]
-          data[:instalment] = options[:instalment] if options[:instalment]
-        end
-      end
+# frozen_string_literal: true
 
-      def card_holder_data
-        return nil unless options[:cardholder]
-
-        case options[:cardholder]
-        when CardHolder
-          options[:cardholder].to_h
-        when Hash
-          options[:cardholder]
-        else
-          raise ValidationError, "Invalid cardholder format"
-        end
-      end
-
-      def validate_options!
-        required = base_required_options + additional_required_options
-        missing = required.select { |key| options[key].nil? }
-        raise ValidationError, "Missing required options: #{missing.join(', ')}" if missing.any?
-
-        validate_instalment! if options[:instalment]
-      end
-
-      private
-
-      def base_required_options
-        [:amount, :details]
-      end
-
-      def additional_required_options
-        []
-      end
-
-      def validate_instalment!
-        unless options[:instalment].to_i.between?(1, 12)
-          raise ValidationError, "Invalid instalment value. Must be between 1 and 12"
-        end
-      end
-    end
+require 'tappay/payment_base'
 
+module Tappay
+  module CreditCard
     class Pay < PaymentBase
       def self.by_prime(options = {})
         PayByPrime.new(options)
@@ -121,7 +23,7 @@ module Tappay
       end
 
       def endpoint_url
-        Tappay::Endpoints::CreditCard.payment_by_prime_url
+        Tappay::Endpoints::Payment.pay_by_prime_url
       end
 
       private
@@ -140,7 +42,7 @@ module Tappay
       end
 
       def endpoint_url
-        Tappay::Endpoints::CreditCard.payment_by_token_url
+        Tappay::Endpoints::Payment.pay_by_token_url
       end
 
       private

data/lib/tappay/endpoints.rb

@@ -12,16 +12,20 @@ module Tappay
       end
     end
 
-    module CreditCard
+    module Payment
       class << self
-        def payment_by_prime_url
+        def pay_by_prime_url
           "#{Endpoints.base_url}/tpc/payment/pay-by-prime"
         end
 
-        def payment_by_token_url
+        def pay_by_token_url
           "#{Endpoints.base_url}/tpc/payment/pay-by-token"
         end
+      end
+    end
 
+    module CreditCard
+      class << self
         def refund_url
           "#{Endpoints.base_url}/tpc/transaction/refund"
         end
@@ -55,5 +59,17 @@ module Tappay
         end
       end
     end
+
+    module LinePay
+      class << self
+        def redirect_url
+          "#{Endpoints.base_url}/tpc/payment/redirect"
+        end
+
+        def query_url
+          "#{Endpoints.base_url}/tpc/transaction/query"
+        end
+      end
+    end
   end
 end

data/lib/tappay/line_pay/pay.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'tappay/payment_base'
+
+module Tappay
+  module LinePay
+    class Pay < PaymentBase
+      def payment_data
+        super.merge(
+          prime: options[:prime],
+          result_url: {
+            frontend_redirect_url: options[:frontend_redirect_url],
+            backend_notify_url: options[:backend_notify_url]
+          },
+          remember: options[:remember] || false
+        )
+      end
+
+      def endpoint_url
+        Tappay::Endpoints::Payment.pay_by_prime_url
+      end
+
+      private
+
+      def additional_required_options
+        [:prime, :frontend_redirect_url, :backend_notify_url]
+      end
+    end
+  end
+end

data/lib/tappay/payment_base.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tappay
+  class PaymentBase < Client
+    def initialize(options = {})
+      super
+      validate_options!
+    end
+
+    def execute
+      post(endpoint_url, payment_data)
+    end
+
+    protected
+
+    def endpoint_url
+      raise NotImplementedError, "Subclass must implement abstract method 'endpoint_url'"
+    end
+
+    def payment_data
+      # Check configuration conflicts first
+      if Tappay.configuration.merchant_group_id && Tappay.configuration.merchant_id
+        raise Tappay::ValidationError, "merchant_group_id and merchant_id cannot be used together"
+      end
+
+      # Get values from options
+      opt_group_id = options[:merchant_group_id]
+      opt_merchant_id = options[:merchant_id]
+
+      # Check for conflicts in options
+      if opt_group_id && opt_merchant_id
+        raise Tappay::ValidationError, "merchant_group_id and merchant_id cannot be used together"
+      end
+
+      # If options has any ID, use it exclusively
+      if opt_group_id || opt_merchant_id
+        merchant_group_id = opt_group_id
+        merchant_id = opt_merchant_id
+      else
+        # If no options, use configuration
+        merchant_group_id = Tappay.configuration.merchant_group_id
+        merchant_id = Tappay.configuration.merchant_id
+      end
+
+      # Check if at least one is provided
+      unless merchant_group_id || merchant_id
+        raise Tappay::ValidationError, "Either merchant_group_id or merchant_id must be provided"
+      end
+
+      {
+        partner_key: Tappay.configuration.partner_key,
+        amount: options[:amount],
+        details: options[:details],
+        currency: options[:currency] || 'TWD',
+        order_number: options[:order_number],
+        three_domain_secure: options[:three_domain_secure] || false
+      }.tap do |data|
+        if merchant_group_id
+          data[:merchant_group_id] = merchant_group_id
+        else
+          data[:merchant_id] = merchant_id
+        end
+        data[:cardholder] = card_holder_data if options[:cardholder]
+        data[:instalment] = options[:instalment] if options[:instalment]
+        data[:result_url] = options[:result_url] if options[:result_url]
+      end
+    end
+
+    def card_holder_data
+      return nil unless options[:cardholder]
+
+      case options[:cardholder]
+      when CardHolder
+        options[:cardholder].to_h
+      when Hash
+        options[:cardholder]
+      else
+        raise ValidationError, "Invalid cardholder format"
+      end
+    end
+
+    def validate_options!
+      required = base_required_options + additional_required_options
+      missing = required.select { |key| options[key].nil? }
+      raise ValidationError, "Missing required options: #{missing.join(', ')}" if missing.any?
+
+      validate_instalment! if options[:instalment]
+      validate_result_url! if options[:three_domain_secure]
+    end
+
+    private
+
+    def base_required_options
+      [:amount, :details]
+    end
+
+    def additional_required_options
+      []
+    end
+
+    def validate_instalment!
+      unless options[:instalment].to_i.between?(1, 12)
+        raise ValidationError, "Invalid instalment value. Must be between 1 and 12"
+      end
+    end
+
+    def validate_result_url!
+      return if options[:result_url] && 
+               options[:result_url][:frontend_redirect_url] && 
+               options[:result_url][:backend_notify_url]
+
+      raise ValidationError, "result_url with frontend_redirect_url and backend_notify_url is required when three_domain_secure is true"
+    end
+  end
+end

data/lib/tappay/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Tappay
-  VERSION = "0.5.1"
+  VERSION = "0.7.0"
 end

data/lib/tappay.rb

@@ -10,6 +10,7 @@ require_relative "tappay/transaction/query"
 require_relative "tappay/credit_card/pay"
 require_relative "tappay/credit_card/refund"
 require_relative "tappay/credit_card/instalment"
+require_relative "tappay/line_pay/pay"
 
 module Tappay
   class Error < StandardError; end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tappay_ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Zac
 bindir: exe
 cert_chain: []
-date: 2024-12-30 00:00:00.000000000 Z
+date: 2025-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -83,6 +83,8 @@ files:
 - lib/tappay/credit_card/refund.rb
 - lib/tappay/endpoints.rb
 - lib/tappay/errors.rb
+- lib/tappay/line_pay/pay.rb
+- lib/tappay/payment_base.rb
 - lib/tappay/transaction/query.rb
 - lib/tappay/version.rb
 - lib/tappay_ruby.rb