tappay_ruby 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f75685c53cf95fc785a6486a6649ede92a9ab175b40c90c89349657e03bba98
+  data.tar.gz: 35462d55532c9ab7da45e9277e53ce91f9788f2e51a1999582b30b246815a2dd
+SHA512:
+  metadata.gz: 8a1f363e1665d9fd1640d8729a828a6f9978f9ef1e0becfbfb9d9d93ad5f9b94d1a516739a1c2f813d05ca323fa2e6654c8d371868f4bdcc53be10316d67ec76
+  data.tar.gz: 43499dda99a4af42cb4e81216550e41a5929630999455ddcc669a5fd16f2b89b639d1541c521e7228b5dccd79fc7572485d80f8e091e52dd72c44abadf795605

data/README.md

@@ -0,0 +1,267 @@
+# TapPay Ruby Gem
+
+A Ruby library for integrating with TapPay payment services. This gem provides a simple and elegant way to process payments, refunds, and handle instalments through TapPay's payment gateway.
+
+## Features
+
+- Credit card payments (one-time and tokenized)
+- Instalment payments
+- Refund processing
+- Transaction status queries
+- Comprehensive error handling
+- Configurable sandbox/production environments
+- Environment-based endpoints management
+- Card holder information management
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tappay_ruby'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install tappay_ruby
+```
+
+## Configuration
+
+There are several ways to configure the gem:
+
+### 1. Direct Configuration
+
+The simplest way to configure the gem:
+
+```ruby
+Tappay.configure do |config|
+  # Environment settings
+  config.mode = Rails.env.production? ? :production : :sandbox
+
+  # Common settings
+  config.partner_key = 'your_partner_key'.freeze
+  config.app_id = 'your_app_id'.freeze
+  config.merchant_id = 'your_merchant_id'.freeze
+  config.instalment_merchant_id = 'your_instalment_merchant_id'.freeze
+  config.currency = 'TWD'.freeze
+  config.vat_number = 'your_vat_number'.freeze
+end
+```
+
+### 2. Using Environment Variables
+
+For better security, you can use environment variables:
+
+```ruby
+Tappay.configure do |config|
+  config.mode = Rails.env.production? ? :production : :sandbox
+  config.partner_key = ENV['TAPPAY_PARTNER_KEY'].freeze
+  config.app_id = ENV['TAPPAY_APP_ID'].freeze
+  config.merchant_id = ENV['TAPPAY_MERCHANT_ID'].freeze
+  # ... other configurations
+end
+```
+
+### 3. Using Rails Credentials
+
+If you're using Rails, you can use credentials:
+
+```ruby
+Tappay.configure do |config|
+  config.mode = Rails.env.production? ? :production : :sandbox
+  config.partner_key = Rails.application.credentials.tappay[:partner_key].freeze
+  config.app_id = Rails.application.credentials.tappay[:app_id].freeze
+  # ... other configurations
+end
+```
+
+## Environment-based Endpoints
+
+The gem automatically handles different endpoints for sandbox and production environments. You don't need to specify the full URLs - just set the mode:
+
+```ruby
+# For sandbox (default)
+config.mode = :sandbox  # Uses https://sandbox.tappaysdk.com/...
+
+# For production
+config.mode = :production  # Uses https://prod.tappaysdk.com/...
+```
+
+## Card Holder Information
+
+You can provide cardholder information in two ways:
+
+### 1. Using CardHolder Object (Recommended)
+
+```ruby
+# Create a CardHolder object
+card_holder = Tappay::CardHolder.new(
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone_number: '+886923456789'
+)
+
+# Use in payment directly
+result = Tappay::CreditCard::Pay.by_prime(
+  prime: 'prime_from_tappay_sdk',
+  amount: 100,
+  order_number: 'ORDER-123',
+  card_holder: card_holder  # No need to call as_json
+)
+```
+
+### 2. Using Hash Directly
+
+```ruby
+result = Tappay::CreditCard::Pay.by_prime(
+  prime: 'prime_from_tappay_sdk',
+  amount: 100,
+  order_number: 'ORDER-123',
+  card_holder: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    phone_number: '+886923456789'
+  }
+)
+```
+
+Both approaches are valid and will work the same way. The CardHolder object provides a more structured way to handle cardholder information and includes validation.
+
+## Usage
+
+### Pay by Prime
+
+Use this method when the customer wants to pay with their credit card without storing the card information. The customer will need to enter their card information for each transaction.
+
+```ruby
+# Basic payment with prime
+result = Tappay::CreditCard::Pay.by_prime(
+  prime: 'prime_from_tappay_sdk',
+  amount: 100,
+  order_number: 'ORDER-123',
+  currency: 'TWD',
+  redirect_url: 'https://your-site.com/return',
+  three_domain_secure: true,  # Enable 3D secure if needed
+  remember: true,  # Set to true if you want to store the card for future payments
+  card_holder: card_holder  # Optional cardholder information
+)
+
+if result['status'] == 0
+  # Payment successful
+  transaction_id = result['rec_trade_id']
+  if result['card_secret']
+    # If remember is true, you'll get these tokens
+    card_key = result['card_secret']['card_key']
+    card_token = result['card_secret']['card_token']
+    # Store card_key and card_token securely for future payments
+  end
+end
+```
+
+### Pay by Token
+
+Use this method when the customer has opted to save their card information for future purchases. This provides a more convenient checkout experience as customers don't need to re-enter their card information.
+
+```ruby
+# Recurring payment with stored card token
+result = Tappay::CreditCard::Pay.by_token(
+  card_key: 'stored_card_key',
+  card_token: 'stored_card_token',
+  amount: 100,
+  order_number: 'ORDER-124',
+  currency: 'TWD',
+  redirect_url: 'https://your-site.com/return',
+  three_domain_secure: true,  # Enable 3D secure if needed
+  card_holder: card_holder  # Optional cardholder information
+)
+
+if result['status'] == 0
+  # Payment successful
+  transaction_id = result['rec_trade_id']
+end
+```
+
+### Instalment Payment
+
+```ruby
+payment = Tappay::CreditCard::Instalment.new(
+  prime: 'prime_from_tappay_sdk',
+  amount: 10000,
+  instalment: 6,  # 6 monthly installments
+  details: 'Product description',
+  cardholder: {
+    phone_number: '+886923456789',
+    name: 'John Doe',
+    email: 'john@example.com'
+  }
+)
+
+begin
+  result = payment.execute
+  if result['status'] == 0
+    # Payment successful
+    instalment_info = result['instalment_info']
+    number_of_instalments = instalment_info['number_of_instalments']
+    first_payment = instalment_info['first_payment']
+    each_payment = instalment_info['each_payment']
+  end
+rescue Tappay::PaymentError => e
+  # Handle payment error
+end
+```
+
+### Refund Processing
+
+```ruby
+refund = Tappay::CreditCard::Refund.new(
+  transaction_id: 'transaction_id_from_payment',
+  amount: 100
+)
+
+begin
+  result = refund.execute
+  if result['status'] == 0
+    # Refund successful
+  end
+rescue Tappay::RefundError => e
+  # Handle refund error
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  result = Tappay::CreditCard::Pay.by_prime(
+    prime: 'prime_from_tappay_sdk',
+    amount: 100,
+    order_number: 'ORDER-123'
+  )
+rescue Tappay::PaymentError => e
+  # Handle payment error
+  puts e.message
+rescue Tappay::ValidationError => e
+  # Handle validation error
+  puts e.message
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/7a6163/tappay.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/tappay/card_holder.rb

@@ -0,0 +1,21 @@
+module Tappay
+  class CardHolder
+    attr_reader :name, :email, :phone_number
+
+    def initialize(name:, email:, phone_number:)
+      @name = name
+      @email = email
+      @phone_number = phone_number
+    end
+
+    def to_h
+      {
+        name: name,
+        email: email,
+        phone_number: phone_number
+      }
+    end
+
+    alias_method :as_json, :to_h
+  end
+end

data/lib/tappay/client.rb

@@ -0,0 +1,65 @@
+require 'httparty'
+require 'json'
+
+module Tappay
+  class Client
+    include HTTParty
+
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    def post(url, data)
+      @response = self.class.post(
+        url,
+        body: data.to_json,
+        headers: headers,
+        timeout: timeout
+      )
+
+      validate_response
+      @response
+    rescue HTTParty::Error => e
+      raise ConnectionError, "HTTP Request failed: #{e.message}"
+    end
+
+    private
+
+    def headers
+      {
+        'Content-Type' => 'application/json',
+        'x-api-key' => Tappay.configuration.partner_key
+      }
+    end
+
+    def timeout
+      25 # seconds
+    end
+
+    def validate_response
+      case @response.code
+      when 200
+        data = parse_response
+        unless data['status'].zero?
+          raise APIError.new(data['status'], data['msg'])
+        end
+      when 400
+        raise ValidationError, "Invalid request: #{@response.body}"
+      when 401
+        raise ConfigurationError, "Authentication failed. Check your partner_key."
+      when 404
+        raise ConnectionError, "API endpoint not found: #{@response.request.last_uri}"
+      else
+        raise ConnectionError, "HTTP Request failed with code #{@response.code}: #{@response.body}"
+      end
+    end
+
+    def parse_response
+      JSON.parse(@response.body)
+    rescue JSON::ParserError => e
+      raise ConnectionError, "Invalid JSON response: #{e.message}"
+    end
+  end
+end

data/lib/tappay/configuration.rb

@@ -0,0 +1,34 @@
+module Tappay
+  class Configuration
+    attr_accessor :partner_key, :merchant_id, :instalment_merchant_id, :app_id, :currency, :vat_number
+    attr_writer :api_version
+
+    def initialize
+      @mode = :sandbox
+      @api_version = '2'
+    end
+
+    def api_version
+      @api_version.to_s
+    end
+
+    def sandbox?
+      @mode == :sandbox
+    end
+
+    def production?
+      @mode == :production
+    end
+
+    def mode=(value)
+      unless [:sandbox, :production].include?(value.to_sym)
+        raise ArgumentError, "Invalid mode. Must be :sandbox or :production"
+      end
+      @mode = value.to_sym
+    end
+
+    def mode
+      @mode ||= :sandbox
+    end
+  end
+end

data/lib/tappay/credit_card/instalment.rb

@@ -0,0 +1,60 @@
+module Tappay
+  module CreditCard
+    class Instalment
+      def self.by_prime(options = {})
+        InstalmentByPrime.new(options)
+      end
+
+      def self.by_token(options = {})
+        InstalmentByToken.new(options)
+      end
+    end
+
+    class InstalmentByPrime < PaymentBase
+      def initialize(options = {})
+        super(options)
+      end
+
+      def payment_data
+        super.merge(
+          prime: options[:prime],
+          remember: options[:remember] || false
+        )
+      end
+
+      def endpoint_url
+        Tappay::Endpoints::CreditCard.payment_by_prime_url
+      end
+
+      private
+
+      def additional_required_options
+        [:prime, :cardholder, :instalment]
+      end
+    end
+
+    class InstalmentByToken < PaymentBase
+      def initialize(options = {})
+        super(options)
+      end
+
+      def payment_data
+        super.merge(
+          card_key: options[:card_key],
+          card_token: options[:card_token],
+          ccv_prime: options[:ccv_prime]
+        )
+      end
+
+      def endpoint_url
+        Tappay::Endpoints::CreditCard.payment_by_token_url
+      end
+
+      private
+
+      def additional_required_options
+        [:card_key, :card_token, :instalment]
+      end
+    end
+  end
+end

data/lib/tappay/credit_card/pay.rb

@@ -0,0 +1,121 @@
+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
+        {
+          partner_key: Tappay.configuration.partner_key,
+          merchant_id: options[:merchant_id] || Tappay.configuration.merchant_id,
+          amount: options[:amount],
+          details: options[:details],
+          currency: options[:currency] || 'TWD',
+          order_number: options[:order_number],
+          redirect_url: options[:redirect_url],
+          three_domain_secure: options[:three_domain_secure] || false
+        }.tap do |data|
+          data[:cardholder] = card_holder_data if options[:cardholder]
+          data[:instalment] = options[:instalment] if options[:instalment]
+        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]
+      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
+
+    class Pay < PaymentBase
+      def self.by_prime(options = {})
+        PayByPrime.new(options)
+      end
+
+      def self.by_token(options = {})
+        PayByToken.new(options)
+      end
+    end
+
+    class PayByPrime < PaymentBase
+      def payment_data
+        super.merge(
+          prime: options[:prime],
+          remember: options[:remember] || false
+        )
+      end
+
+      def endpoint_url
+        Tappay::Endpoints::CreditCard.payment_by_prime_url
+      end
+
+      private
+
+      def additional_required_options
+        [:prime]
+      end
+    end
+
+    class PayByToken < PaymentBase
+      def payment_data
+        super.merge(
+          card_key: options[:card_key],
+          card_token: options[:card_token]
+        )
+      end
+
+      def endpoint_url
+        Tappay::Endpoints::CreditCard.payment_by_token_url
+      end
+
+      private
+
+      def additional_required_options
+        [:card_key, :card_token, :currency]
+      end
+    end
+  end
+end

data/lib/tappay/credit_card/refund.rb

@@ -0,0 +1,31 @@
+module Tappay
+  module CreditCard
+    class Refund < Client
+      def initialize(options = {})
+        super
+        validate_options!
+      end
+
+      def execute
+        post(Endpoints::CreditCard.refund_url, refund_data)
+      end
+
+      private
+
+      def refund_data
+        {
+          partner_key: Tappay.configuration.partner_key,
+          rec_trade_id: options[:transaction_id],
+          amount: options[:amount]
+        }
+      end
+
+      def validate_options!
+        required = [:transaction_id, :amount]
+        missing = required.select { |key| options[key].nil? }
+        
+        raise ValidationError, "Missing required options: #{missing.join(', ')}" if missing.any?
+      end
+    end
+  end
+end

data/lib/tappay/endpoints.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tappay
+  module Endpoints
+    class << self
+      def base_url
+        if Tappay.configuration.sandbox?
+          'https://sandbox.tappaysdk.com'
+        else
+          'https://prod.tappaysdk.com'
+        end
+      end
+    end
+
+    module CreditCard
+      class << self
+        def payment_by_prime_url
+          "#{Endpoints.base_url}/tpc/payment/pay-by-prime"
+        end
+
+        def payment_by_token_url
+          "#{Endpoints.base_url}/tpc/payment/pay-by-token"
+        end
+
+        def refund_url
+          "#{Endpoints.base_url}/tpc/transaction/refund"
+        end
+      end
+    end
+
+    module Transaction
+      class << self
+        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
+end

data/lib/tappay/errors.rb

@@ -0,0 +1,20 @@
+module Tappay
+  class Error < StandardError; end
+  
+  class ConfigurationError < Error; end
+  class ConnectionError < Error; end
+  class ValidationError < Error; end
+  class PaymentError < Error; end
+  class RefundError < Error; end
+  class QueryError < Error; end
+  
+  class APIError < Error
+    attr_reader :code, :message
+
+    def initialize(code, message)
+      @code = code
+      @message = message
+      super("TapPay API Error (#{code}): #{message}")
+    end
+  end
+end

data/lib/tappay/transaction/query.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Tappay
+  module Transaction
+    class Query
+      def initialize(order_number:, records_per_page: 50, page: 0, time: nil, order_by: nil)
+        @order_number = order_number
+        @records_per_page = records_per_page
+        @page = page
+        @time = time
+        @order_by = order_by
+      end
+
+      def execute
+        client = Tappay::Client.new
+        response = client.post(Endpoints::Transaction.query_url, request_params)
+        
+        {
+          status: response['status'],
+          msg: response['msg'],
+          number_of_transactions: response['number_of_transactions'],
+          trade_records: parse_trade_records(response['trade_records'])
+        }
+      end
+
+      private
+
+      def request_params
+        {
+          records_per_page: @records_per_page,
+          page: @page,
+          filters: filters,
+          order_by: @order_by
+        }.compact
+      end
+
+      def filters
+        {
+          order_number: @order_number,
+          time: @time
+        }.compact
+      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']
+          }
+        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

@@ -0,0 +1,3 @@
+module Tappay
+  VERSION = "0.4.0"
+end

data/lib/tappay.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "tappay/version"
+require_relative "tappay/configuration"
+require_relative "tappay/client"
+require_relative "tappay/errors"
+require_relative "tappay/card_holder"
+require_relative "tappay/endpoints"
+require_relative "tappay/transaction/query"
+require_relative "tappay/credit_card/pay"
+require_relative "tappay/credit_card/refund"
+require_relative "tappay/credit_card/instalment"
+
+module Tappay
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  def self.reset
+    self.configuration = Configuration.new
+  end
+end

data/lib/tappay_ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'tappay'

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: tappay_ruby
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Zac
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-12-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+description: A Ruby library for integrating with TapPay payment services, supporting
+  credit card payments, refunds, and transaction queries
+email:
+- 579103+7a6163@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tappay.rb
+- lib/tappay/card_holder.rb
+- lib/tappay/client.rb
+- lib/tappay/configuration.rb
+- lib/tappay/credit_card/instalment.rb
+- lib/tappay/credit_card/pay.rb
+- lib/tappay/credit_card/refund.rb
+- lib/tappay/endpoints.rb
+- lib/tappay/errors.rb
+- lib/tappay/transaction/query.rb
+- lib/tappay/version.rb
+- lib/tappay_ruby.rb
+homepage: https://github.com/7a6163/tappay
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/7a6163/tappay
+  source_code_uri: https://github.com/7a6163/tappay
+  changelog_uri: https://github.com/7a6163/tappay/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for TapPay payment gateway
+test_files: []