zai_payment 2.0.2 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. checksums.yaml +4 -4
  2. data/badges/coverage.json +1 -1
  3. data/changelog.md +75 -0
  4. data/docs/readme.md +55 -25
  5. data/docs/token_auths.md +523 -0
  6. data/docs/user_id_field.md +1 -1
  7. data/docs/users.md +303 -6
  8. data/examples/rails_card_payment.md +716 -0
  9. data/examples/token_auths.md +687 -0
  10. data/lib/zai_payment/resources/token_auth.rb +75 -0
  11. data/lib/zai_payment/resources/user.rb +131 -3
  12. data/lib/zai_payment/response.rb +10 -4
  13. data/lib/zai_payment/version.rb +1 -1
  14. data/lib/zai_payment.rb +6 -0
  15. data/readme.md +55 -0
  16. data/token_auth_implementation_summary.md +249 -0
  17. metadata +7 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: de2e744f1102ac7982d84422f7381d5c4928bd2afc1e2c2104946dbe57ebbb15
4
- data.tar.gz: d00b49b1354c78899ead062c890fb4bfeab0057d82df45d88ff64a66916f6119
3
+ metadata.gz: 4711fe7ce837e63205c63cdacf15dd79ab6ac310c23cffd48dac60a3770fcb4f
4
+ data.tar.gz: 7de103d746c51bb8951f0c7d330ef8b05b6b69abcf15c8f170d275baa7bdb3e0
5
5
  SHA512:
6
- metadata.gz: ba4b187933438167c31b91fbaa42372d285861e0cb5b806dddde7d9f1cb2b2986ee0477d341ffecff033a85c104abe3b13636afc4979f46855c20d8e6a1c6d9d
7
- data.tar.gz: 2d12d31b7e02a9b24169bae9fddacb1b61bd3dec45e210bdea5ddaf6343533f8269184de881f77f25c3dab610f13e82c7bdfa157e506ad792d903e328c574427
6
+ metadata.gz: 63ee9160f09c7e1170cd601fbe2106c026b99077afb52692bd7f1089d061aae2b0a8d91ee2471c059b270c0fdd69b4799bc9c05e5807ec2cd3ca513b6bc069b6
7
+ data.tar.gz: 4344ee075e93a036ffaf4b525ec15d4bc38dc4d00f2a2391a0bc7020c684e7255ac5b2c1584ac87c84ade8c8868bef3a0f831851ff11063da0cc1c67b24f023f
data/badges/coverage.json CHANGED
@@ -1 +1 @@
1
- {"schemaVersion": 1, "label": "coverage", "message": "95.19%", "color": "brightgreen"}
1
+ {"schemaVersion": 1, "label": "coverage", "message": "96.15%", "color": "brightgreen"}
data/changelog.md CHANGED
@@ -1,4 +1,79 @@
1
1
  ## [Released]
2
+ ## [2.2.0] - 2025-10-24
3
+ ### Added
4
+ - **Extended User Management API**: 7 new user-related endpoints 🚀
5
+ - `ZaiPayment.users.wallet_account(user_id)` - Show user's wallet account details
6
+ - `ZaiPayment.users.items(user_id, limit:, offset:)` - List items associated with user (paginated)
7
+ - `ZaiPayment.users.set_disbursement_account(user_id, account_id)` - Set user's disbursement account
8
+ - `ZaiPayment.users.bank_account(user_id)` - Show user's active bank account
9
+ - `ZaiPayment.users.verify(user_id)` - Verify user (prelive environment only)
10
+ - `ZaiPayment.users.card_account(user_id)` - Show user's active card account
11
+ - `ZaiPayment.users.bpay_accounts(user_id)` - List user's BPay accounts
12
+ - All endpoints include comprehensive nested data structures:
13
+ - Bank accounts with nested `bank` details (account_name, routing_number, account_type, holder_type)
14
+ - Card accounts with nested `card` details (type, full_name, masked number, expiry)
15
+ - BPay accounts with nested `bpay_details` (biller_code, biller_name, CRN, account_name)
16
+ - Items with full transaction details (buyer/seller info, payment_type, status, links to related resources)
17
+ - Validation for all user_id and account_id parameters
18
+ - Links to related resources included in all responses
19
+
20
+ ### Enhanced
21
+ - **Response Class Refactoring**: Improved data extraction logic
22
+ - Replaced complex conditional chain with iterative approach using `RESPONSE_DATA_KEYS` constant
23
+ - Added support for new data keys: `bpay_accounts`, `bank_accounts`, `card_accounts`
24
+ - Reduced complexity metrics (ABC, Cyclomatic, Perceived Complexity)
25
+ - More maintainable and extensible architecture
26
+ - **User Creation Validation**: Made `user_type` a required field
27
+ - Added validation to ensure `user_type` ('payin' or 'payout') is specified when creating users
28
+ - Improved error messages for missing required fields
29
+ - Enhanced test suite with compact, readable validation tests
30
+
31
+ ### Documentation
32
+ - **Updated User Management Guide** (`docs/users.md`):
33
+ - Comprehensive examples for all 7 new endpoints
34
+ - Complete response structures with real API data
35
+ - Detailed field access patterns for nested objects
36
+ - Pagination examples for list endpoints
37
+ - Related resource link usage examples
38
+ - **Updated README.md**:
39
+ - Added quick reference for all new endpoints
40
+ - Updated user management section with complete API surface
41
+ - Real API response examples integrated for:
42
+ - List User Items (with buyer/seller details, transaction links)
43
+ - List User's BPay Accounts (with biller details, verification status)
44
+ - Show User Bank Account (with bank details, direct debit authorities)
45
+ - Show User Card Account (with card details, CVV verification status)
46
+
47
+ **Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.1.0...v2.2.0
48
+
49
+ ## [2.1.0] - 2025-10-24
50
+ ### Added
51
+ - **Token Auth API**: Token generation for bank and card accounts 🔐
52
+ - `ZaiPayment.token_auths.generate(user_id:, token_type:)` - Generate tokens for secure payment data collection
53
+ - Support for bank tokens (collecting bank account information)
54
+ - Support for card tokens (collecting credit card information)
55
+ - Token type validation (bank or card)
56
+ - User ID validation
57
+ - Full RSpec test suite for TokenAuth resource
58
+ - Comprehensive examples documentation in `examples/token_auths.md`
59
+
60
+ ### Documentation
61
+ - Added detailed TokenAuth API examples with complete integration patterns
62
+ - Frontend integration examples (PromisePay.js)
63
+ - Rails controller integration examples
64
+ - Service object pattern examples
65
+ - Error handling and retry logic examples
66
+ - Security best practices (token expiry management, audit logging, rate limiting)
67
+ - Complete payment flow example
68
+
69
+ ### Testing
70
+ - 20+ new test cases for TokenAuth resource
71
+ - Validation error handling tested
72
+ - Case-insensitive token type support tested
73
+ - Default parameter behavior tested
74
+
75
+ **Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.0.2...v2.1.0
76
+
2
77
  ## [2.0.2] - 2025-10-24
3
78
  ### Fixed
4
79
  - **Items API**: Fixed endpoint configuration to use `core_base` instead of `va_base`
data/docs/readme.md CHANGED
@@ -5,24 +5,30 @@ Welcome to the Zai Payment Ruby gem documentation. This guide will help you find
5
5
  ## 📖 Getting Started
6
6
 
7
7
  **New to the gem?** Start here:
8
- 1. [Main README](../README.md) - Installation and basic configuration
9
- 2. [Authentication Guide](AUTHENTICATION.md) - Get tokens with two approaches (short & long way)
10
- 3. [Webhook Quick Start](WEBHOOK_SECURITY_QUICKSTART.md) - Set up secure webhooks in 5 minutes
8
+ 1. [Main README](../readme.md) - Installation and basic configuration
9
+ 2. [Authentication Guide](authentication.md) - Get tokens with two approaches (short & long way)
10
+ 3. [Webhook Quick Start](webhook_security_quickstart.md) - Set up secure webhooks in 5 minutes
11
11
  4. [Webhook Examples](../examples/webhooks.md) - Complete usage examples
12
12
 
13
13
  ## 🏗️ Architecture & Design
14
14
 
15
- - [**ARCHITECTURE.md**](ARCHITECTURE.md) - System architecture and design principles
16
- - [**AUTHENTICATION.md**](AUTHENTICATION.md) - OAuth2 implementation, token management, two approaches
17
- - [**WEBHOOKS.md**](WEBHOOKS.md) - Webhook implementation details, best practices, and patterns
15
+ - [**architecture.md**](architecture.md) - System architecture and design principles
16
+ - [**authentication.md**](authentication.md) - OAuth2 implementation, token management, two approaches
17
+ - [**users.md**](users.md) - User management for payin (buyers) and payout (sellers/merchants)
18
+ - [**items.md**](items.md) - Item management for transactions and payments
19
+ - [**token_auths.md**](token_auths.md) - Token generation for secure bank and card data collection
20
+ - [**webhooks.md**](webhooks.md) - Webhook implementation details, best practices, and patterns
18
21
 
19
22
  ## 🔐 Security Guides
20
23
 
21
- - [**WEBHOOK_SECURITY_QUICKSTART.md**](WEBHOOK_SECURITY_QUICKSTART.md) - Quick 5-minute security setup guide
22
- - [**WEBHOOK_SIGNATURE.md**](WEBHOOK_SIGNATURE.md) - Detailed signature verification implementation
24
+ - [**webhook_security_quickstart.md**](webhook_security_quickstart.md) - Quick 5-minute security setup guide
25
+ - [**webhook_signature.md**](webhook_signature.md) - Detailed signature verification implementation
23
26
 
24
27
  ## 📝 Examples
25
28
 
29
+ - [**User Examples**](../examples/users.md) - User management examples and patterns
30
+ - [**Item Examples**](../examples/items.md) - Transaction and payment workflows
31
+ - [**Token Auth Examples**](../examples/token_auths.md) - Token generation and PromisePay.js integration
26
32
  - [**Webhook Examples**](../examples/webhooks.md) - Comprehensive webhook usage examples including:
27
33
  - Basic CRUD operations
28
34
  - Rails controller implementation
@@ -34,15 +40,30 @@ Welcome to the Zai Payment Ruby gem documentation. This guide will help you find
34
40
  ## 🔗 Quick Links
35
41
 
36
42
  ### Authentication
37
- - **Getting Started**: [Authentication Guide](AUTHENTICATION.md)
43
+ - **Getting Started**: [Authentication Guide](authentication.md)
38
44
  - **Short Way**: `ZaiPayment.token` (one-liner)
39
45
  - **Long Way**: `TokenProvider.new(config: config).bearer_token` (full control)
40
46
 
47
+ ### Users
48
+ - **Guide**: [User Management](users.md)
49
+ - **Examples**: [User Examples](../examples/users.md)
50
+ - **API Reference**: [Zai Users API](https://developer.hellozai.com/reference/getallusers)
51
+
52
+ ### Items
53
+ - **Guide**: [Item Management](items.md)
54
+ - **Examples**: [Item Examples](../examples/items.md)
55
+ - **API Reference**: [Zai Items API](https://developer.hellozai.com/reference/listitems)
56
+
57
+ ### Token Auth
58
+ - **Guide**: [Token Auth](token_auths.md)
59
+ - **Examples**: [Token Auth Examples](../examples/token_auths.md)
60
+ - **API Reference**: [Zai Generate Token API](https://developer.hellozai.com/reference/generatetoken)
61
+
41
62
  ### Webhooks
42
- - **Setup**: [Quick Start Guide](WEBHOOK_SECURITY_QUICKSTART.md)
63
+ - **Setup**: [Quick Start Guide](webhook_security_quickstart.md)
43
64
  - **Examples**: [Complete Examples](../examples/webhooks.md)
44
- - **Details**: [Technical Documentation](WEBHOOKS.md)
45
- - **Security**: [Signature Verification](WEBHOOK_SIGNATURE.md)
65
+ - **Details**: [Technical Documentation](webhooks.md)
66
+ - **Security**: [Signature Verification](webhook_signature.md)
46
67
 
47
68
  ### External Resources
48
69
  - [Zai Developer Portal](https://developer.hellozai.com/)
@@ -53,29 +74,38 @@ Welcome to the Zai Payment Ruby gem documentation. This guide will help you find
53
74
 
54
75
  ```
55
76
  docs/
56
- ├── README.md # This file - documentation index
57
- ├── AUTHENTICATION.md # OAuth2 authentication guide (NEW!)
58
- ├── ARCHITECTURE.md # System architecture
59
- ├── WEBHOOKS.md # Webhook technical docs
60
- ├── WEBHOOK_SECURITY_QUICKSTART.md # Quick security setup
61
- └── WEBHOOK_SIGNATURE.md # Signature implementation
77
+ ├── readme.md # This file - documentation index
78
+ ├── authentication.md # OAuth2 authentication guide
79
+ ├── users.md # User management guide
80
+ ├── items.md # Item management guide
81
+ ├── token_auths.md # Token generation guide (NEW!)
82
+ ├── architecture.md # System architecture
83
+ ├── webhooks.md # Webhook technical docs
84
+ ├── webhook_security_quickstart.md # Quick security setup
85
+ └── webhook_signature.md # Signature implementation
62
86
 
63
87
  examples/
64
- └── webhooks.md # Complete webhook examples
88
+ ├── users.md # User management examples
89
+ ├── items.md # Item examples
90
+ ├── token_auths.md # Token auth examples (NEW!)
91
+ └── webhooks.md # Webhook examples
65
92
  ```
66
93
 
67
94
  ## 💡 Tips
68
95
 
69
- - **Getting tokens?** Check [AUTHENTICATION.md](AUTHENTICATION.md) for both approaches
70
- - **Looking for code examples?** Check [examples/webhooks.md](../examples/webhooks.md)
71
- - **Need quick setup?** See [WEBHOOK_SECURITY_QUICKSTART.md](WEBHOOK_SECURITY_QUICKSTART.md)
72
- - **Want to understand the design?** Read [ARCHITECTURE.md](ARCHITECTURE.md)
73
- - **Security details?** Review [WEBHOOK_SIGNATURE.md](WEBHOOK_SIGNATURE.md)
96
+ - **Getting tokens?** Check [authentication.md](authentication.md) for both approaches
97
+ - **Managing users?** See [users.md](users.md) for payin and payout user guides
98
+ - **Creating transactions?** Review [items.md](items.md) for item management
99
+ - **Collecting payment data?** See [token_auths.md](token_auths.md) for secure token generation
100
+ - **Looking for code examples?** Check the [examples](../examples/) directory
101
+ - **Need quick setup?** See [webhook_security_quickstart.md](webhook_security_quickstart.md)
102
+ - **Want to understand the design?** Read [architecture.md](architecture.md)
103
+ - **Security details?** Review [webhook_signature.md](webhook_signature.md)
74
104
 
75
105
  ## 🆘 Need Help?
76
106
 
77
107
  1. Check the relevant documentation section above
78
- 2. Review the [examples](../examples/webhooks.md)
108
+ 2. Review the [examples](../examples/)
79
109
  3. Consult the [Zai API documentation](https://developer.hellozai.com/)
80
110
  4. Open an issue on GitHub
81
111