zai_payment 2.6.0 → 2.7.0

data/lib/zai_payment/resources/batch_transaction.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # BatchTransaction resource for managing Zai batch transactions (Prelive only)
+    #
+    # @note These endpoints are only available in the prelive environment
+    class BatchTransaction
+      attr_reader :client, :config
+
+      # Valid transaction types
+      TRANSACTION_TYPES = %w[payment refund disbursement fee deposit withdrawal].freeze
+
+      # Valid transaction type methods
+      TRANSACTION_TYPE_METHODS = %w[credit_card npp bpay wallet_account_transfer wire_transfer misc].freeze
+
+      # Valid directions
+      DIRECTIONS = %w[debit credit].freeze
+
+      def initialize(client: nil, config: nil)
+        @client = client || Client.new(base_endpoint: :core_base)
+        @config = config || ZaiPayment.config
+      end
+
+      # List batch transactions
+      #
+      # Retrieve an ordered and paginated list of existing batch transactions.
+      # The list can be filtered by account, batch ID, item, and transaction type.
+      #
+      # @param options [Hash] optional filters
+      # @option options [Integer] :limit number of records to return (default: 10, max: 200)
+      # @option options [Integer] :offset number of records to skip (default: 0)
+      # @option options [String] :account_id Bank, Card or Wallet Account ID
+      # @option options [String] :batch_id Batch ID
+      # @option options [String] :item_id Item ID
+      # @option options [String] :transaction_type transaction type
+      #   (payment, refund, disbursement, fee, deposit, withdrawal)
+      # @option options [String] :transaction_type_method transaction method (credit_card, npp, bpay, etc.)
+      # @option options [String] :direction direction (debit, credit)
+      # @option options [String] :created_before ISO 8601 date/time to filter transactions created before
+      # @option options [String] :created_after ISO 8601 date/time to filter transactions created after
+      # @option options [String] :disbursement_bank the bank used for disbursing the payment
+      # @option options [String] :processing_bank the bank used for processing the payment
+      # @return [Response] the API response containing batch_transactions array
+      #
+      # @example List all batch transactions
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.list
+      #   response.data # => [{"id" => 12484, "status" => 12200, ...}]
+      #
+      # @example List with filters
+      #   response = batch_transactions.list(
+      #     transaction_type: 'disbursement',
+      #     direction: 'credit',
+      #     limit: 50
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/listbatchtransactions
+      def list(**options)
+        validate_list_options(options)
+
+        params = build_list_params(options)
+
+        client.get('/batch_transactions', params: params)
+      end
+
+      # Show a batch transaction
+      #
+      # Get a batch transaction using its ID (UUID or numeric ID).
+      #
+      # @param id [String] the batch transaction ID
+      # @return [Response] the API response containing batch_transactions object
+      #
+      # @example Get a batch transaction by UUID
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.show('90c1418b-f4f4-413e-a4ba-f29c334e7f55')
+      #   response.data # => {"id" => 13143, "uuid" => "90c1418b-f4f4-413e-a4ba-f29c334e7f55", ...}
+      #
+      # @example Get a batch transaction by numeric ID
+      #   response = batch_transactions.show('13143')
+      #   response.data['state'] # => "successful"
+      #
+      # @raise [Errors::ValidationError] if id is blank
+      #
+      # @see https://developer.hellozai.com/reference/showbatchtransaction
+      def show(id)
+        validate_id!(id, 'id')
+
+        client.get("/batch_transactions/#{id}")
+      end
+
+      # Export batch transactions (Prelive only)
+      #
+      # Calls the GET /batch_transactions/export_transactions API which moves all pending
+      # batch_transactions into batched state. As a result, this API will return all the
+      # batch_transactions that have moved from pending to batched. Please store the id
+      # in order to progress it in Pre-live.
+      #
+      # @return [Response] the API response containing transactions array with batch_id
+      #
+      # @example Export transactions
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.export_transactions
+      #   response.data # => {"transactions" => [{"id" => "...", "batch_id" => "...", "status" => "batched", ...}]}
+      #
+      # @raise [Errors::ConfigurationError] if not in prelive environment
+      #
+      # @see https://developer.hellozai.com/reference (Prelive endpoints)
+      def export_transactions
+        ensure_prelive_environment!
+
+        client.get('/batch_transactions/export_transactions')
+      end
+
+      # Update batch transaction states (Prelive only)
+      #
+      # Calls the PATCH /batches/:id/transaction_states API which moves one or more
+      # batch_transactions into a specific state. You will need to pass in the batch_id
+      # from the export_transactions response.
+      #
+      # State codes:
+      # - 12700: bank_processing state
+      # - 12000: successful state (final state, triggers webhook)
+      #
+      # @param batch_id [String] the batch ID from export_transactions response
+      # @param exported_ids [Array<String>] array of transaction IDs to update
+      # @param state [Integer] the target state code (12700 or 12000)
+      # @return [Response] the API response containing job information
+      #
+      # @example Move transactions to bank_processing state
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.update_transaction_states(
+      #     "batch_id",
+      #     exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"],
+      #     state: 12700
+      #   )
+      #   response.body # => {
+      #     "aggregated_jobs_uuid" => "c1cbc502-9754-42fd-9731-2330ddd7a41f",
+      #     "msg" => "1 jobs have been sent to the queue.",
+      #     "errors" => []
+      #   }
+      #
+      # @example Move transactions to successful state
+      #   response = batch_transactions.update_transaction_states(
+      #     "batch_id",
+      #     exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"],
+      #     state: 12000
+      #   )
+      #   response.body # => {
+      #     "aggregated_jobs_uuid" => "...",
+      #     "msg" => "1 jobs have been sent to the queue.",
+      #     "errors" => []
+      #   }
+      #
+      # @raise [Errors::ConfigurationError] if not in prelive environment
+      # @raise [Errors::ValidationError] if parameters are invalid
+      #
+      # @see https://developer.hellozai.com/reference (Prelive endpoints)
+      def update_transaction_states(batch_id, exported_ids:, state:)
+        ensure_prelive_environment!
+        validate_id!(batch_id, 'batch_id')
+        validate_exported_ids!(exported_ids)
+        validate_state!(state)
+
+        body = {
+          exported_ids: exported_ids,
+          state: state
+        }
+
+        client.patch("/batches/#{batch_id}/transaction_states", body: body)
+      end
+
+      # Move transactions to bank_processing state (Prelive only)
+      #
+      # Convenience method that calls update_transaction_states with state 12700.
+      # This simulates the step where transactions are moved to bank_processing state.
+      #
+      # @param batch_id [String] the batch ID from export_transactions response
+      # @param exported_ids [Array<String>] array of transaction IDs to update
+      # @return [Response] the API response with aggregated_jobs_uuid, msg, and errors
+      #
+      # @example
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.process_to_bank_processing(
+      #     "batch_id",
+      #     exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"]
+      #   )
+      #   response.body["msg"] # => "1 jobs have been sent to the queue."
+      #
+      # @raise [Errors::ConfigurationError] if not in prelive environment
+      # @raise [Errors::ValidationError] if parameters are invalid
+      def process_to_bank_processing(batch_id, exported_ids:)
+        update_transaction_states(batch_id, exported_ids: exported_ids, state: 12_700)
+      end
+
+      # Move transactions to successful state (Prelive only)
+      #
+      # Convenience method that calls update_transaction_states with state 12000.
+      # This simulates the final step where transactions are marked as successful
+      # and triggers the batch_transactions webhook.
+      #
+      # @param batch_id [String] the batch ID from export_transactions response
+      # @param exported_ids [Array<String>] array of transaction IDs to update
+      # @return [Response] the API response with aggregated_jobs_uuid, msg, and errors
+      #
+      # @example
+      #   batch_transactions = ZaiPayment.batch_transactions
+      #   response = batch_transactions.process_to_successful(
+      #     "batch_id",
+      #     exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"]
+      #   )
+      #   response.body["msg"] # => "1 jobs have been sent to the queue."
+      #
+      # @raise [Errors::ConfigurationError] if not in prelive environment
+      # @raise [Errors::ValidationError] if parameters are invalid
+      def process_to_successful(batch_id, exported_ids:)
+        update_transaction_states(batch_id, exported_ids: exported_ids, state: 12_000)
+      end
+
+      private
+
+      def ensure_prelive_environment!
+        return if config.environment.to_sym == :prelive
+
+        raise Errors::ConfigurationError,
+              'Batch transaction endpoints are only available in prelive environment. ' \
+              "Current environment: #{config.environment}"
+      end
+
+      def validate_id!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_exported_ids!(exported_ids)
+        if exported_ids.nil? || !exported_ids.is_a?(Array) || exported_ids.empty?
+          raise Errors::ValidationError,
+                'exported_ids is required and must be a non-empty array'
+        end
+
+        return unless exported_ids.any? { |id| id.nil? || id.to_s.strip.empty? }
+
+        raise Errors::ValidationError,
+              'exported_ids cannot contain nil or empty values'
+      end
+
+      def validate_state!(state)
+        valid_states = [12_700, 12_000]
+
+        return if valid_states.include?(state)
+
+        raise Errors::ValidationError,
+              "state must be 12700 (bank_processing) or 12000 (successful), got: #{state}"
+      end
+
+      def validate_transaction_type!(transaction_type)
+        return if TRANSACTION_TYPES.include?(transaction_type.to_s)
+
+        raise Errors::ValidationError,
+              "transaction_type must be one of: #{TRANSACTION_TYPES.join(', ')}"
+      end
+
+      def validate_transaction_type_method!(transaction_type_method)
+        return if TRANSACTION_TYPE_METHODS.include?(transaction_type_method.to_s)
+
+        raise Errors::ValidationError,
+              "transaction_type_method must be one of: #{TRANSACTION_TYPE_METHODS.join(', ')}"
+      end
+
+      def validate_direction!(direction)
+        return if DIRECTIONS.include?(direction.to_s)
+
+        raise Errors::ValidationError,
+              "direction must be one of: #{DIRECTIONS.join(', ')}"
+      end
+
+      def validate_list_options(options)
+        validate_transaction_type!(options[:transaction_type]) if options[:transaction_type]
+        validate_transaction_type_method!(options[:transaction_type_method]) if options[:transaction_type_method]
+        validate_direction!(options[:direction]) if options[:direction]
+      end
+
+      def build_list_params(options)
+        {
+          limit: options.fetch(:limit, 10),
+          offset: options.fetch(:offset, 0),
+          account_id: options[:account_id],
+          batch_id: options[:batch_id],
+          item_id: options[:item_id],
+          transaction_type: options[:transaction_type],
+          transaction_type_method: options[:transaction_type_method],
+          direction: options[:direction],
+          created_before: options[:created_before],
+          created_after: options[:created_after],
+          disbursement_bank: options[:disbursement_bank],
+          processing_bank: options[:processing_bank]
+        }.compact
+      end
+    end
+  end
+end

data/lib/zai_payment/resources/user.rb

@@ -277,7 +277,13 @@ module ZaiPayment
       # @example
       #   users = ZaiPayment::Resources::User.new
       #   response = users.wallet_account("user_id")
-      #   response.data # => {"id" => "...", "balance" => ..., ...}
+      #   # The response.data method automatically extracts the wallet_accounts object
+      #   wallet = response.data
+      #   wallet["id"] # => "5c1c6b10-4c56-0137-8cd7-0242ac110002"
+      #   wallet["balance"] # => 663337
+      #   wallet["currency"] # => "AUD"
+      #   wallet["active"] # => true
+      #   wallet["links"]["transactions"] # => "/wallet_accounts/.../transactions"
       #
       # @see https://developer.hellozai.com/reference/showuserwalletaccounts
       def wallet_account(user_id)

data/lib/zai_payment/resources/wallet_account.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # WalletAccount resource for managing Zai wallet accounts
+    #
+    # @see https://developer.hellozai.com/reference
+    class WalletAccount
+      attr_reader :client
+
+      # Map of attribute keys to API field names for pay_bill
+      PAY_BILL_FIELD_MAPPING = {
+        account_id: :account_id,
+        amount: :amount,
+        reference_id: :reference_id
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # Get a specific wallet account by ID
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @return [Response] the API response containing wallet account details
+      #
+      # @example
+      #   wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+      #   response = wallet_accounts.show("wallet_account_id")
+      #   response.data # => {"id" => "wallet_account_id", "active" => true, ...}
+      #
+      # @see https://developer.hellozai.com/reference
+      def show(wallet_account_id)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        client.get("/wallet_accounts/#{wallet_account_id}")
+      end
+
+      # Get the user associated with a Wallet Account
+      #
+      # Show the User the Wallet Account is associated with using a given wallet_account_id.
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @return [Response] the API response containing user details
+      #
+      # @example
+      #   wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+      #   response = wallet_accounts.show_user("wallet_account_id")
+      #   response.data # => {"id" => "user_id", "full_name" => "Samuel Seller", ...}
+      #
+      # @see https://developer.hellozai.com/reference
+      def show_user(wallet_account_id)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        client.get("/wallet_accounts/#{wallet_account_id}/users")
+      end
+
+      # Get NPP details for a Wallet Account
+      #
+      # Show NPP details of a specific Wallet Account using a given wallet_account_id.
+      # NPP (New Payments Platform) details include PayID and payment reference information.
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @return [Response] the API response containing NPP details
+      #
+      # @example
+      #   wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+      #   response = wallet_accounts.show_npp_details("wallet_account_id")
+      #   response.data # => {"id" => "wallet_account_id", "npp_details" => {...}}
+      #
+      # @see https://developer.hellozai.com/reference
+      def show_npp_details(wallet_account_id)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        client.get("/wallet_accounts/#{wallet_account_id}/npp_details")
+      end
+
+      # Get BPay details for a Wallet Account
+      #
+      # Show BPay details of a specific Wallet Account using a given wallet_account_id.
+      # BPay details include biller code, reference, and amount information.
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @return [Response] the API response containing BPay details
+      #
+      # @example
+      #   wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+      #   response = wallet_accounts.show_bpay_details("wallet_account_id")
+      #   response.data # => {"id" => "wallet_account_id", "bpay_details" => {...}}
+      #
+      # @see https://developer.hellozai.com/reference
+      def show_bpay_details(wallet_account_id)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        client.get("/wallet_accounts/#{wallet_account_id}/bpay_details")
+      end
+
+      # Pay a bill by withdrawing funds from a Wallet Account to a specified BPay account
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @param attributes [Hash] bill payment attributes
+      # @option attributes [String] :account_id (Required) BPay account ID to withdraw to
+      # @option attributes [Integer] :amount (Required) Amount in cents to withdraw
+      # @option attributes [String] :reference_id Optional unique reference information
+      # @return [Response] the API response containing disbursement details
+      #
+      # @example Pay a bill
+      #   wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+      #   response = wallet_accounts.pay_bill(
+      #     '901d8cd0-6af3-0138-967d-0a58a9feac04',
+      #     account_id: 'c1824ad0-73f1-0138-3700-0a58a9feac09',
+      #     amount: 173,
+      #     reference_id: 'test100'
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference
+      def pay_bill(wallet_account_id, **attributes)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        validate_pay_bill_attributes!(attributes)
+
+        body = build_pay_bill_body(attributes)
+        client.post("/wallet_accounts/#{wallet_account_id}/bill_payment", body: body)
+      end
+
+      private
+
+      def validate_id!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_pay_bill_attributes!(attributes)
+        validate_required_pay_bill_attributes!(attributes)
+        validate_amount!(attributes[:amount]) if attributes[:amount]
+        validate_reference_id!(attributes[:reference_id]) if attributes[:reference_id]
+      end
+
+      def validate_required_pay_bill_attributes!(attributes)
+        required_fields = %i[account_id amount]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || (attributes[field].respond_to?(:to_s) && attributes[field].to_s.strip.empty?)
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_amount!(amount)
+        # Amount must be a positive integer
+        return if amount.is_a?(Integer) && amount.positive?
+
+        raise Errors::ValidationError, 'amount must be a positive integer'
+      end
+
+      def validate_reference_id!(reference_id)
+        # Reference ID cannot contain single quote character
+        return unless reference_id.to_s.include?("'")
+
+        raise Errors::ValidationError, "reference_id cannot contain single quote (') character"
+      end
+
+      def build_pay_bill_body(attributes)
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = PAY_BILL_FIELD_MAPPING[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/zai_payment/response.rb

@@ -7,8 +7,8 @@ module ZaiPayment
 
     RESPONSE_DATA_KEYS = %w[
       webhooks users items fees transactions
-      batch_transactions bpay_accounts bank_accounts card_accounts
-      routing_number
+      batch_transactions batches bpay_accounts bank_accounts card_accounts
+      wallet_accounts routing_number disbursements
     ].freeze
 
     def initialize(faraday_response)

data/lib/zai_payment/version.rb

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

data/lib/zai_payment.rb

@@ -16,6 +16,8 @@ require_relative 'zai_payment/resources/item'
 require_relative 'zai_payment/resources/token_auth'
 require_relative 'zai_payment/resources/bank_account'
 require_relative 'zai_payment/resources/bpay_account'
+require_relative 'zai_payment/resources/batch_transaction'
+require_relative 'zai_payment/resources/wallet_account'
 
 module ZaiPayment
   class << self
@@ -69,5 +71,15 @@ module ZaiPayment
     def bpay_accounts
       @bpay_accounts ||= Resources::BpayAccount.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::BatchTransaction] batch_transaction resource instance (prelive only)
+    def batch_transactions
+      @batch_transactions ||= Resources::BatchTransaction.new(client: Client.new(base_endpoint: :core_base))
+    end
+
+    # @return [ZaiPayment::Resources::WalletAccount] wallet_account resource instance
+    def wallet_accounts
+      @wallet_accounts ||= Resources::WalletAccount.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end

data/readme.md

@@ -22,8 +22,11 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 - 👥 **User Management** - Create and manage payin (buyers) & payout (sellers) users  
 - 📦 **Item Management** - Full CRUD for transactions/payments between buyers and sellers  
 - 🏦 **Bank Account Management** - Complete CRUD + validation for AU/UK bank accounts  
+- 💳 **BPay Account Management** - Manage BPay accounts for Australian bill payments  
+- 💼 **Wallet Account Management** - Show wallet accounts, check balances, and pay bills via BPay  
 - 🎫 **Token Auth** - Generate secure tokens for bank and card account data collection  
 - 🪝 **Webhooks** - Full CRUD + secure signature verification (HMAC SHA256)  
+- 🧪 **Batch Transactions** - Prelive-only endpoints for testing batch transaction flows  
 - ⚙️ **Environment-Aware** - Seamless Pre-live / Production switching  
 - 🧱 **Modular & Extensible** - Clean resource-based architecture  
 - 🧰 **Zero Heavy Dependencies** - Lightweight, fast, and reliable  
@@ -115,6 +118,48 @@ Manage bank accounts for Australian and UK users, with routing number validation
 - 💡 [Bank Account Examples](examples/bank_accounts.md) - Real-world patterns and integration
 - 🔗 [Zai: Bank Accounts API Reference](https://developer.hellozai.com/reference/showbankaccount)
 
+### BPay Accounts
+
+Manage BPay accounts for Australian bill payments.
+
+**📚 Documentation:**
+- 📖 [BPay Account Management Guide](docs/bpay_accounts.md) - Complete guide for BPay accounts
+- 💡 [BPay Account Examples](examples/bpay_accounts.md) - Real-world patterns and bill payment workflows
+- 🔗 [Zai: BPay Accounts API Reference](https://developer.hellozai.com/reference/createbpayaccount)
+
+### Wallet Accounts
+
+Manage wallet accounts, check balances, and pay bills via BPay.
+
+**📚 Documentation:**
+- 📖 [Wallet Account Management Guide](docs/wallet_accounts.md) - Complete guide for wallet accounts
+- 💡 [Wallet Account Examples](examples/wallet_accounts.md) - Real-world patterns and payment workflows
+- 🔗 [Zai: Wallet Accounts API Reference](https://developer.hellozai.com/reference)
+
+**Quick Example:**
+```ruby
+wallet_accounts = ZaiPayment::Resources::WalletAccount.new
+
+# Check wallet balance
+response = wallet_accounts.show('wallet_account_id')
+balance = response.data['balance']  # in cents
+puts "Balance: $#{balance / 100.0}"
+
+# Pay a bill from wallet to BPay account
+payment_response = wallet_accounts.pay_bill(
+  'wallet_account_id',
+  account_id: 'bpay_account_id',
+  amount: 17300,  # $173.00 in cents
+  reference_id: 'bill_nov_2024'
+)
+
+if payment_response.success?
+  disbursement = payment_response.data
+  puts "Payment successful: #{disbursement['id']}"
+  puts "State: #{disbursement['state']}"
+end
+```
+
 ### Token Auth
 
 Generate secure tokens for collecting bank and card account information.
@@ -133,6 +178,35 @@ Manage webhook endpoints with secure signature verification.
 - 🏗️ [Architecture & Implementation](docs/webhooks.md) - Detailed technical documentation
 - 🔐 [Signature Verification Details](docs/webhook_signature.md) - Security implementation specs
 
+### Batch Transactions (Prelive Only)
+
+Simulate batch transaction processing for testing in the prelive environment.
+
+**📚 Documentation:**
+- 📖 [Batch Transaction Guide](docs/batch_transactions.md) - Complete guide and method reference
+- 💡 [Batch Transaction Examples](examples/batch_transactions.md) - Testing workflows and webhook simulation
+- ⚠️ **Note:** These endpoints are only available in prelive environment
+
+**Quick Example:**
+```ruby
+# Export pending transactions to batched state
+export_response = ZaiPayment.batch_transactions.export_transactions
+batch_id = export_response.data.first['batch_id']
+transaction_ids = export_response.data.map { |t| t['id'] }
+
+# Move to bank_processing state
+ZaiPayment.batch_transactions.process_to_bank_processing(
+  batch_id,
+  exported_ids: transaction_ids
+)
+
+# Complete processing (triggers webhooks)
+ZaiPayment.batch_transactions.process_to_successful(
+  batch_id,
+  exported_ids: transaction_ids
+)
+```
+
 ### Error Handling
 
 The gem provides specific error classes for different scenarios:
@@ -167,10 +241,12 @@ end
 | ✅ Users                        | Manage PayIn / PayOut users       | Done           |
 | ✅ Items                        | Transactions/payments (CRUD)      | Done           |
 | ✅ Bank Accounts                | AU/UK bank accounts + validation  | Done           |
+| ✅ BPay Accounts                | Manage BPay accounts              | Done           |
+| ✅ Wallet Accounts              | Show, check balance, pay bills    | Done           |
 | ✅ Token Auth                   | Generate bank/card tokens         | Done           |
-| 💳 Payments                     | Single and recurring payments     | 🚧 In progress |
+| ✅ Batch Transactions (Prelive) | Simulate batch processing flows   | Done           |
+| ✅ Payments                     | Single and recurring payments     | Done           |
 | 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
-| 💼 Wallets                      | Create and manage wallet accounts | ⏳ Planned      |
 
 ## 🧪 Development
 
@@ -227,6 +303,8 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 - [**User Management Guide**](docs/users.md) - Managing payin and payout users
 - [**Item Management Guide**](docs/items.md) - Creating and managing transactions/payments
 - [**Bank Account Guide**](docs/bank_accounts.md) - Managing bank accounts for AU/UK users
+- [**BPay Account Guide**](docs/bpay_accounts.md) - Managing BPay accounts for Australian bill payments
+- [**Wallet Account Guide**](docs/wallet_accounts.md) - Managing wallet accounts, checking balances, and paying bills
 - [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
 - [**Documentation Index**](docs/readme.md) - Full documentation navigation
 
@@ -234,12 +312,16 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 - [User Examples](examples/users.md) - Real-world user management patterns
 - [Item Examples](examples/items.md) - Transaction and payment workflows
 - [Bank Account Examples](examples/bank_accounts.md) - Bank account integration patterns
+- [BPay Account Examples](examples/bpay_accounts.md) - BPay account integration patterns
+- [Wallet Account Examples](examples/wallet_accounts.md) - Wallet account and bill payment workflows
 - [Token Auth Examples](examples/token_auths.md) - Secure token generation and integration
 - [Webhook Examples](examples/webhooks.md) - Webhook integration patterns
+- [Batch Transaction Examples](examples/batch_transactions.md) - Testing batch transaction flows (prelive only)
 
 ### Technical Guides
 - [Webhook Architecture](docs/webhooks.md) - Technical implementation details
 - [Architecture Overview](docs/architecture.md) - System architecture and design
+- [**Direct API Usage Guide**](docs/direct_api_usage.md) - 🔥 How to call unimplemented APIs directly
 
 ### Security
 - [Webhook Security Quick Start](docs/webhook_security_quickstart.md) - 5-minute setup guide