zai_payment 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c0f57b605f7a885cb3fcbb0e8b4554d782fd298444d49b57732d0214b0a8a14
-  data.tar.gz: 014e39994a1d9051b28d90deaec6407cd638de2ed7995509c0196ec25da6805a
+  metadata.gz: 510e8e99ba15a794801fbfa54f066f9c9df8037b2b4439f1e4f2a11b19509899
+  data.tar.gz: 5f699a364d1cc0f50a6e6e36e4a5ffea274a8c7e761dfa01f0f78d71043f9578
 SHA512:
-  metadata.gz: 24b3058ec5ee8e06b06f9444175a6a86e455a3ba08b2a5f40df990f5ab7beae812d05225e62802b1fd2e69acc37f9364f33d1dc89f37fb045c150c52ae18fd04
-  data.tar.gz: a2e4715f2f8e8630fe4ea03d13ad83318acf4fd09737266de497ecc889af22af84fc7edd0b8d6846658ebc50d4c49ed8d36ae0144190a0d79aeae88d6e398bce
+  metadata.gz: ad9010a7ed0538881749587f2ea3cf2a7e3bf8dde51f1f2856b62a13726f25ef55c5174dce276c024df5d3ea9f7352a049ad2da29e15495dc7e4b838d08c963a
+  data.tar.gz: 2d33996bd2e78ab91f8c2ee27f02d9d5d5f0f139cda22141d4c5e0d0d9358c3906872236f13131448da217665db28ed7d3df360119981b9ba87cc11a2acf9ec6

data/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,183 @@
+# Batch Transactions Implementation Summary
+
+## Overview
+
+Successfully implemented prelive-only batch transaction endpoints for the Zai Payment Ruby gem. These endpoints allow testing and simulation of batch transaction processing flows in the prelive environment.
+
+## Files Created
+
+### 1. Resource Implementation
+**File:** `lib/zai_payment/resources/batch_transaction.rb`
+
+Implements the `BatchTransaction` resource class with the following methods:
+- `export_transactions` - Exports pending batch transactions to batched state
+- `update_transaction_states` - Updates batch transaction states (12700 or 12000)
+- `process_to_bank_processing` - Convenience method for state 12700
+- `process_to_successful` - Convenience method for state 12000 (triggers webhooks)
+
+**Key Features:**
+- Environment validation (prelive-only)
+- Comprehensive parameter validation
+- Clear error messages
+- Full YARD documentation
+
+### 2. Spec File
+**File:** `spec/zai_payment/resources/batch_transaction_spec.rb`
+
+Comprehensive test coverage including:
+- Export transactions functionality
+- Update transaction states with both state codes
+- Convenience methods (process_to_bank_processing, process_to_successful)
+- Environment validation (prelive vs production)
+- Parameter validation for all methods
+- Multiple transaction ID handling
+- Integration with ZaiPayment module
+
+### 3. Documentation
+
+#### Examples
+**File:** `examples/batch_transactions.md`
+- Complete workflow examples
+- Step-by-step usage guide
+- Error handling examples
+- Multiple transaction processing
+- Webhook testing guide
+
+#### Technical Documentation
+**File:** `docs/batch_transactions.md`
+- Complete method reference with signatures
+- Parameter descriptions and types
+- Return value specifications
+- Error handling details
+- State code documentation
+- Lifecycle diagrams
+- Integration examples
+
+## Files Modified
+
+### 1. Main Module
+**File:** `lib/zai_payment.rb`
+- Added require for batch_transaction resource
+- Added `batch_transactions` accessor method
+
+### 2. Response Class
+**File:** `lib/zai_payment/response.rb`
+- Added "batches" to RESPONSE_DATA_KEYS array
+
+### 3. README
+**File:** `readme.md`
+- Added batch transactions to Features section
+- Added new Quick Start section with example
+- Added to Roadmap as completed feature
+- Added to Examples & Patterns section
+- Added documentation links
+
+## API Endpoints Implemented
+
+### 1. Export Transactions
+**Method:** `GET /batch_transactions/export_transactions`
+**Purpose:** Move all pending batch_transactions to batched state
+**Returns:** Array of transactions with batch_id and transaction id
+
+### 2. Update Transaction States
+**Method:** `PATCH /batches/:id/transaction_states`
+**Purpose:** Move batch transactions between states
+**Supports:**
+- State 12700 (bank_processing)
+- State 12000 (successful - triggers webhooks)
+
+## Usage Example
+
+```ruby
+# Configure for prelive
+ZaiPayment.configure do |config|
+  config.environment = :prelive
+  config.client_id = 'your_client_id'
+  config.client_secret = 'your_client_secret'
+  config.scope = 'your_scope'
+end
+
+# Export transactions
+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
+ZaiPayment.batch_transactions.process_to_bank_processing(
+  batch_id,
+  exported_ids: transaction_ids
+)
+
+# Complete processing (triggers webhook)
+ZaiPayment.batch_transactions.process_to_successful(
+  batch_id,
+  exported_ids: transaction_ids
+)
+```
+
+## Error Handling
+
+### ConfigurationError
+Raised when attempting to use batch transaction endpoints outside prelive environment.
+
+### ValidationError
+Raised for:
+- Blank or nil batch_id
+- Empty or nil exported_ids array
+- exported_ids not an array
+- exported_ids containing nil or empty values
+- Invalid state codes (not 12700 or 12000)
+
+## Key Design Decisions
+
+1. **Prelive-Only Enforcement**: Environment check in every method to prevent accidental production use
+2. **Convenience Methods**: Separate methods for common operations (process_to_bank_processing, process_to_successful)
+3. **Array Support**: All methods support processing multiple transactions at once
+4. **State Code Constants**: Clear documentation of state codes (12700, 12000)
+5. **Comprehensive Validation**: All parameters validated with clear error messages
+6. **Consistent API**: Follows same patterns as other resources in the gem
+
+## Testing
+
+The implementation includes comprehensive RSpec tests covering:
+- ✅ Happy path for all methods
+- ✅ Error cases (invalid environment, invalid parameters)
+- ✅ Multiple transaction handling
+- ✅ Response structure validation
+- ✅ Integration with main module
+
+## Documentation
+
+Three levels of documentation provided:
+1. **YARD Comments**: Inline documentation in the code
+2. **Examples**: Practical usage examples (`examples/batch_transactions.md`)
+3. **Technical Guide**: Complete reference documentation (`docs/batch_transactions.md`)
+
+## Next Steps
+
+The implementation is complete and ready for use. To use it:
+
+1. Ensure your environment is set to `:prelive`
+2. Access via `ZaiPayment.batch_transactions`
+3. Follow the workflow: export → bank_processing → successful
+4. Handle webhooks triggered by the successful state
+
+## Files Summary
+
+**Created:**
+- `lib/zai_payment/resources/batch_transaction.rb` (172 lines)
+- `spec/zai_payment/resources/batch_transaction_spec.rb` (443 lines)
+- `examples/batch_transactions.md` (276 lines)
+- `docs/batch_transactions.md` (434 lines)
+
+**Modified:**
+- `lib/zai_payment.rb` (added 2 lines)
+- `lib/zai_payment/response.rb` (added "batches" key)
+- `readme.md` (added sections and examples)
+
+**Total:** 1,325+ lines of code, tests, and documentation added.
+
+## No Linter Errors
+
+All files pass linting checks with no errors or warnings.
+

data/RESPONSE_FORMAT_CORRECTION.md

@@ -0,0 +1,75 @@
+# Batch Transactions API Response Correction
+
+## Response Format for PATCH /batches/:id/transaction_states
+
+### ✅ Correct Response Format
+
+The actual API response for `PATCH /batches/:id/transaction_states` contains:
+
+```json
+{
+  "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
+  "msg": "1 jobs have been sent to the queue.",
+  "errors": []
+}
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `aggregated_jobs_uuid` | String | UUID identifying the batch of jobs sent to the queue |
+| `msg` | String | Success message indicating how many jobs were queued |
+| `errors` | Array | Array of any errors (typically empty on success) |
+
+### Ruby Usage Example
+
+```ruby
+response = ZaiPayment.batch_transactions.update_transaction_states(
+  'batch_id',
+  exported_ids: ['439970a2-e0a1-418e-aecf-6b519c115c55'],
+  state: 12700
+)
+
+# Access response data
+response.body['aggregated_jobs_uuid'] # => "c1cbc502-9754-42fd-9731-2330ddd7a41f"
+response.body['msg']                   # => "1 jobs have been sent to the queue."
+response.body['errors']                # => []
+
+# Check for success
+if response.success? && response.body['errors'].empty?
+  puts "Successfully queued #{response.body['msg']}"
+  puts "Job UUID: #{response.body['aggregated_jobs_uuid']}"
+end
+```
+
+### Multiple Transactions
+
+When processing multiple transactions, the message reflects the count:
+
+```ruby
+response = ZaiPayment.batch_transactions.update_transaction_states(
+  'batch_id',
+  exported_ids: ['id1', 'id2', 'id3'],
+  state: 12000
+)
+
+response.body['msg'] # => "3 jobs have been sent to the queue."
+```
+
+## Updated Files
+
+All documentation and specs have been updated to reflect the correct response format:
+
+1. ✅ `lib/zai_payment/resources/batch_transaction.rb` - YARD documentation
+2. ✅ `spec/zai_payment/resources/batch_transaction_spec.rb` - Test expectations
+3. ✅ `examples/batch_transactions.md` - Example code
+4. ✅ `docs/batch_transactions.md` - Technical documentation
+
+## Key Points
+
+- The response is **asynchronous** - jobs are queued for processing
+- The `aggregated_jobs_uuid` can be used to track the batch of jobs
+- Check the `errors` array to ensure no errors occurred
+- The `msg` field contains a human-readable description of what was queued
+

data/badges/coverage.json

@@ -1 +1 @@
-{"schemaVersion": 1, "label": "coverage", "message": "97.39%", "color": "brightgreen"}
+{"schemaVersion": 1, "label": "coverage", "message": "97.47%", "color": "brightgreen"}

data/changelog.md

@@ -1,5 +1,114 @@
 ## [Released]
 
+## [2.7.0] - 2025-11-04
+
+### Added
+- **Batch Transactions Resource**: Complete batch transaction management for testing in prelive environment 🔄
+  - `ZaiPayment.batch_transactions.export_transactions` - Export pending transactions to batched state
+  - `ZaiPayment.batch_transactions.process_to_bank_processing(batch_id, exported_ids:)` - Move batch to bank_processing state
+  - `ZaiPayment.batch_transactions.process_to_successful(batch_id, exported_ids:)` - Complete batch processing (triggers webhooks)
+  - `ZaiPayment.batch_transactions.show_batches` - List all batches
+  - `ZaiPayment.batch_transactions.show_batch(batch_id)` - Get specific batch details
+  - `ZaiPayment.batch_transactions.show_transactions(batch_id, limit:, offset:)` - List transactions in a batch with pagination
+  - Prelive-only endpoints for testing transaction processing workflows
+  - Full RSpec test suite with 20+ test examples
+  - Comprehensive documentation in `docs/batch_transactions.md`
+  - Practical examples in `examples/batch_transactions.md`
+
+- **Wallet Account Resource**: Complete wallet account management for Australian payments 💼
+  - `ZaiPayment.wallet_accounts.show(wallet_account_id)` - Get wallet account details including balance
+  - `ZaiPayment.wallet_accounts.show_user(wallet_account_id)` - Get user associated with wallet account
+  - `ZaiPayment.wallet_accounts.show_npp_details(wallet_account_id)` - Get NPP (New Payments Platform) details including PayID
+  - `ZaiPayment.wallet_accounts.show_bpay_details(wallet_account_id)` - Get BPay details including biller code and reference
+  - `ZaiPayment.wallet_accounts.pay_bill(wallet_account_id, account_id:, amount:, reference_id:)` - Pay bills via BPay from wallet
+  - Support for checking wallet balances before transactions
+  - Support for NPP payments with PayID
+  - Support for BPay bill payments
+  - Validation for payment amounts and reference IDs
+  - Full RSpec test suite with 35+ test examples across 5 describe blocks
+  - Comprehensive documentation in `docs/wallet_accounts.md`
+  - Practical examples in `examples/wallet_accounts.md`
+
+### Documentation
+- **Batch Transactions Guide** (`docs/batch_transactions.md`):
+  - Complete guide for all 6 batch transaction endpoints
+  - Detailed workflow for simulating batch processing
+  - State transition diagrams and examples
+  - Error handling patterns for batch operations
+  - Important notes about prelive-only usage
+  
+- **Batch Transactions Examples** (`examples/batch_transactions.md`):
+  - Export transactions examples (3 examples)
+  - Process to bank_processing examples (3 examples)
+  - Process to successful examples (3 examples)
+  - Show batches and transactions examples (6 examples)
+  - Complete workflow patterns
+  - Rails integration examples
+  - Webhook simulation workflows
+
+- **Wallet Accounts Guide** (`docs/wallet_accounts.md`):
+  - Complete guide for all 5 wallet account endpoints
+  - Balance checking and payment workflows
+  - NPP PayID integration examples
+  - BPay bill payment patterns
+  - Validation rules and error handling
+  - Four comprehensive use cases:
+    - Balance verification before payment
+    - Multiple bill payments workflow
+    - User verification for payments
+    - Disbursement status monitoring
+
+- **Wallet Accounts Examples** (`examples/wallet_accounts.md`):
+  - Show wallet account examples (3 examples)
+  - Show user examples (3 examples)
+  - NPP details examples
+  - BPay details examples
+  - Pay bill examples (3 examples)
+  - Three common patterns:
+    - Complete payment workflow
+    - Wallet payment service class
+    - Rails controller integration
+
+### Enhanced
+- **Response Class**: Added `disbursements` to `RESPONSE_DATA_KEYS` for automatic data extraction
+  - `response.data` now properly extracts disbursement objects from pay_bill responses
+  - Consistent with other resource response handling
+
+### Updated
+- **README.md**: 
+  - Added Wallet Accounts to features section
+  - Added Batch Transactions documentation links
+  - Updated roadmap to mark Payments as Done
+  - Added quick start examples for wallet account operations
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.6.1...v2.7.0
+
+## [2.6.1] - 2025-11-03
+
+### Changed
+- **Wallet Accounts Response Structure**: Updated to match actual API response format 🔄
+  - Response now properly returns nested `wallet_accounts` object with complete structure
+  - Added `wallet_accounts` to `Response#data` automatic extraction
+  - The `Response#data` method now automatically extracts the `wallet_accounts` object for cleaner API usage
+  - Updated response includes: `id`, `active`, `created_at`, `updated_at`, `balance`, `currency`
+  - Enhanced `links` structure with: `self`, `users`, `batch_transactions`, `transactions`, `bpay_details`, `npp_details`, `virtual_accounts`
+
+### Improved
+- **API Consistency**: `response.data` now works consistently across all resources
+  - Before: `response.data['wallet_accounts']['balance']` (manual extraction)
+  - After: `response.data['balance']` (automatic extraction)
+- **Documentation**: Updated all wallet_account documentation and examples
+  - Updated `docs/users.md` with complete wallet account response structure
+  - Added note about automatic data extraction in Response class
+  - Updated code examples in `lib/zai_payment/resources/user.rb`
+- **Test Coverage**: Enhanced wallet_account test suite
+  - Split tests into focused examples for better maintainability
+  - Added comprehensive validation for all wallet account fields
+  - Tests for active status, timestamps, and all link fields
+  - All tests comply with RuboCop standards
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.6.0...v2.6.1
+
 ## [2.6.0] - 2025-11-03
 
 ### Added