rails-shopee-qris 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4abd75453a929debadba31df32047103e52839b892f4cd410446bec2175a292
-  data.tar.gz: 8cf2072749c406cfec500aedd4f0e8d1cb1dd895e589e360e5a86f8cf9ad64d7
+  metadata.gz: 5f301fa2107316c8aa94a3ab8946fc318bbbb73d0306c9d0b08290648437e2c1
+  data.tar.gz: d35eb2223fdad00dfc593ec82eb4c926652aa97a15ccea640177f1d9b6c31b3b
 SHA512:
-  metadata.gz: 2a5a549cadef0c93f502b9ce8cf40ea7105db57292819887b4200cea58e1e225c10a83527a75f489e4963560f837fa4bfa3dd4f197e818c626c075951f4b12db
-  data.tar.gz: a3be425bb15d15f483612622b5c1995e05bfe9d2451f48c4f938a9a4ebe257b7482d9573a6b81d931d463456ad4b6382914988ecf007e6aea00f35e62542c577
+  metadata.gz: e4a3757eb7bd2e386a1774bafdb50b8486a51dd3265c6513b75c2039bac9d3e4ec6a8c0760794de5cbdf6fdba45b0cefee97e16aeb988dcb1e2ae8b11180f443
+  data.tar.gz: 84a529743925b2494c02b9cd9c5a322f7efda75dc83c630e258a7833a6c59fb9a7dbfc1f04b31f45d743f1d265032da7f39c3c5d0d28fd960c903dcb636b11b3

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.2.0
+
+Verified against a live ShopeePay Partner merchant account (store listing, transaction
+feed, transaction detail, device-risk, OTP request).
+
+### Added
+- `Client` accepts either the raw `B:...` merchant token or the whole
+  `__shopee_partner_website_x_token_live` JWT cookie, extracting the inner token,
+  `userid` and `exp`.
+- `Client#refreshable?` tells callers whether a session can silently renew.
+- Provider error codes are translated into actionable text
+  (`10002`, `200020`, `2010000`, `48401003`, `48401102`, `48401103`, `48500102`).
+- `Setup` exposes `CHANNEL_NAMES`; unavailable OTP channels are reported with the
+  available list.
+- `test/response_test.rb` coverage for the error mapping.
+
+### Fixed
+- **Payment envelope shape.** Request fields were nested under `data.metadata`; Shopee
+  expects them as siblings of `metadata`. Store listing and the transaction feed never
+  worked before this.
+- **`10002` aborted every non-password account.** It means "no password set" — the OTP
+  flow now continues instead of raising.
+- **Wrong refresh error.** A rejected manual token raised "session cannot be refreshed";
+  it now reports the real rejection and its code. Proactive refresh only runs when the
+  session actually has renewal credentials.
+- **Duplicate-key crash.** `Client` symbolized sessions via `JSON.generate`, which raised
+  on hashes carrying both `"token"` and `:token`.
+- **`48401003`** is now reported as a wrong/expired OTP rather than a bare code.
+- QRIS generation rejects fractional and oversized amounts instead of truncating them,
+  and parsing rejects non-decimal lengths and duplicate tags.
+
+## 0.1.0
+
+Initial release: dynamic QRIS generation, static QRIS validation, CRC-16, store listing,
+transaction feed, payment matching, OTP login flow.

data/README.md

@@ -2,7 +2,7 @@
 
 Unofficial Ruby/Rails ShopeePay Partner client, based on `QrisMerchantID` Shopee API logic and `rails-gopay-unofficial` gem structure. Ruby >= 3.1; no runtime dependencies beyond stdlib.
 
-Use only with merchant authorization. Internal Shopee APIs can change. Live Shopee login/payment acceptance has not been verified here; offline regressions and local HTTP smoke checks do not prove provider acceptance. Never log tokens, passwords, device reports, session cookies, or raw payment data.
+Use only with merchant authorization. Internal Shopee APIs can change. Read paths (`get-store-list`, `get-transaction-list`, `get-transaction-detail`, device-risk, OTP request/verify) have been exercised against a live merchant account; actual money settlement has not. Never log tokens, passwords, device reports, session cookies, or raw payment data.
 
 ## Installation
 
@@ -24,7 +24,9 @@ end
 
 ## Direct merchant token
 
-Use the inner `token` value (`B:...`), not the entire JWT from the `__shopee_partner_website_x_token_live` cookie. `Setup#read_merchant_credential` decodes that cookie payload; it does not verify the JWT signature. Provider validates credentials on requests.
+Pass either the inner `B:...` token, or the whole `__shopee_partner_website_x_token_live` cookie value — the client decodes that JWT and pulls out the inner `token` (plus `userid` and `exp`). It does not verify the JWT signature; Shopee validates credentials on each request.
+
+Get a fresh token: log in at `partner.shopee.co.id` → DevTools → Network → open the ShopeePay transaction history page → click `get-transaction-list` → Request Payload → `data.metadata.token`.
 
 ```ruby
 client = Rails::Shopee::Qris::Client.new(
@@ -33,7 +35,7 @@ client = Rails::Shopee::Qris::Client.new(
 stores = client.list_stores
 ```
 
-A manually supplied token cannot silently renew. Reconnect when rejected.
+Tokens rotate when the portal session refreshes; `200020` means paste a new one. A manually supplied token cannot silently renew — only an OTP session carries `switch_credential` and can call `refresh!`.
 
 ## OTP login
 
@@ -58,7 +60,7 @@ else
 end
 ```
 
-Channels: `1` SMS, `2` voice, `3` WhatsApp, `4` email, `5` Zalo; availability comes from provider. `verify_otp(challenge, otp)` also returns verification separately, reusable by `complete_login(verification, merchant_id:, store_id:)`. Requested store must belong to selected merchant; multiple stores can leave `store_id` unset, requiring explicit selection before transaction reconciliation.
+Channels: `1` SMS, `2` voice, `3` WhatsApp, `4` email, `5` Zalo. Omit `channel:` to use the channel Shopee recommends for that account; asking for an unavailable one raises with the available list. `verify_otp(challenge, otp)` also returns verification separately, reusable by `complete_login(verification, merchant_id:, store_id:)`. Requested store must belong to selected merchant; multiple stores can leave `store_id` unset, requiring explicit selection before transaction reconciliation.
 
 Persist **entire** session encrypted, including `cookies`, `merchant`, `merchants`, and `switch_credential`. These are credentials, not safe client-side session data.
 
@@ -130,7 +132,17 @@ rescue Rails::Shopee::Qris::Error => error
 end
 ```
 
-Invalid provider envelopes, HTTP failures, expired credentials, malformed inputs, and incomplete pagination fail explicitly. Dead account session needs fresh OTP.
+Invalid provider envelopes, HTTP failures, expired credentials, malformed inputs, and incomplete pagination fail explicitly. Shopee often answers with a bare numeric code and no message; observed codes are translated:
+
+| Code | Meaning |
+| --- | --- |
+| `10002` | Account has no password set (not an error — the OTP flow continues) |
+| `200020` | Token invalid or expired — paste a fresh one |
+| `2010000` | Request carried no token |
+| `48401003` | OTP code wrong or expired |
+| `48401102` | Password required before an OTP is sent |
+| `48401103` | OTP channel unavailable for this account |
+| `48500102` | Account session expired; log in again with an OTP |
 
 ## Verification
 
@@ -141,12 +153,12 @@ gem build rails-shopee-qris.gemspec
 
 ## RubyGems release
 
-Package `0.1.0` with `gem build rails-shopee-qris.gemspec`. Authenticate via `gem signin` (or configure a scoped `GEM_HOST_API_KEY` with push permission), then:
+Package with `gem build rails-shopee-qris.gemspec`. Authenticate via `gem signin` (or configure a scoped `GEM_HOST_API_KEY` with push permission), then:
 
 ```sh
-gem push rails-shopee-qris-0.1.0.gem --host https://rubygems.org
+gem push rails-shopee-qris-0.2.0.gem --host https://rubygems.org
 ```
 
-RubyGems versions are immutable. Bump gemspec version before subsequent releases. Built `.gem` files and credentials must not be committed.
+RubyGems versions are immutable. Bump the gemspec version before subsequent releases. Built `.gem` files and credentials must not be committed.
 
 MIT license; see [LICENSE.txt](LICENSE.txt).

data/lib/rails/shopee/qris/client.rb

@@ -25,16 +25,22 @@ module Rails
         )
           config = Rails::Shopee::Qris.configuration
           raise Error, "Shopee session must be an object" if session && !session.is_a?(Hash)
-          @session = session && JSON.parse(JSON.generate(session), symbolize_names: true)
-          @token = token || @session&.dig(:token) || config.token
+          @session = session && deep_symbolize(session)
+          raw_token = token || @session&.dig(:token) || config.token
+          parsed_token, token_meta = parse_token_input(raw_token)
+          @token = parsed_token
           @store_id = (store_id || @session&.dig(:store_id) || config.store_id)&.to_s
-          @merchant_id = (merchant_id || @session&.dig(:merchant, :id) || @session&.dig(:merchant_id) || config.merchant_id)&.to_s
+          @merchant_id = (merchant_id || @session&.dig(:merchant, :id) || @session&.dig(:merchant_id) || token_meta[:account_id] || config.merchant_id)&.to_s
           @phone_number = phone_number || @session&.dig(:phone_number) || config.phone_number
           @device_id = device_id || @session&.dig(:switch_credential, :spc_clientid)
-          expiry = expires_at || @session&.dig(:expires_at)
+          expiry = expires_at || @session&.dig(:expires_at) || token_meta[:expires_at]
           @expires_at = extract_time(expiry)
           raise Error, "Invalid Shopee session expiry" if expiry && !@expires_at
-          @session[:expires_at] = @expires_at if @session && expiry
+          if @session
+            @session[:token] = @token if @token
+            @session[:merchant_id] ||= @merchant_id if @merchant_id
+            @session[:expires_at] = @expires_at if expiry
+          end
         end
 
         attr_reader :token, :store_id, :merchant_id, :session, :phone_number, :device_id, :expires_at
@@ -53,9 +59,14 @@ module Rails
           raise Error, "Invalid payment amount"
         end
 
+        def refreshable?
+          session.is_a?(Hash) && session[:switch_credential].is_a?(Hash)
+        end
+
         def refresh!
-          unless session.is_a?(Hash) && session[:switch_credential].is_a?(Hash)
-            raise Error, "Shopee session cannot be refreshed without full session credentials; reconnect with OTP"
+          unless refreshable?
+            raise Error, "Shopee merchant token is invalid or expired and this session has no renewal " \
+                         "credentials; log in again with OTP or paste a fresh B:... token"
           end
 
           updated = Setup.new.refresh_session(session)
@@ -66,7 +77,7 @@ module Rails
         end
 
         def transactions_between(start_time:, end_time:, store_id: @store_id, page_size: 10, max_pages: 20)
-          refresh! if expires_at && expires_at <= Time.now + 900 && session
+          refresh! if refreshable? && expires_at && expires_at <= Time.now + 900
 
           start_ts = start_time.respond_to?(:to_i) ? start_time.to_i : Integer(start_time)
           end_ts = end_time.respond_to?(:to_i) ? end_time.to_i : Integer(end_time)
@@ -307,6 +318,43 @@ module Rails
         rescue ArgumentError, TypeError, RangeError
           nil
         end
+        def deep_symbolize(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), acc|
+              acc[k.to_sym] = deep_symbolize(v)
+            end
+          when Array
+            obj.map { |item| deep_symbolize(item) }
+          else
+            obj
+          end
+        end
+
+        def parse_token_input(val)
+          return [nil, {}] if val.nil?
+
+          str = val.to_s.strip.gsub(/[\r\n\t ]/, "")
+          return [str, {}] if str.start_with?("B:")
+
+          if str.count(".") == 2
+            segments = str.split(".")
+            padded = segments[1] + ("=" * (-segments[1].bytesize % 4))
+            payload = JSON.parse(Base64.urlsafe_decode64(padded), symbolize_names: true)
+            if payload.is_a?(Hash) && payload[:token].to_s.start_with?("B:")
+              meta = {
+                account_id: payload[:userid]&.to_s,
+                expires_at: payload[:exp] ? Time.at(payload[:exp]) : nil
+              }
+              return [payload[:token].to_s, meta]
+            end
+          end
+
+          [str, {}]
+        rescue StandardError
+          [str, {}]
+        end
+
 
         def request_payment(url, inner_data, retried: false)
           raise Error, "Shopee merchant token is missing; configure token or login with OTP" if token.to_s.empty?
@@ -326,14 +374,21 @@ module Rails
           raise Error, "Shopee returned a non-object response" unless resp.is_a?(Hash)
           code = resp[:code].to_s
 
-          if (code != "0" && INVALID_TOKEN_CODES.include?(code)) && session && !retried
-            refresh!
-            return request_payment(url, inner_data, retried: true)
+          if code != "0" && INVALID_TOKEN_CODES.include?(code) && !retried
+            if refreshable?
+              refresh!
+              return request_payment(url, inner_data, retried: true)
+            end
+
+            raise Error.new(
+              "Shopee rejected the merchant token (code #{code}); it is invalid or expired. " \
+              "Log in again with OTP or paste a fresh B:... token.",
+              nil, resp[:code], resp
+            )
           end
 
           err = Response.error(resp)
           raise Error.new(err || "ShopeePay request failed", nil, resp[:code], resp) if err
-          Response.data(resp)
 
           resp
         end

data/lib/rails/shopee/qris/response.rb

@@ -6,6 +6,18 @@ module Rails
       module Response
         module_function
 
+        # Shopee answers many failures with a bare numeric code and no message.
+        # Map the ones we have observed so callers get something actionable.
+        CODE_HINTS = {
+          10002 => "The Shopee account has no password set",
+          200020 => "Shopee rejected the token as invalid or expired",
+          2010000 => "Shopee request carried no token",
+          48401003 => "Shopee rejected the OTP code as wrong or expired",
+          48401102 => "Shopee requires the account password before sending an OTP",
+          48401103 => "Shopee refused to send the OTP on the requested channel",
+          48500102 => "The Shopee account session has expired; log in again with an OTP"
+        }.freeze
+
         def data(payload)
           code = payload[:code] if payload.is_a?(Hash)
           success = (code.is_a?(Integer) && code.zero?) || code == "0"
@@ -38,7 +50,7 @@ module Rails
 
             messages << msg.to_s unless msg.to_s.empty?
             messages << description.to_s unless description.to_s.empty?
-            messages << "Shopee error (code #{code})" if messages.empty? && !code.nil?
+            messages << (CODE_HINTS[code_i] || "Shopee error (code #{code})") if messages.empty? && !code.nil?
           end
           return nil if messages.empty?
 

data/lib/rails/shopee/qris/setup.rb

@@ -18,8 +18,13 @@ module Rails
         OTP_CHANNELS = [1, 2, 3, 5].freeze
         SEND_OTP_CHANNELS = [1, 2, 3, 5, 4].freeze
         DEFAULT_OTP_CHANNEL = 3
+        CHANNEL_NAMES = { 1 => "SMS", 2 => "voice", 3 => "WhatsApp", 4 => "email", 5 => "Zalo" }.freeze
         NEED_OTP_CODE = 48401102
         NOT_LOGIN_CODE = 48500102
+        NO_PASSWORD_CODE = 10002
+        OTP_CHANNEL_UNAVAILABLE_CODE = 48401103
+        WRONG_OTP_CODE = 48401003
+        PASSWORD_REQUIRED = "This Shopee account is password-protected; supply the password to receive an OTP"
 
         LIVE_TOKEN_COOKIE = "__shopee_partner_website_x_token_live"
         CLIENT_ID_COOKIE = "SPC_CLIENTID"
@@ -60,22 +65,32 @@ module Rails
           default_ch = settings[:default_channel]
           resolved = channel || default_ch || DEFAULT_OTP_CHANNEL
           if !available.empty? && !available.include?(resolved)
-            raise Error, "Requested Shopee OTP channel is unavailable"
+            names = available.map { |c| "#{c} (#{CHANNEL_NAMES[c] || 'unknown'})" }.join(", ")
+            raise Error, "Shopee OTP channel #{resolved} is unavailable for this account; available: #{names}"
           end
 
-          account_request(
-            "/api/v4/account/business/send_otp",
-            {
-              operation: OTP_OPERATION,
-              phone: phone,
-              security_device_fingerprint: fingerprint,
-              support_session: false,
-              supported_channels: SEND_OTP_CHANNELS,
-              channel: resolved,
-              captcha_signature: ""
-            },
-            fingerprint
-          )
+          begin
+            account_request(
+              "/api/v4/account/business/send_otp",
+              {
+                operation: OTP_OPERATION,
+                phone: phone,
+                security_device_fingerprint: fingerprint,
+                support_session: false,
+                supported_channels: SEND_OTP_CHANNELS,
+                channel: resolved,
+                captcha_signature: ""
+              },
+              fingerprint
+            )
+          rescue Error => e
+            raise Error.new(
+              e.code == OTP_CHANNEL_UNAVAILABLE_CODE ?
+                "Shopee refused to send the OTP on channel #{resolved}; choose another available channel" :
+                e.message,
+              e.status, e.code, e.payload
+            )
+          end
 
           {
             version: 1,
@@ -105,17 +120,26 @@ module Rails
           fingerprint = challenge[:device_fingerprint].to_s
 
           formatted_phone = format_phone_for_verification(phone)
-          verified = account_request(
-            "/api/v4/account/business/verify_otp",
-            {
-              operation: OTP_OPERATION,
-              otp: code.to_s,
-              phone: formatted_phone,
-              security_device_fingerprint: fingerprint,
-              support_session: false
-            },
-            fingerprint
-          )
+          begin
+            verified = account_request(
+              "/api/v4/account/business/verify_otp",
+              {
+                operation: OTP_OPERATION,
+                otp: code.to_s,
+                phone: formatted_phone,
+                security_device_fingerprint: fingerprint,
+                support_session: false
+              },
+              fingerprint
+            )
+          rescue Error => e
+            raise e unless e.code.to_s == WRONG_OTP_CODE.to_s
+
+            raise Error.new(
+              "Shopee rejected the OTP code (wrong or expired); request a new one and try again",
+              e.status, e.code, e.payload
+            )
+          end
 
           token = verified[:otp_token]
           raise Error, "Shopee OTP verification returned no token" unless token.is_a?(String) && !token.empty?
@@ -374,20 +398,23 @@ module Rails
           parsed = parse_json(resp)
 
           if parsed[:error] == NEED_OTP_CODE
-            raise Error, "This Shopee account is password-protected; supply the password to receive an OTP" if password.to_s.empty?
+            raise Error, PASSWORD_REQUIRED if password.to_s.empty?
 
             return true
           end
 
-          return false if parsed[:error] == 0 && parsed[:data].is_a?(Hash)
+          return false if parsed[:error] == 0
+          # 10002: the account exists but has no password set — nothing to verify.
+          return false if parsed[:error] == NO_PASSWORD_CODE
 
           account = parsed[:data].is_a?(Hash) ? parsed[:data][:toc_account] : nil
           if account.is_a?(Hash) && account[:has_password] == true
-            raise Error, "This Shopee account is password-protected; supply the password to receive an OTP"
+            raise Error, PASSWORD_REQUIRED
           end
 
-          err = Response.error(parsed)
-          raise Error.new(err || "Shopee authentication failed", resp.code.to_i, parsed[:error], parsed)
+          # Any other code means this account does not authenticate by password;
+          # OTP delivery is validated by send_otp afterwards.
+          false
         end
 
         def login_status

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-shopee-qris
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Azmi
@@ -14,6 +14,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/rails-shopee-qris.rb