active_merchant_gmo_pg 0.1.0

data/lib/active_merchant/billing/gateways/gmo_pg.rb

@@ -0,0 +1,642 @@
+# frozen_string_literal: true
+
+require_relative 'gmo_pg_error_messages'
+
+module ActiveMerchant
+  module Billing
+    class GmoPgGateway < Gateway
+      self.test_url = 'https://pt01.mul-pay.jp'
+      self.live_url = 'https://p01.mul-pay.jp'
+
+      self.supported_countries = [ 'JP' ]
+      self.default_currency = 'JPY'
+      self.supported_cardtypes = %i[visa master american_express jcb diners_club]
+      self.money_format = :cents
+
+      self.homepage_url = 'https://www.gmo-pg.com/'
+      self.display_name = 'GMO Payment Gateway'
+
+      STANDARD_ERROR_CODE_MAPPING = {
+        'E01' => STANDARD_ERROR_CODE[:invalid_number],
+        'E11' => STANDARD_ERROR_CODE[:card_declined],
+        'E61' => STANDARD_ERROR_CODE[:invalid_cvc],
+        'E91' => STANDARD_ERROR_CODE[:processing_error]
+      }.freeze
+
+      # GMO-PGエラーコード
+      MEMBER_NOT_FOUND_ERROR = 'E01390002'
+
+      # GMO-PGゲートウェイを初期化します
+      #
+      # @param options [Hash] 認証情報を含むオプション
+      # @option options [String] :shop_id ショップID（必須）
+      # @option options [String] :shop_pass ショップパスワード（必須）
+      # @option options [String] :site_id サイトID（必須）
+      # @option options [String] :site_pass サイトパスワード（必須）
+      # @option options [Boolean] :test テスト環境を使用する場合はtrue
+      def initialize(options = {})
+        requires!(options, :shop_id, :shop_pass, :site_id, :site_pass)
+        super
+
+        host = test? ? 'pt01.mul-pay.jp' : 'p01.mul-pay.jp'
+
+        @site_client = GMO::Payment::SiteAPI.new(
+          site_id: @options[:site_id],
+          site_pass: @options[:site_pass],
+          host: host
+        )
+
+        @shop_client = GMO::Payment::ShopAPI.new(
+          shop_id: @options[:shop_id],
+          shop_pass: @options[:shop_pass],
+          host: host
+        )
+      end
+
+      # クレジットカード情報を登録します
+      # 会員が存在しない場合は自動的に会員登録も行います
+      #
+      # @param payment [String, CreditCard] トークンまたはクレジットカードオブジェクト
+      # @param options [Hash] オプション
+      # @option options [String] :member_id 会員ID（省略時は自動生成）
+      # @option options [String] :member_name 会員名（省略時はmember_idを使用）
+      # @option options [String] :card_pass カードパスワード
+      # @return [Response] レスポンスオブジェクト。authorizationに"member_id|card_seq"形式の識別子が含まれます
+      #
+      # @example トークンを使用したカード登録
+      #   gateway.store("token_string", { member_id: "user_001" })
+      #
+      # @example クレジットカードオブジェクトを使用したカード登録
+      #   card = ActiveMerchant::Billing::CreditCard.new(
+      #     number: "4111111111111111",
+      #     month: 12,
+      #     year: 2025,
+      #     verification_value: "123",
+      #     first_name: "Taro",
+      #     last_name: "Yamada"
+      #   )
+      #   gateway.store(card, { member_id: "user_001" })
+      def store(payment, options = {})
+        member_id = options[:member_id] || generate_unique_member_id
+        member_name = options[:member_name] || member_id
+
+        begin
+          @site_client.search_member(member_id: member_id)
+        rescue GMO::Payment::APIError => e
+          if e.error_info["ErrInfo"]&.include?(MEMBER_NOT_FOUND_ERROR)
+            begin
+              @site_client.save_member(member_id: member_id, member_name: member_name)
+            rescue GMO::Payment::APIError => save_error
+              return error_response(parse_error_message(save_error))
+            end
+          else
+            return error_response(parse_error_message(e))
+          end
+        end
+
+        card_params = {
+          member_id: member_id,
+          seq_mode: 1
+        }
+
+        if payment.is_a?(String)
+          card_params[:token] = payment
+        else
+          card_params[:card_no] = payment.number
+          card_params[:expire] = expdate(payment)
+          card_params[:holder_name] = payment.name if payment.name.present?
+          card_params[:security_code] = payment.verification_value if payment.verification_value.present?
+        end
+
+        card_params[:card_pass] = options[:card_pass] if options[:card_pass]
+
+        begin
+          result = @site_client.save_card(card_params)
+          card_seq = result['CardSeq']
+          authorization = "#{member_id}|#{card_seq}"
+
+          Response.new(
+            true,
+            'カード登録に成功しました',
+            result,
+            authorization: authorization,
+            test: test?
+          )
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+      # 登録済みのクレジットカードを削除します
+      #
+      # @param identification [String] カード識別子（"member_id|card_seq"形式）
+      # @param options [Hash] オプション（現在未使用）
+      # @return [Response] レスポンスオブジェクト
+      #
+      # @example カード削除
+      #   gateway.unstore("user_001|0")
+      def unstore(identification, options = {})
+        member_id, card_seq = split_authorization(identification)
+        return error_response('無効な識別子フォーマットです') unless member_id && card_seq
+
+        begin
+          @site_client.delete_card(member_id: member_id, card_seq: card_seq, seq_mode: 1)
+          Response.new(true, 'カード削除に成功しました', {}, test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+      # オーソリ（仮売上）を実行します
+      # 後でcaptureメソッドで売上計上する必要があります
+      #
+      # @param money [Integer] 金額（円単位）
+      # @param payment_source [String, CreditCard] トークン、"member_id|card_seq"形式の識別子、またはクレジットカードオブジェクト
+      # @param options [Hash] オプション
+      # @option options [String] :order_id 注文ID（省略時は自動生成）
+      # @option options [Integer] :tax 税額
+      # @option options [Integer] :method 支払方法（デフォルト: 1=一括払い）
+      # @option options [Integer] :pay_times 分割回数
+      # @option options [String] :ret_url 3DS認証後の戻りURL
+      # @option options [String] :callback_type コールバックタイプ
+      # @option options [String] :td_tenant_name 3DSテナント名
+      # @option options [String] :tds2_type 3DS2.0未対応時取り扱い（デフォルト: '3'=通常オーソリ実施）
+      # @option options [String] :td_required 決済時3DS必須タイプ（デフォルト: '0'=契約内容に従う、'1'=3DS認証必須、'2'=3DS認証必須ではない）
+      # @option options [String] :tds2_email メールアドレス（3DS2.0用）
+      # @option options [String] :tds2_mobile_phone_cc 携帯電話国コード（3DS2.0用）
+      # @option options [String] :tds2_mobile_phone_no 携帯電話番号（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_city 配送先都市（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_country 配送先国（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line1 配送先住所1（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_post_code 配送先郵便番号（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_city 請求先都市（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_country 請求先国（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line1 請求先住所1（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_post_code 請求先郵便番号（3DS2.0用）
+      # @option options [String] :tds2_home_phone_cc 自宅電話国コード（3DS2.0用）
+      # @option options [String] :tds2_home_phone_no 自宅電話番号（3DS2.0用）
+      # @option options [String] :tds2_work_phone_cc 勤務先電話国コード（3DS2.0用）
+      # @option options [String] :tds2_work_phone_no 勤務先電話番号（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line2 配送先住所2（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line3 配送先住所3（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_state 配送先州/都道府県（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line2 請求先住所2（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line3 請求先住所3（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_state 請求先州/都道府県（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_change アカウント変更インジケータ（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_date アカウント作成日（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_pw_change パスワード変更インジケータ（3DS2.0用）
+      # @option options [String] :tds2_nb_purchase_account 購入回数（3DS2.0用）
+      # @option options [String] :tds2_payment_acc_age 決済アカウント年齢（3DS2.0用）
+      # @option options [String] :tds2_provision_attempts_day プロビジョニング試行回数（3DS2.0用）
+      # @option options [String] :tds2_ship_address_usage 配送先住所の使用状況（3DS2.0用）
+      # @option options [String] :tds2_ship_name_ind 配送先名インジケータ（3DS2.0用）
+      # @option options [String] :tds2_suspicious_acc_activity 不審なアクティビティインジケータ（3DS2.0用）
+      # @option options [String] :tds2_txn_activity_day 1日あたりの取引数（3DS2.0用）
+      # @option options [String] :tds2_txn_activity_year 1年あたりの取引数（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_data 3DS要求者認証データ（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_method 3DS要求者認証方法（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_timestamp 3DS要求者認証タイムスタンプ（3DS2.0用）
+      # @option options [String] :tds2_acs_challenge_mandated ACSチャレンジ必須（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_prior_ref 3DS要求者事前参照（3DS2.0用）
+      # @return [Response] レスポンスオブジェクト。authorizationに"access_id|access_pass|order_id"形式の識別子が含まれます
+      #
+      # @example 登録済みカードでオーソリ
+      #   gateway.authorize(1000, "user_001|0", { order_id: "order_123" })
+      #
+      # @example トークンでオーソリ
+      #   gateway.authorize(1000, "token_string", { order_id: "order_123" })
+      def authorize(money, payment_source, options = {})
+        perform_transaction(
+          money,
+          payment_source,
+          'AUTH',
+          'オーソリに成功しました',
+          options.merge(tds2_type: options[:tds2_type] || '3', td_required: options[:td_required] || '0')
+        )
+      end
+
+      # 即時売上を実行します
+      # authorizeとcaptureを同時に行います
+      #
+      # @param money [Integer] 金額（円単位）
+      # @param payment_source [String, CreditCard] トークン、"member_id|card_seq"形式の識別子、またはクレジットカードオブジェクト
+      # @param options [Hash] オプション
+      # @option options [String] :order_id 注文ID（省略時は自動生成）
+      # @option options [Integer] :tax 税額
+      # @option options [Integer] :method 支払方法（デフォルト: 1=一括払い）
+      # @option options [Integer] :pay_times 分割回数
+      # @option options [String] :ret_url 3DS認証後の戻りURL
+      # @option options [String] :callback_type コールバックタイプ
+      # @option options [String] :td_tenant_name 3DSテナント名
+      # @option options [String] :tds2_type 3DS2.0未対応時取り扱い（デフォルト: '3'=通常オーソリ実施）
+      # @option options [String] :tds2_email メールアドレス（3DS2.0用）
+      # @option options [String] :tds2_mobile_phone_cc 携帯電話国コード（3DS2.0用）
+      # @option options [String] :tds2_mobile_phone_no 携帯電話番号（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_city 配送先都市（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_country 配送先国（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line1 配送先住所1（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_post_code 配送先郵便番号（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_city 請求先都市（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_country 請求先国（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line1 請求先住所1（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_post_code 請求先郵便番号（3DS2.0用）
+      # @option options [String] :tds2_home_phone_cc 自宅電話国コード（3DS2.0用）
+      # @option options [String] :tds2_home_phone_no 自宅電話番号（3DS2.0用）
+      # @option options [String] :tds2_work_phone_cc 勤務先電話国コード（3DS2.0用）
+      # @option options [String] :tds2_work_phone_no 勤務先電話番号（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line2 配送先住所2（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_line3 配送先住所3（3DS2.0用）
+      # @option options [String] :tds2_ship_addr_state 配送先州/都道府県（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line2 請求先住所2（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_line3 請求先住所3（3DS2.0用）
+      # @option options [String] :tds2_bill_addr_state 請求先州/都道府県（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_change アカウント変更インジケータ（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_date アカウント作成日（3DS2.0用）
+      # @option options [String] :tds2_ch_acc_pw_change パスワード変更インジケータ（3DS2.0用）
+      # @option options [String] :tds2_nb_purchase_account 購入回数（3DS2.0用）
+      # @option options [String] :tds2_payment_acc_age 決済アカウント年齢（3DS2.0用）
+      # @option options [String] :tds2_provision_attempts_day プロビジョニング試行回数（3DS2.0用）
+      # @option options [String] :tds2_ship_address_usage 配送先住所の使用状況（3DS2.0用）
+      # @option options [String] :tds2_ship_name_ind 配送先名インジケータ（3DS2.0用）
+      # @option options [String] :tds2_suspicious_acc_activity 不審なアクティビティインジケータ（3DS2.0用）
+      # @option options [String] :tds2_txn_activity_day 1日あたりの取引数（3DS2.0用）
+      # @option options [String] :tds2_txn_activity_year 1年あたりの取引数（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_data 3DS要求者認証データ（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_method 3DS要求者認証方法（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_auth_timestamp 3DS要求者認証タイムスタンプ（3DS2.0用）
+      # @option options [String] :tds2_acs_challenge_mandated ACSチャレンジ必須（3DS2.0用）
+      # @option options [String] :tds2_three_ds_req_prior_ref 3DS要求者事前参照（3DS2.0用）
+      # @return [Response] レスポンスオブジェクト
+      #
+      # @example 登録済みカードで即時売上
+      #   gateway.purchase(1000, "user_001|0", { order_id: "order_123" })
+      def purchase(money, payment_source, options = {})
+        perform_transaction(
+          money,
+          payment_source,
+          'CAPTURE',
+          '決済に成功しました',
+          options.merge(tds2_type: options[:tds2_type] || '3')
+        )
+      end
+
+      # オーソリ済みの取引を売上計上します
+      #
+      # @param money [Integer] 金額（円単位）
+      # @param authorization [String] authorizeメソッドで取得した認証情報（"access_id|access_pass|order_id"形式）
+      # @param options [Hash] オプション
+      # @option options [Integer] :tax 税額
+      # @return [Response] レスポンスオブジェクト
+      #
+      # @example 売上計上
+      #   response = gateway.authorize(1000, "user_001|0", { order_id: "order_123" })
+      #   gateway.capture(1000, response.authorization)
+      def capture(money, authorization, options = {})
+        access_id, access_pass, order_id = split_authorization(authorization)
+        return error_response('無効な認証情報です') unless access_id && access_pass
+
+        begin
+          alter_params = {
+            access_id: access_id,
+            access_pass: access_pass,
+            job_cd: 'SALES',
+            amount: amount(money)
+          }
+          alter_params[:tax] = options[:tax].to_i if options[:tax]
+          alter_params[:shipping] = options[:shipping].to_i if options[:shipping]
+
+          result = @shop_client.alter_tran(alter_params)
+          Response.new(true, '売上計上に成功しました', result, test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+      # 取引を取消します
+      # オーソリ済みまたは売上済みの取引を取り消すことができます
+      #
+      # @param authorization [String] authorizeまたはpurchaseメソッドで取得した認証情報
+      # @param options [Hash] オプション（現在未使用）
+      # @return [Response] レスポンスオブジェクト
+      #
+      # @example 取引取消
+      #   response = gateway.authorize(1000, "user_001|0", { order_id: "order_123" })
+      #   gateway.void(response.authorization)
+      def void(authorization, options = {})
+        access_id, access_pass, _order_id = split_authorization(authorization)
+        return error_response('無効な認証情報です') unless access_id && access_pass
+
+        begin
+          alter_params = {
+            access_id: access_id,
+            access_pass: access_pass,
+            job_cd: 'CANCEL'
+          }
+
+          result = @shop_client.alter_tran(alter_params)
+          Response.new(true, '取消に成功しました', result,
+                       authorization: result['TranID'],
+                       test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+      #
+      # @param money [Integer] 新しい金額（セント単位）
+      # @param authorization [String] authorizeまたはpurchaseメソッドで取得した認証情報
+      # @param options [Hash] オプション
+      # @option options [String] :job_cd 処理区分（'AUTH'または'CAPTURE'、デフォルト: 'CAPTURE'）
+      # @option options [Integer] :tax 税額（セント単位）
+      # @return [Response] レスポンスオブジェクト
+      #
+      # @example オーソリ済み取引の金額変更
+      #   response = gateway.authorize(100000, "user_001|0", { order_id: "order_123" })
+      #   gateway.update_amount(50000, response.authorization, { job_cd: 'AUTH' })
+      #
+      # @example 売上計上済み取引の金額変更
+      #   response = gateway.purchase(100000, "user_001|0", { order_id: "order_123" })
+      #   gateway.update_amount(50000, response.authorization, { job_cd: 'CAPTURE' })
+      def update_amount(money, authorization, options = {})
+        access_id, access_pass, _order_id = split_authorization(authorization)
+        return error_response('無効な認証情報です') unless access_id && access_pass
+
+        job_cd = options[:job_cd] || 'CAPTURE'
+
+        begin
+          change_params = {
+            shop_id: @options[:shop_id],
+            shop_pass: @options[:shop_pass],
+            access_id: access_id,
+            access_pass: access_pass,
+            job_cd: job_cd,
+            amount: amount(money)
+          }
+          change_params[:tax] = amount(options[:tax]) if options[:tax]
+
+          # NOTE: gmo gem (v0.5.8) にchange_tranメソッドがない場合は
+          # post_requestを直接呼び出してChangeTran.idPassエンドポイントにアクセス
+          result = @shop_client.send(:post_request, 'ChangeTran.idPass', change_params)
+
+          Response.new(true, '金額変更に成功しました', result,
+                       authorization: result['TranID'],
+                       test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(e.message)
+        end
+      end
+
+      # 取引情報を照会します
+      #
+      # @param order_id [String] 注文ID
+      # @param options [Hash] オプション（現在未使用）
+      # @return [Response] レスポンスオブジェクト。取引の詳細情報が含まれます
+      #
+      # @example 取引照会
+      #   gateway.search_trade("order_123")
+      def search_trade(order_id, options = {})
+        begin
+          result = @shop_client.search_trade(order_id: order_id)
+          Response.new(true, '取引照会に成功しました', result, test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+      # 3DS2.0認証後の決済を完了します
+      # 3DS2.0認証チャレンジ完了後、この決済を実行して取引を確定させます
+      #
+      # @param access_id [String] EntryTranで取得したアクセスID
+      # @param access_pass [String] EntryTranで取得したアクセスパス
+      # @param options [Hash] オプション（現在未使用）
+      # @return [Response] レスポンスオブジェクト。決済実行結果が含まれます
+      #                     authorizationには"access_id|access_pass|order_id"形式の識別子が含まれます
+      #
+      # @example 3DS2.0認証後の決済完了
+      #   response = gateway.authorize(1000, "user_001|0", { order_id: "order_123", ret_url: "https://example.com/callback" })
+      #   access_id = response.params['AccessID']
+      #   access_pass = response.params['AccessPass']
+      #   gateway.secure_tran2(access_id, access_pass)
+      def secure_tran2(access_id, access_pass, options = {})
+        begin
+          result = @shop_client.secure_tran_2(access_id: access_id, access_pass: access_pass)
+          # レスポンスのOrderIDを使ってauthorizationを構築
+          # これにより、後続のcapture/void/credit操作で使用できるようになります
+          order_id = result['OrderID']
+          authorization = "#{access_id}|#{access_pass}|#{order_id}"
+
+          Response.new(true, '3DS2.0認証後の決済に成功しました', result,
+                       authorization: authorization,
+                       test: test?)
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+
+
+      private
+
+      def perform_transaction(money, payment_source, job_cd, success_message, options = {})
+        order_id = options[:order_id] || generate_order_id
+
+        begin
+          entry_params = {
+            order_id: order_id,
+            job_cd: job_cd,
+            amount: amount(money)
+          }
+          entry_params[:tax] = amount(options[:tax]) if options[:tax]
+          entry_params[:shipping] = amount(options[:shipping]) if options[:shipping]
+          entry_params[:td_flag] = '2'
+          entry_params[:td_tenant_name] = options[:td_tenant_name] if options[:td_tenant_name]
+          entry_params[:tds2_type] = options[:tds2_type]
+          entry_params[:td_required] = options[:td_required] if options[:td_required]
+
+          entry_result = @shop_client.entry_tran(entry_params)
+          access_id = entry_result['AccessID']
+          access_pass = entry_result['AccessPass']
+
+          exec_params = build_exec_tran_params(access_id, access_pass, order_id, payment_source, options)
+          exec_result = execute_transaction(exec_params, payment_source)
+
+          authorization = "#{access_id}|#{access_pass}|#{order_id}"
+
+          Response.new(
+            true,
+            success_message,
+            exec_result.merge('AccessID' => access_id, 'AccessPass' => access_pass, 'OrderID' => order_id),
+            authorization: authorization,
+            test: test?
+          )
+        rescue GMO::Payment::APIError => e
+          error_response(parse_error_message(e))
+        end
+      end
+
+      def build_exec_tran_params(access_id, access_pass, order_id, payment_source, options)
+        params = {
+          access_id: access_id,
+          access_pass: access_pass,
+          order_id: order_id
+        }
+
+        if payment_source.is_a?(String)
+          if payment_source.include?('|')
+            member_id, card_seq = payment_source.split('|')
+            params[:member_id] = member_id
+            params[:card_seq] = card_seq
+            params[:seq_mode] = 1
+          else
+            params[:token] = payment_source
+          end
+        else
+          params[:card_no] = payment_source.number
+          params[:expire] = expdate(payment_source)
+          params[:security_code] = payment_source.verification_value if payment_source.verification_value.present?
+          params[:holder_name] = payment_source.name if payment_source.name.present?
+        end
+
+        params[:method] = options[:method] || 1
+        params[:pay_times] = options[:pay_times] if options[:pay_times]
+        params[:ret_url] = options[:ret_url] if options[:ret_url]
+        params[:callback_type] = options[:callback_type] if options[:callback_type]
+
+        add_3ds2_params(params, options)
+
+        params
+      end
+
+      def add_3ds2_params(params, options)
+        tds2_params = %w[
+          tds2_ch_acc_change tds2_ch_acc_date tds2_ch_acc_pw_change tds2_nb_purchase_account
+          tds2_payment_acc_age tds2_provision_attempts_day tds2_ship_address_usage
+          tds2_ship_name_ind tds2_suspicious_acc_activity tds2_txn_activity_day
+          tds2_txn_activity_year tds2_three_ds_req_auth_data tds2_three_ds_req_auth_method
+          tds2_three_ds_req_auth_timestamp tds2_acs_challenge_mandated tds2_three_ds_req_prior_ref
+          tds2_email tds2_home_phone_cc tds2_home_phone_no tds2_mobile_phone_cc
+          tds2_mobile_phone_no tds2_work_phone_cc tds2_work_phone_no tds2_ship_addr_city
+          tds2_ship_addr_country tds2_ship_addr_line1 tds2_ship_addr_line2 tds2_ship_addr_line3
+          tds2_ship_addr_post_code tds2_ship_addr_state tds2_bill_addr_city tds2_bill_addr_country
+          tds2_bill_addr_line1 tds2_bill_addr_line2 tds2_bill_addr_line3 tds2_bill_addr_post_code
+          tds2_bill_addr_state
+        ]
+
+        tds2_params.each do |param|
+          key = param.to_sym
+          params[key] = options[key] if options[key]
+        end
+      end
+
+      def split_authorization(authorization)
+        return [ nil, nil, nil ] unless authorization
+
+        parts = authorization.split('|')
+        case parts.length
+        when 2
+          [ parts[0], parts[1], nil ]
+        when 3
+          parts
+        else
+          [ nil, nil, nil ]
+        end
+      end
+
+      def generate_unique_member_id
+        "member-#{Time.now.to_i}-#{SecureRandom.hex(4)}"
+      end
+
+      def generate_order_id
+        "order-#{Time.now.to_i}-#{SecureRandom.hex(4)}"
+      end
+
+      def expdate(payment)
+        "#{format('%02d', payment.month)}#{payment.year.to_s[-2..]}"
+      end
+
+      # 詳細エラーコード(例: 42G020000)から簡略エラーコード(例: G02)を抽出
+      #
+      # @param detailed_code [String] 詳細エラーコード
+      # @return [String, nil] 簡略エラーコード
+      def extract_error_code(detailed_code)
+        return nil unless detailed_code.is_a?(String)
+
+        # C系/G系エラー: 42C010000 -> C01, 42G020000 -> G02
+        if detailed_code.match(/^42([CG])(\d{2})/)
+          "#{$1}#{$2}"
+        # E系/M系エラー: E01010001 -> E01, M01002001 -> M01
+        elsif detailed_code.match(/^([EM])(\d{2})/)
+          "#{$1}#{$2}"
+        else
+          detailed_code
+        end
+      end
+
+      # GMO::Payment::APIErrorから日本語エラーメッセージを抽出
+      #
+      # @param error [GMO::Payment::APIError] APIエラーオブジェクト
+      # @return [String] 日本語エラーメッセージ
+      def parse_error_message(error)
+        return error.message unless error.respond_to?(:error_info)
+
+        error_info = error.error_info
+        return error.message unless error_info.is_a?(Hash)
+
+        # ErrInfoから詳細エラーコードを抽出
+        err_info_str = error_info['ErrInfo'].to_s
+        detailed_codes = err_info_str.scan(/[A-Z0-9]+/)
+
+        # 最初に見つかった日本語メッセージを返す
+        detailed_codes.each do |code|
+          # 詳細コードで検索（例: E21030007, 42G020000）
+          if GMO_PG_OFFICIAL_ERROR_MESSAGES.key?(code)
+            return GMO_PG_OFFICIAL_ERROR_MESSAGES[code]
+          end
+
+          # 簡略コードで検索（例: E21, G02）
+          simplified_code = extract_error_code(code)
+          if simplified_code && GMO_PG_OFFICIAL_ERROR_MESSAGES.key?(simplified_code)
+            return GMO_PG_OFFICIAL_ERROR_MESSAGES[simplified_code]
+          end
+        end
+
+        # メッセージが見つからない場合は汎用メッセージを返す
+        '決済処理に失敗しました。申し訳ございませんが、しばらく時間をあけて購入画面からやり直してください。'
+      end
+
+      def error_response(message)
+        Response.new(false, message, {}, test: test?)
+      end
+
+      # 金額を整数に変換
+      # Spree::Money#amount_in_centsが既に正しい円単位の値を返すため、
+      # 単純にIntegerに変換するだけで良い
+      # 例: 2000円 -> amount_in_cents(2000) -> amount(2000) = 2000円
+      def amount(money)
+        return money unless money.is_a?(Numeric)
+
+        money.to_i
+      end
+
+      def execute_transaction(params, payment_source)
+        if payment_source.is_a?(String) && payment_source.include?('|')
+          params[:site_id] = @options[:site_id]
+          params[:site_pass] = @options[:site_pass]
+          params[:client_field_flg] = if params[:client_field_1] || params[:client_field_2] || params[:client_field_3]
+                                        '1'
+          else
+                                        '0'
+          end
+          params[:device_category] = '0'
+
+          # NOTE: gmo gem (v0.5.8) のexec_tranはmember_id/card_seq方式に対応していないため、
+          # post_requestを直接呼び出してExecTran.idPassエンドポイントにアクセスしています。
+          # gmo gemのアップデート時には動作確認が必要です。
+          @shop_client.send(:post_request, 'ExecTran.idPass', params)
+        else
+          @shop_client.exec_tran(params)
+        end
+      end
+    end
+  end
+end