zai_payment 2.5.0 → 2.6.1

data/lib/zai_payment/resources/bpay_account.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # BpayAccount resource for managing Zai BPay accounts
+    #
+    # @see https://developer.hellozai.com/reference/createbpayaccount
+    class BpayAccount
+      attr_reader :client
+
+      # Map of attribute keys to API field names
+      FIELD_MAPPING = {
+        user_id: :user_id,
+        account_name: :account_name,
+        biller_code: :biller_code,
+        bpay_crn: :bpay_crn
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # Get a specific BPay account by ID
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response containing BPay account details
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.show("bpay_account_id")
+      #   response.data # => {"id" => "bpay_account_id", "active" => true, ...}
+      #
+      # @see https://developer.hellozai.com/reference/showbpayaccount
+      def show(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.get("/bpay_accounts/#{bpay_account_id}")
+      end
+
+      # Redact a BPay account
+      #
+      # Redacts a BPay account using the given bpay_account_id. Redacted BPay accounts
+      # can no longer be used as a disbursement destination.
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.redact("bpay_account_id")
+      #
+      # @see https://developer.hellozai.com/reference/redactbpayaccount
+      def redact(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.delete("/bpay_accounts/#{bpay_account_id}")
+      end
+
+      # Get the user associated with a BPay account
+      #
+      # Show the User the BPay Account is associated with using a given bpay_account_id.
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response containing user details
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.show_user("bpay_account_id")
+      #   response.data # => {"id" => "user_id", "full_name" => "Samuel Seller", ...}
+      #
+      # @see https://developer.hellozai.com/reference/showbpayaccountuser
+      def show_user(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.get("/bpay_accounts/#{bpay_account_id}/users")
+      end
+
+      # Create a new BPay account
+      #
+      # Create a BPay Account to be used as a Disbursement destination.
+      #
+      # @param attributes [Hash] BPay account attributes
+      # @option attributes [String] :user_id (Required) User ID
+      # @option attributes [String] :account_name (Required) Name assigned by the platform/marketplace
+      #   to identify the account (similar to a nickname). Defaults to "My Water Bill Company"
+      # @option attributes [Integer] :biller_code (Required) The Biller Code for the biller that will
+      #   receive the payment. The Biller Code must be a numeric value with 3 to 10 digits.
+      # @option attributes [String] :bpay_crn (Required) Customer reference number (crn) to be used for
+      #   this bpay account. The CRN must contain between 2 and 20 digits. Defaults to "987654321"
+      # @return [Response] the API response containing created BPay account
+      #
+      # @example Create a BPay account
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.create(
+      #     user_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      #     account_name: 'My Water Bill Company',
+      #     biller_code: 123456,
+      #     bpay_crn: '987654321'
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createbpayaccount
+      def create(**attributes)
+        validate_create_attributes!(attributes)
+
+        body = build_bpay_account_body(attributes)
+        client.post('/bpay_accounts', 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_create_attributes!(attributes)
+        validate_required_attributes!(attributes)
+        validate_biller_code!(attributes[:biller_code]) if attributes[:biller_code]
+        validate_bpay_crn!(attributes[:bpay_crn]) if attributes[:bpay_crn]
+      end
+
+      def validate_required_attributes!(attributes)
+        required_fields = %i[user_id account_name biller_code bpay_crn]
+
+        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_biller_code!(biller_code)
+        # Biller code must be a numeric value with 3 to 10 digits
+        biller_code_str = biller_code.to_s
+
+        return if biller_code_str.match?(/\A\d{3,10}\z/)
+
+        raise Errors::ValidationError,
+              'biller_code must be a numeric value with 3 to 10 digits'
+      end
+
+      def validate_bpay_crn!(bpay_crn)
+        # CRN must contain between 2 and 20 digits
+        bpay_crn_str = bpay_crn.to_s
+
+        return if bpay_crn_str.match?(/\A\d{2,20}\z/)
+
+        raise Errors::ValidationError,
+              'bpay_crn must contain between 2 and 20 digits'
+      end
+
+      def build_bpay_account_body(attributes)
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = FIELD_MAPPING[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      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/response.rb

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

data/lib/zai_payment/version.rb

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

data/lib/zai_payment.rb

@@ -15,6 +15,7 @@ require_relative 'zai_payment/resources/user'
 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'
 
 module ZaiPayment
   class << self
@@ -63,5 +64,10 @@ module ZaiPayment
     def bank_accounts
       @bank_accounts ||= Resources::BankAccount.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::BpayAccount] bpay_account resource instance
+    def bpay_accounts
+      @bpay_accounts ||= Resources::BpayAccount.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.1
 platform: ruby
 authors:
 - Eddy Jaga
@@ -69,6 +69,7 @@ files:
 - docs/architecture.md
 - docs/authentication.md
 - docs/bank_accounts.md
+- docs/bpay_accounts.md
 - docs/items.md
 - docs/readme.md
 - docs/token_auths.md
@@ -79,13 +80,12 @@ files:
 - docs/webhook_signature.md
 - docs/webhooks.md
 - examples/bank_accounts.md
+- examples/bpay_accounts.md
 - examples/items.md
 - examples/rails_card_payment.md
 - examples/token_auths.md
 - examples/users.md
 - examples/webhooks.md
-- implementation.md
-- implementation_summary.md
 - lib/zai_payment.rb
 - lib/zai_payment/auth/token_provider.rb
 - lib/zai_payment/auth/token_store.rb
@@ -94,6 +94,7 @@ files:
 - lib/zai_payment/config.rb
 - lib/zai_payment/errors.rb
 - lib/zai_payment/resources/bank_account.rb
+- lib/zai_payment/resources/bpay_account.rb
 - lib/zai_payment/resources/item.rb
 - lib/zai_payment/resources/token_auth.rb
 - lib/zai_payment/resources/user.rb

data/implementation.md

@@ -1,304 +0,0 @@
-# User Management Implementation Summary
-
-## Overview
-
-This document summarizes the implementation of the User Management feature for the Zai Payment Ruby library.
-
-## Implementation Date
-
-October 23, 2025
-
-## What Was Implemented
-
-### 1. User Resource Class (`lib/zai_payment/resources/user.rb`)
-
-A comprehensive User resource that provides CRUD operations for managing both payin (buyer) and payout (seller/merchant) users.
-
-**Key Features:**
-- ✅ List users with pagination
-- ✅ Show user details by ID
-- ✅ Create payin users (buyers)
-- ✅ Create payout users (sellers/merchants)
-- ✅ Update user information
-- ✅ Comprehensive validation for all user types
-- ✅ Support for all Zai API user fields
-
-**Supported Fields:**
-- Email, first name, last name (required)
-- Country (ISO 3166-1 alpha-3 code, required)
-- Address details (line1, line2, city, state, zip)
-- Contact information (mobile, phone)
-- Date of birth (DD/MM/YYYY format)
-- Government ID number
-- Device ID and IP address (for fraud prevention)
-- User type designation (payin/payout)
-
-**Validation:**
-- Required field validation
-- Email format validation
-- Country code validation (3-letter ISO codes)
-- Date of birth format validation (DD/MM/YYYY)
-- User type validation (payin/payout)
-
-### 2. Client Updates (`lib/zai_payment/client.rb`)
-
-**Changes:**
-- Added `base_endpoint` parameter to constructor
-- Updated `base_url` method to support multiple API endpoints
-- Users API uses `core_base` endpoint
-- Webhooks API uses `va_base` endpoint
-
-### 3. Response Updates (`lib/zai_payment/response.rb`)
-
-**Changes:**
-- Updated `data` method to handle both `webhooks` and `users` response formats
-- Maintains backward compatibility with existing webhook code
-
-### 4. Main Module Integration (`lib/zai_payment.rb`)
-
-**Changes:**
-- Added `require` for User resource
-- Added `users` accessor method
-- Properly configured User resource to use `core_base` endpoint
-
-### 5. Comprehensive Test Suite (`spec/zai_payment/resources/user_spec.rb`)
-
-**Test Coverage:**
-- List users with pagination
-- Show user details
-- Create payin users with various configurations
-- Create payout users with required fields
-- Validation error handling
-- API error handling
-- Update operations
-- User type validation
-- Integration with main module
-
-**Test Statistics:**
-- 40+ test cases
-- Covers all CRUD operations
-- Tests both success and error scenarios
-- Validates all field types
-- Tests integration points
-
-### 6. Documentation
-
-#### User Guide (`docs/users.md`)
-Comprehensive guide covering:
-- Overview of payin vs payout users
-- Required fields for each user type
-- Complete API reference
-- Field reference table
-- Error handling patterns
-- Best practices
-- Response structures
-- Complete examples
-
-#### Usage Examples (`examples/users.md`)
-Practical examples including:
-- Basic payin user creation
-- Complete payin user profiles
-- Progressive profile building
-- Individual payout users
-- International users (AU, UK, US)
-- List and pagination
-- Update operations
-- Error handling patterns
-- Rails integration example
-- Batch operations
-- User profile validation helper
-- RSpec integration tests
-- Common patterns with retry logic
-
-#### readme Updates (`readme.md`)
-- Added Users section with quick examples
-- Updated roadmap to mark Users as "Done"
-- Added documentation links
-- Updated Getting Started section
-
-## API Endpoints
-
-The implementation works with the following Zai API endpoints:
-
-- `GET /users` - List users
-- `GET /users/:id` - Show user
-- `POST /users` - Create user
-- `PATCH /users/:id` - Update user
-
-## Usage Examples
-
-### Create a Payin User (Buyer)
-
-```ruby
-response = ZaiPayment.users.create(
-  email: 'buyer@example.com',
-  first_name: 'John',
-  last_name: 'Doe',
-  country: 'USA',
-  mobile: '+1234567890'
-)
-
-user_id = response.data['id']
-```
-
-### Create a Payout User (Seller/Merchant)
-
-```ruby
-response = ZaiPayment.users.create(
-  email: 'seller@example.com',
-  first_name: 'Jane',
-  last_name: 'Smith',
-  country: 'AUS',
-  dob: '01/01/1990',
-  address_line1: '456 Market St',
-  city: 'Sydney',
-  state: 'NSW',
-  zip: '2000',
-  mobile: '+61412345678'
-)
-
-seller_id = response.data['id']
-```
-
-### List Users
-
-```ruby
-response = ZaiPayment.users.list(limit: 10, offset: 0)
-users = response.data
-```
-
-### Show User
-
-```ruby
-response = ZaiPayment.users.show('user_id')
-user = response.data
-```
-
-### Update User
-
-```ruby
-response = ZaiPayment.users.update(
-  'user_id',
-  mobile: '+9876543210',
-  address_line1: '789 New St'
-)
-```
-
-## Key Differences: Payin vs Payout Users
-
-### Payin User (Buyer) Requirements
-**Required:**
-- Email, first name, last name, country
-- Device ID and IP address (when charging)
-
-**Recommended:**
-- Address, city, state, zip
-- Mobile, DOB
-
-### Payout User (Seller/Merchant) Requirements
-**Required:**
-- Email, first name, last name, country
-- Address, city, state, zip
-- Date of birth (DD/MM/YYYY format)
-
-**Recommended:**
-- Mobile, government number
-
-## Validation Rules
-
-1. **Email**: Must be valid email format
-2. **Country**: Must be 3-letter ISO 3166-1 alpha-3 code (e.g., USA, AUS, GBR)
-3. **Date of Birth**: Must be DD/MM/YYYY format (e.g., 01/01/1990)
-4. **User Type**: Must be 'payin' or 'payout' (optional field)
-
-## Error Handling
-
-The implementation provides proper error handling for:
-- `ValidationError` - Missing or invalid fields
-- `UnauthorizedError` - Authentication failures
-- `NotFoundError` - User not found
-- `ApiError` - General API errors
-- `ConnectionError` - Network issues
-- `TimeoutError` - Request timeouts
-
-## Best Practices Implemented
-
-1. **Progressive Profile Building**: Create users with minimal info, update later
-2. **Proper Validation**: Validate data before API calls
-3. **Error Recovery**: Handle errors gracefully with proper error classes
-4. **Type Safety**: Validate user types and field formats
-5. **Documentation**: Comprehensive guides and examples
-6. **Testing**: Extensive test coverage for all scenarios
-
-## Files Created/Modified
-
-### Created Files:
-1. `/lib/zai_payment/resources/user.rb` - User resource class
-2. `/spec/zai_payment/resources/user_spec.rb` - Test suite
-3. `/docs/users.md` - User management guide
-4. `/examples/users.md` - Usage examples
-
-### Modified Files:
-1. `/lib/zai_payment/client.rb` - Added endpoint support
-2. `/lib/zai_payment/response.rb` - Added users data handling
-3. `/lib/zai_payment.rb` - Integrated User resource
-4. `/readme.md` - Added Users section and updated roadmap
-
-## Code Quality
-
-- ✅ No linter errors
-- ✅ Follows existing code patterns
-- ✅ Comprehensive test coverage
-- ✅ Well-documented with YARD comments
-- ✅ Follows Ruby best practices
-- ✅ Consistent with webhook implementation
-
-## Architecture Decisions
-
-1. **Endpoint Routing**: Users use `core_base`, webhooks use `va_base`
-2. **Validation Strategy**: Client-side validation before API calls
-3. **Field Mapping**: Direct 1:1 mapping with Zai API fields
-4. **Error Handling**: Leverage existing error class hierarchy
-5. **Testing Approach**: Match webhook test patterns
-
-## Integration Points
-
-The User resource integrates seamlessly with:
-- Authentication system (OAuth2 tokens)
-- Error handling framework
-- Response wrapper
-- Configuration management
-- Testing infrastructure
-
-## Next Steps
-
-The implementation is complete and ready for use. Recommended next steps:
-
-1. ✅ Run the full test suite
-2. ✅ Review documentation
-3. ✅ Try examples in development environment
-4. Consider adding:
-   - Company user support (for payout users)
-   - User verification status checking
-   - Bank account associations
-   - Payment method attachments
-
-## References
-
-- [Zai: Onboarding a Payin User](https://developer.hellozai.com/docs/onboarding-a-pay-in-user)
-- [Zai: Onboarding a Payout User](https://developer.hellozai.com/docs/onboarding-a-pay-out-user)
-- [Zai API Reference](https://developer.hellozai.com/reference)
-
-## Support
-
-For questions or issues:
-1. Check the documentation in `/docs/users.md`
-2. Review examples in `/examples/users.md`
-3. Run tests: `bundle exec rspec spec/zai_payment/resources/user_spec.rb`
-4. Refer to Zai Developer Portal: https://developer.hellozai.com/
-
----
-
-**Implementation completed successfully! 🎉**
-
-All CRUD operations for User management are now available in the ZaiPayment gem, following best practices and maintaining consistency with the existing codebase.