zai_payment 2.1.0 → 2.3.0

data/lib/zai_payment/resources/user.rb

@@ -68,6 +68,7 @@ module ZaiPayment
       #
       # @param limit [Integer] number of records to return (default: 10)
       # @param offset [Integer] number of records to skip (default: 0)
+      # @param search [String] text value to be used for searching users
       # @return [Response] the API response containing users array
       #
       # @example
@@ -75,12 +76,16 @@ module ZaiPayment
       #   response = users.list
       #   response.data # => [{"id" => "...", "email" => "..."}, ...]
       #
+      # @example with search
+      #   response = users.list(search: "john@example.com")
+      #
       # @see https://developer.hellozai.com/reference/getallusers
-      def list(limit: 10, offset: 0)
+      def list(limit: 10, offset: 0, search: nil)
         params = {
           limit: limit,
           offset: offset
         }
+        params[:search] = search if search
 
         client.get('/users', params: params)
       end
@@ -107,7 +112,7 @@ module ZaiPayment
       # @option attributes [String] :id Optional unique ID for the user. If not provided,
       #   Zai will generate one automatically. Cannot contain '.' character.
       #   Useful for mapping to your existing system's user IDs.
-      # @option attributes [String] :user_type User type ('payin' or 'payout').
+      # @option attributes [String] :user_type (Required) User type ('payin' or 'payout').
       #   This determines which fields are required.
       # @option attributes [String] :email (Required) user's email address
       # @option attributes [String] :first_name (Required) user's first name
@@ -264,6 +269,134 @@ module ZaiPayment
         client.patch("/users/#{user_id}", body: body)
       end
 
+      # Show the user's wallet account
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response containing wallet account details
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.wallet_account("user_id")
+      #   response.data # => {"id" => "...", "balance" => ..., ...}
+      #
+      # @see https://developer.hellozai.com/reference/showuserwalletaccounts
+      def wallet_account(user_id)
+        validate_id!(user_id, 'user_id')
+        client.get("/users/#{user_id}/wallet_accounts")
+      end
+
+      # List items associated with the user
+      #
+      # @param user_id [String] the user ID
+      # @param limit [Integer] number of records to return (default: 10, max: 200)
+      # @param offset [Integer] number of records to skip (default: 0)
+      # @return [Response] the API response containing items array
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.items("user_id")
+      #   response.data # => [{"id" => "...", "name" => "..."}, ...]
+      #
+      # @example with custom pagination
+      #   response = users.items("user_id", limit: 50, offset: 10)
+      #
+      # @see https://developer.hellozai.com/reference/listuseritems
+      def items(user_id, limit: 10, offset: 0)
+        validate_id!(user_id, 'user_id')
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        client.get("/users/#{user_id}/items", params: params)
+      end
+
+      # Set the user's disbursement account
+      #
+      # @param user_id [String] the user ID
+      # @param account_id [String] the bank account ID to use for disbursements
+      # @return [Response] the API response
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.set_disbursement_account("user_id", "account_id")
+      #
+      # @see https://developer.hellozai.com/reference/setuserdisbursementaccount
+      def set_disbursement_account(user_id, account_id)
+        validate_id!(user_id, 'user_id')
+        validate_id!(account_id, 'account_id')
+
+        body = { account_id: account_id }
+        client.patch("/users/#{user_id}/disbursement_account", body: body)
+      end
+
+      # Show the user's bank account
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response containing bank account details
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.bank_account("user_id")
+      #   response.data # => {"id" => "...", "account_name" => "...", ...}
+      #
+      # @see https://developer.hellozai.com/reference/showuserbankaccount
+      def bank_account(user_id)
+        validate_id!(user_id, 'user_id')
+        client.get("/users/#{user_id}/bank_accounts")
+      end
+
+      # Verify user (Prelive Only)
+      # Sets a user's verification state to approved on pre-live environment
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.verify("user_id")
+      #
+      # @note This endpoint only works in the pre-live environment.
+      #   The user verification workflow holds for all users in production.
+      #
+      # @see https://developer.hellozai.com/reference/verifyuser
+      def verify(user_id)
+        validate_id!(user_id, 'user_id')
+        client.patch("/users/#{user_id}/identity_verified")
+      end
+
+      # Show the user's card account
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response containing card account details
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.card_account("user_id")
+      #   response.data # => {"id" => "...", "card" => {...}, ...}
+      #
+      # @see https://developer.hellozai.com/reference/showusercardaccount
+      def card_account(user_id)
+        validate_id!(user_id, 'user_id')
+        client.get("/users/#{user_id}/card_accounts")
+      end
+
+      # List BPay accounts associated with the user
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response containing BPay accounts array
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.bpay_accounts("user_id")
+      #   response.data # => [{"id" => "...", "biller_code" => "..."}, ...]
+      #
+      # @see https://developer.hellozai.com/reference/listuserbpayaccounts
+      def bpay_accounts(user_id)
+        validate_id!(user_id, 'user_id')
+        client.get("/users/#{user_id}/bpay_accounts")
+      end
+
       private
 
       def validate_id!(value, field_name)
@@ -280,7 +413,7 @@ module ZaiPayment
 
       def validate_create_attributes!(attributes) # rubocop:disable Metrics/AbcSize
         validate_required_attributes!(attributes)
-        validate_user_type!(attributes[:user_type]) if attributes[:user_type]
+        validate_user_type!(attributes[:user_type])
         validate_email!(attributes[:email])
         validate_country!(attributes[:country])
         validate_dob!(attributes[:dob]) if attributes[:dob]
@@ -290,7 +423,7 @@ module ZaiPayment
 
       def validate_required_attributes!(attributes)
         # Base required fields for all users
-        required_fields = %i[email first_name last_name country]
+        required_fields = %i[email first_name last_name country user_type]
 
         # Additional required fields for payout users
         user_type = attributes[:user_type]&.to_s&.downcase

data/lib/zai_payment/response.rb

@@ -5,6 +5,11 @@ module ZaiPayment
   class Response
     attr_reader :status, :body, :headers, :raw_response
 
+    RESPONSE_DATA_KEYS = %w[
+      webhooks users items fees transactions
+      batch_transactions bpay_accounts bank_accounts card_accounts
+    ].freeze
+
     def initialize(faraday_response)
       @raw_response = faraday_response
       @status = faraday_response.status
@@ -30,14 +35,15 @@ module ZaiPayment
     end
 
     # Get the data from the response body
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
     def data
       return body unless body.is_a?(Hash)
 
-      body['webhooks'] || body['users'] || body['items'] || body['fees'] ||
-        body['transactions'] || body['batch_transactions'] || body
+      RESPONSE_DATA_KEYS.each do |key|
+        return body[key] if body[key]
+      end
+
+      body
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     # Get pagination or metadata info
     def meta

data/lib/zai_payment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZaiPayment
-  VERSION = '2.1.0'
+  VERSION = '2.3.0'
 end

data/readme.md

@@ -88,6 +88,7 @@ Manage payin (buyer) and payout (seller/merchant) users:
 ```ruby
 # Create a payin user (buyer)
 response = ZaiPayment.users.create(
+  user_type: 'payin',
   email: 'buyer@example.com',
   first_name: 'John',
   last_name: 'Doe',
@@ -97,6 +98,7 @@ response = ZaiPayment.users.create(
 
 # Create a payout user (seller/merchant)
 response = ZaiPayment.users.create(
+  user_type: 'payout',
   email: 'seller@example.com',
   first_name: 'Jane',
   last_name: 'Smith',
@@ -110,6 +112,7 @@ response = ZaiPayment.users.create(
 
 # Create a business user with company details
 response = ZaiPayment.users.create(
+  user_type: 'payout',
   email: 'director@company.com',
   first_name: 'John',
   last_name: 'Director',
@@ -134,6 +137,27 @@ response = ZaiPayment.users.show('user_id')
 
 # Update user
 response = ZaiPayment.users.update('user_id', mobile: '+9876543210')
+
+# Show user wallet account
+response = ZaiPayment.users.wallet_account('user_id')
+
+# List user items with pagination
+response = ZaiPayment.users.items('user_id', limit: 50, offset: 10)
+
+# Set user disbursement account
+response = ZaiPayment.users.set_disbursement_account('user_id', 'bank_account_id')
+
+# Show user bank account
+response = ZaiPayment.users.bank_account('user_id')
+
+# Verify user (prelive only)
+response = ZaiPayment.users.verify('user_id')
+
+# Show user card account
+response = ZaiPayment.users.card_account('user_id')
+
+# List user's BPay accounts
+response = ZaiPayment.users.bpay_accounts('user_id')
 ```
 
 **📚 Documentation:**

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -78,6 +78,7 @@ files:
 - docs/webhook_signature.md
 - docs/webhooks.md
 - examples/items.md
+- examples/rails_card_payment.md
 - examples/token_auths.md
 - examples/users.md
 - examples/webhooks.md