zai_payment 2.0.2 → 2.2.0

data/lib/zai_payment/resources/token_auth.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # TokenAuth resource for generating tokens for bank or card accounts
+    #
+    # @see https://developer.hellozai.com/reference/generatetoken
+    class TokenAuth
+      attr_reader :client
+
+      # Token types
+      TOKEN_TYPE_BANK = 'bank'
+      TOKEN_TYPE_CARD = 'card'
+
+      # Valid token types
+      VALID_TOKEN_TYPES = [TOKEN_TYPE_BANK, TOKEN_TYPE_CARD].freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new(base_endpoint: :core_base)
+      end
+
+      # Generate a token for bank or card account
+      #
+      # Create a token, either for a bank or a card account, that can be used with the
+      # PromisePay.js package to securely send Assembly credit card details.
+      #
+      # @param user_id [String] (Required) Buyer or Seller ID (already created)
+      # @param token_type [String] Token type ID, use 'bank' or 'card' (default: 'bank')
+      # @return [Response] the API response containing generated token
+      #
+      # @example Generate a bank token
+      #   token_auth = ZaiPayment::Resources::TokenAuth.new
+      #   response = token_auth.generate(
+      #     user_id: "seller-68611249",
+      #     token_type: "bank"
+      #   )
+      #   response.data # => {"token_auth" => {"token" => "...", "user_id" => "...", ...}}
+      #
+      # @example Generate a card token
+      #   token_auth = ZaiPayment::Resources::TokenAuth.new
+      #   response = token_auth.generate(
+      #     user_id: "buyer-12345",
+      #     token_type: "card"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/generatetoken
+      def generate(user_id:, token_type: TOKEN_TYPE_BANK)
+        validate_user_id!(user_id)
+        validate_token_type!(token_type)
+
+        body = {
+          token_type: token_type,
+          user_id: user_id
+        }
+
+        client.post('/token_auths', body: body)
+      end
+
+      private
+
+      def validate_user_id!(user_id)
+        return unless user_id.nil? || user_id.to_s.strip.empty?
+
+        raise Errors::ValidationError, 'user_id is required and cannot be blank'
+      end
+
+      def validate_token_type!(token_type)
+        return if VALID_TOKEN_TYPES.include?(token_type.to_s.downcase)
+
+        raise Errors::ValidationError,
+              "token_type must be one of: #{VALID_TOKEN_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/zai_payment/resources/user.rb

@@ -107,7 +107,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 +264,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 +408,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 +418,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.0.2'
+  VERSION = '2.2.0'
 end

data/lib/zai_payment.rb

@@ -13,6 +13,7 @@ require_relative 'zai_payment/response'
 require_relative 'zai_payment/resources/webhook'
 require_relative 'zai_payment/resources/user'
 require_relative 'zai_payment/resources/item'
+require_relative 'zai_payment/resources/token_auth'
 
 module ZaiPayment
   class << self
@@ -51,5 +52,10 @@ module ZaiPayment
     def items
       @items ||= Resources::Item.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::TokenAuth] token_auth resource instance
+    def token_auths
+      @token_auths ||= Resources::TokenAuth.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end

data/readme.md

@@ -21,6 +21,7 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 - 🧠 **Smart Token Caching** - Auto-refresh before expiration, thread-safe storage  
 - 👥 **User Management** - Create and manage payin (buyers) & payout (sellers) users  
 - 📦 **Item Management** - Full CRUD for transactions/payments between buyers and sellers  
+- 🎫 **Token Auth** - Generate secure tokens for bank and card account data collection  
 - 🪝 **Webhooks** - Full CRUD + secure signature verification (HMAC SHA256)  
 - ⚙️ **Environment-Aware** - Seamless Pre-live / Production switching  
 - 🧱 **Modular & Extensible** - Clean resource-based architecture  
@@ -87,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',
@@ -96,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',
@@ -109,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',
@@ -133,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:**
@@ -183,6 +208,34 @@ response = ZaiPayment.items.list_transactions('item_id')
 - 💡 [Item Examples](examples/items.md) - Real-world usage patterns and complete workflows
 - 🔗 [Zai: Items API Reference](https://developer.hellozai.com/reference/listitems)
 
+### Token Auth
+
+Generate secure tokens for collecting bank and card account information:
+
+```ruby
+# Generate a bank token (for collecting bank account details)
+response = ZaiPayment.token_auths.generate(
+  user_id: "seller-68611249",
+  token_type: "bank"
+)
+
+token = response.data['token_auth']['token']
+# Use this token with PromisePay.js on the frontend
+
+# Generate a card token (for collecting credit card details)
+response = ZaiPayment.token_auths.generate(
+  user_id: "buyer-12345",
+  token_type: "card"
+)
+
+token = response.data['token_auth']['token']
+# Use this token with PromisePay.js on the frontend
+```
+
+**📚 Documentation:**
+- 💡 [Token Auth Examples](examples/token_auths.md) - Complete integration guide with PromisePay.js
+- 🔗 [Zai: Generate Token API Reference](https://developer.hellozai.com/reference/generatetoken)
+
 ### Webhooks
 
 Manage webhook endpoints:
@@ -243,6 +296,7 @@ end
 | ✅ Webhooks                     | CRUD for webhook endpoints        | Done           |
 | ✅ Users                        | Manage PayIn / PayOut users       | Done           |
 | ✅ Items                        | Transactions/payments (CRUD)      | Done           |
+| ✅ Token Auth                   | Generate bank/card tokens         | Done           |
 | 💳 Payments                     | Single and recurring payments     | 🚧 In progress |
 | 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
 | 💼 Wallets                      | Create and manage wallet accounts | ⏳ Planned      |
@@ -307,6 +361,7 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 ### Examples & Patterns
 - [User Examples](examples/users.md) - Real-world user management patterns
 - [Item Examples](examples/items.md) - Transaction and payment workflows
+- [Token Auth Examples](examples/token_auths.md) - Secure token generation and integration
 - [Webhook Examples](examples/webhooks.md) - Webhook integration patterns
 
 ### Technical Guides

data/token_auth_implementation_summary.md

@@ -0,0 +1,249 @@
+# Token Auth API Implementation Summary
+
+## Overview
+
+Successfully implemented the **Generate Token** endpoint from the Zai API (https://developer.hellozai.com/reference/generatetoken) to enable secure bank and card account data collection.
+
+## What Was Implemented
+
+### 1. Core Resource Implementation
+
+**File:** `lib/zai_payment/resources/token_auth.rb`
+
+- Created `TokenAuth` resource class following the project's resource pattern
+- Implemented `generate(user_id:, token_type:)` method
+- Added token type validation (bank or card)
+- Added user ID validation
+- Support for case-insensitive token types
+- Default token type: 'bank'
+
+**Key Features:**
+```ruby
+# Generate a bank token (default)
+ZaiPayment.token_auths.generate(user_id: "seller-123")
+
+# Generate a card token
+ZaiPayment.token_auths.generate(user_id: "buyer-123", token_type: "card")
+```
+
+### 2. Module Integration
+
+**File:** `lib/zai_payment.rb`
+
+- Added `require_relative` for token_auth resource
+- Added `token_auths` accessor method
+- Configured to use `core_base` endpoint (https://test.api.promisepay.com)
+
+### 3. Test Suite
+
+**File:** `spec/zai_payment/resources/token_auth_spec.rb`
+
+- 15 comprehensive test cases covering:
+  - Bank token generation
+  - Card token generation
+  - Default token type behavior
+  - Validation errors (nil, empty, whitespace, invalid types)
+  - Case-insensitive token types
+  - Client initialization
+  - Constants verification
+- All tests passing with 95.22% line coverage
+- Follows project's testing pattern using Faraday test stubs
+- RuboCop compliant
+
+### 4. Documentation
+
+**File:** `examples/token_auths.md` (600+ lines)
+
+Comprehensive examples including:
+- Basic usage patterns
+- Bank token collection workflows
+- Card token collection workflows
+- Rails controller integration
+- Service object pattern
+- Frontend integration with PromisePay.js
+- Complete payment flow examples
+- Error handling strategies
+- Retry logic with exponential backoff
+- Security best practices:
+  - Token expiry management
+  - Audit logging
+  - Rate limiting protection
+
+**File:** `docs/token_auths.md` (500+ lines)
+
+Complete technical guide covering:
+- When to use Token Auth
+- How it works (flow diagram)
+- API methods reference
+- Token types (bank vs card) with use cases
+- Security considerations (PCI compliance, token lifecycle)
+- Integration guide (backend + frontend)
+- Error handling patterns
+- Best practices with code examples
+- Related resources and API references
+
+### 5. Version Updates
+
+**File:** `lib/zai_payment/version.rb`
+
+- Updated version from `2.0.2` to `2.1.0`
+- Follows semantic versioning (minor version bump for new feature)
+
+### 6. Changelog
+
+**File:** `changelog.md`
+
+Added comprehensive release notes for version 2.1.0:
+- Feature description
+- API methods
+- Documentation additions
+- Testing coverage
+- Link to full changelog
+
+### 7. README Updates
+
+**File:** `readme.md`
+
+- Added Token Auth to features list (🎫 emoji)
+- Added Token Auth section with quick examples
+- Updated roadmap (marked Token Auth as Done ✅)
+- Added documentation links in Examples & Patterns section
+
+### 8. Documentation Index
+
+**File:** `docs/readme.md`
+
+- Added token_auths.md to Architecture & Design section
+- Added Token Auth Examples to Examples section
+- Added Token Auth to Quick Links with guide, examples, and API reference
+- Updated documentation structure tree
+- Added tips for collecting payment data
+
+## API Endpoint
+
+**POST** `https://test.api.promisepay.com/token_auths`
+
+**Request Body:**
+```json
+{
+  "token_type": "bank",  // or "card"
+  "user_id": "seller-68611249"
+}
+```
+
+**Response:**
+```json
+{
+  "token_auth": {
+    "token": "tok_bank_abc123...",
+    "user_id": "seller-68611249",
+    "token_type": "bank",
+    "created_at": "2025-10-24T12:00:00Z",
+    "expires_at": "2025-10-24T13:00:00Z"
+  }
+}
+```
+
+## Usage Example
+
+```ruby
+# Configure the gem
+ZaiPayment.configure do |c|
+  c.environment   = :prelive
+  c.client_id     = ENV['ZAI_CLIENT_ID']
+  c.client_secret = ENV['ZAI_CLIENT_SECRET']
+  c.scope         = ENV['ZAI_OAUTH_SCOPE']
+end
+
+# Generate a card token for buyer
+response = ZaiPayment.token_auths.generate(
+  user_id: "buyer-12345",
+  token_type: "card"
+)
+
+token = response.data['token_auth']['token']
+# Send token to frontend for use with PromisePay.js
+```
+
+## Integration with PromisePay.js
+
+```javascript
+// Frontend (JavaScript)
+PromisePay.setToken(token_from_backend);
+
+PromisePay.createCardAccount({
+  card_number: '4111111111111111',
+  expiry_month: '12',
+  expiry_year: '2025',
+  cvv: '123'
+}, function(response) {
+  if (response.error) {
+    console.error('Error:', response.error);
+  } else {
+    const cardAccountId = response.card_accounts.id;
+    // Send cardAccountId back to backend
+  }
+});
+```
+
+## Test Results
+
+- **Total Tests:** 272 examples
+- **Failures:** 0
+- **Line Coverage:** 95.22% (518 / 544)
+- **Branch Coverage:** 80.79% (143 / 177)
+- **RuboCop:** No offenses detected
+
+## Files Created
+
+1. `lib/zai_payment/resources/token_auth.rb` - Core resource implementation
+2. `spec/zai_payment/resources/token_auth_spec.rb` - Test suite
+3. `examples/token_auths.md` - Comprehensive usage examples
+4. `docs/token_auths.md` - Technical documentation
+
+## Files Modified
+
+1. `lib/zai_payment.rb` - Added token_auths accessor
+2. `lib/zai_payment/version.rb` - Version bump to 2.1.0
+3. `changelog.md` - Added 2.1.0 release notes
+4. `readme.md` - Added Token Auth documentation
+5. `docs/readme.md` - Updated documentation index
+
+## Security Considerations
+
+- **PCI Compliance:** Tokens enable PCI-compliant card data collection without sensitive data touching your server
+- **Token Expiration:** Tokens have limited lifespan (typically 1 hour)
+- **Single-use:** Tokens should be generated fresh for each session
+- **User-specific:** Each token is tied to a specific user ID
+- **Type-specific:** Bank tokens only for bank accounts, card tokens only for cards
+- **HTTPS Required:** All communication over secure HTTPS
+
+## Next Steps
+
+The Token Auth implementation is complete and ready for use. Developers can now:
+
+1. Generate tokens for buyers to collect credit card information
+2. Generate tokens for sellers to collect bank account details
+3. Integrate with PromisePay.js for secure frontend data collection
+4. Process payments without handling sensitive payment data directly
+
+## Related APIs
+
+This implementation complements existing resources:
+- **Users API** - Create users before generating tokens
+- **Items API** - Use payment accounts to create transactions
+- **Webhooks API** - Receive notifications about payment events
+
+## Documentation Links
+
+- **API Reference:** https://developer.hellozai.com/reference/generatetoken
+- **Examples:** [examples/token_auths.md](examples/token_auths.md)
+- **Guide:** [docs/token_auths.md](docs/token_auths.md)
+- **PromisePay.js:** https://developer.hellozai.com/docs/promisepay-js
+
+---
+
+**Implementation Date:** October 24, 2025  
+**Version:** 2.1.0  
+**Status:** ✅ Complete and tested
+