zai_payment 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 875d506340e0ebde15266915492626d10e454df4630a74fa17881cbc04b9e6fe
-  data.tar.gz: d0fae97dd2dc5d219f46af7ea61a04e0fcc74239b0860f3cfed251782c34086a
+  metadata.gz: 4711fe7ce837e63205c63cdacf15dd79ab6ac310c23cffd48dac60a3770fcb4f
+  data.tar.gz: 7de103d746c51bb8951f0c7d330ef8b05b6b69abcf15c8f170d275baa7bdb3e0
 SHA512:
-  metadata.gz: aa334f191958e38c6e87846daac9fd33391a3e34ae0ebcca24395c501aac4b283c44fb059d6f24b70c5bd1f91f9a241abe668f81e66facfc194dfd10f66065e4
-  data.tar.gz: c81b7ceb54b8947859c62a49c98efba981e6ee0a8550e7c4bb810c23bd66aad06eece483db51d9d6cc9e1c0f05afb0e37fb1bacdadbb222fbd8dc59887e907c3
+  metadata.gz: 63ee9160f09c7e1170cd601fbe2106c026b99077afb52692bd7f1089d061aae2b0a8d91ee2471c059b270c0fdd69b4799bc9c05e5807ec2cd3ca513b6bc069b6
+  data.tar.gz: 4344ee075e93a036ffaf4b525ec15d4bc38dc4d00f2a2391a0bc7020c684e7255ac5b2c1584ac87c84ade8c8868bef3a0f831851ff11063da0cc1c67b24f023f

data/badges/coverage.json

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

data/changelog.md

@@ -1,4 +1,51 @@
 ## [Released]
+## [2.2.0] - 2025-10-24
+### Added
+- **Extended User Management API**: 7 new user-related endpoints 🚀
+  - `ZaiPayment.users.wallet_account(user_id)` - Show user's wallet account details
+  - `ZaiPayment.users.items(user_id, limit:, offset:)` - List items associated with user (paginated)
+  - `ZaiPayment.users.set_disbursement_account(user_id, account_id)` - Set user's disbursement account
+  - `ZaiPayment.users.bank_account(user_id)` - Show user's active bank account
+  - `ZaiPayment.users.verify(user_id)` - Verify user (prelive environment only)
+  - `ZaiPayment.users.card_account(user_id)` - Show user's active card account
+  - `ZaiPayment.users.bpay_accounts(user_id)` - List user's BPay accounts
+- All endpoints include comprehensive nested data structures:
+  - Bank accounts with nested `bank` details (account_name, routing_number, account_type, holder_type)
+  - Card accounts with nested `card` details (type, full_name, masked number, expiry)
+  - BPay accounts with nested `bpay_details` (biller_code, biller_name, CRN, account_name)
+  - Items with full transaction details (buyer/seller info, payment_type, status, links to related resources)
+- Validation for all user_id and account_id parameters
+- Links to related resources included in all responses
+
+### Enhanced
+- **Response Class Refactoring**: Improved data extraction logic
+  - Replaced complex conditional chain with iterative approach using `RESPONSE_DATA_KEYS` constant
+  - Added support for new data keys: `bpay_accounts`, `bank_accounts`, `card_accounts`
+  - Reduced complexity metrics (ABC, Cyclomatic, Perceived Complexity)
+  - More maintainable and extensible architecture
+- **User Creation Validation**: Made `user_type` a required field
+  - Added validation to ensure `user_type` ('payin' or 'payout') is specified when creating users
+  - Improved error messages for missing required fields
+  - Enhanced test suite with compact, readable validation tests
+
+### Documentation
+- **Updated User Management Guide** (`docs/users.md`):
+  - Comprehensive examples for all 7 new endpoints
+  - Complete response structures with real API data
+  - Detailed field access patterns for nested objects
+  - Pagination examples for list endpoints
+  - Related resource link usage examples
+- **Updated README.md**:
+  - Added quick reference for all new endpoints
+  - Updated user management section with complete API surface
+- Real API response examples integrated for:
+  - List User Items (with buyer/seller details, transaction links)
+  - List User's BPay Accounts (with biller details, verification status)
+  - Show User Bank Account (with bank details, direct debit authorities)
+  - Show User Card Account (with card details, CVV verification status)
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.1.0...v2.2.0
+
 ## [2.1.0] - 2025-10-24
 ### Added
 - **Token Auth API**: Token generation for bank and card accounts 🔐

data/docs/users.md

@@ -65,6 +65,7 @@ Create a new payin user who will make payments on your platform.
 
 #### Required Fields for Payin Users
 
+- `user_type` - User type (must be 'payin')
 - `email` - User's email address
 - `first_name` - User's first name
 - `last_name` - User's last name
@@ -85,6 +86,7 @@ Create a new payin user who will make payments on your platform.
 
 ```ruby
 response = ZaiPayment.users.create(
+  user_type: 'payin',
   email: 'buyer@example.com',
   first_name: 'John',
   last_name: 'Doe',
@@ -108,6 +110,7 @@ Create a new payout user who will receive payments. Payout users must undergo ve
 
 #### Required Fields for Payout Users (Individuals)
 
+- `user_type` - User type (must be 'payout')
 - `email` - User's email address
 - `first_name` - User's first name
 - `last_name` - User's last name
@@ -122,6 +125,7 @@ Create a new payout user who will receive payments. Payout users must undergo ve
 
 ```ruby
 response = ZaiPayment.users.create(
+  user_type: 'payout',
   email: 'seller@example.com',
   first_name: 'Jane',
   last_name: 'Smith',
@@ -157,6 +161,297 @@ response = ZaiPayment.users.update(
 updated_user = response.data
 ```
 
+### Show User Wallet Account
+
+Show the user's wallet account using a given user ID.
+
+```ruby
+response = ZaiPayment.users.wallet_account('user_id')
+
+wallet = response.data
+puts wallet['id']
+puts wallet['balance']
+puts wallet['currency']
+```
+
+### List User Items
+
+Retrieve an ordered and paginated list of existing items the user is associated with.
+
+```ruby
+# List items with default pagination (limit: 10, offset: 0)
+response = ZaiPayment.users.items('user_id')
+
+# List items with custom pagination
+response = ZaiPayment.users.items('user_id', limit: 50, offset: 10)
+
+# Access the items
+response.data.each do |item|
+  puts "Item ID: #{item['id']}"
+  puts "Name: #{item['name']}"
+  puts "Description: #{item['description']}"
+  puts "Amount: #{item['amount']} #{item['currency']}"
+  puts "State: #{item['state']}"
+  puts "Status: #{item['status']}"
+  puts "Payment Type: #{item['payment_type_id']}"
+  
+  # Buyer information
+  puts "Buyer: #{item['buyer_name']} (#{item['buyer_country']})"
+  puts "Buyer Email: #{item['buyer_email']}"
+  
+  # Seller information
+  puts "Seller: #{item['seller_name']} (#{item['seller_country']})"
+  puts "Seller Email: #{item['seller_email']}"
+  
+  # Access related resource links
+  puts "Transactions URL: #{item['links']['transactions']}"
+  puts "Fees URL: #{item['links']['fees']}"
+end
+
+# Access pagination metadata
+puts "Total items: #{response.meta['total']}"
+puts "Limit: #{response.meta['limit']}"
+puts "Offset: #{response.meta['offset']}"
+```
+
+**Response Structure:**
+
+```ruby
+{
+  "items" => [
+    {
+      "id" => "7139651-1-2046",
+      "name" => "Item 7139651-1-2046",
+      "description" => "Test Item 7139651-1-2046",
+      "created_at" => "2020-05-05T12:26:50.782Z",
+      "updated_at" => "2020-05-05T12:31:03.654Z",
+      "state" => "payment_deposited",
+      "payment_type_id" => 2,
+      "status" => 22200,
+      "amount" => 109,
+      "deposit_reference" => "100014012501482",
+      "buyer_name" => "Buyer Last Name",
+      "buyer_country" => "AUS",
+      "buyer_email" => "assemblybuyer71391895@assemblypayments.com",
+      "seller_name" => "Assembly seller71391950",
+      "seller_country" => "AUS",
+      "seller_email" => "neol_seller71391950@assemblypayments.com",
+      "tds_check_state" => "NA",
+      "currency" => "AUD",
+      "links" => {
+        "self" => "/items/7139651-1-2046",
+        "buyers" => "/items/7139651-1-2046/buyers",
+        "sellers" => "/items/7139651-1-2046/sellers",
+        "status" => "/items/7139651-1-2046/status",
+        "fees" => "/items/7139651-1-2046/fees",
+        "transactions" => "/items/7139651-1-2046/transactions",
+        "batch_transactions" => "/items/7139651-1-2046/batch_transactions",
+        "wire_details" => "/items/7139651-1-2046/wire_details",
+        "bpay_details" => "/items/7139651-1-2046/bpay_details"
+      }
+    }
+  ],
+  "meta" => {
+    "limit" => 10,
+    "offset" => 0,
+    "total" => 1
+  }
+}
+```
+
+### Set User Disbursement Account
+
+Set the user's disbursement account using a given user ID and bank account ID.
+
+```ruby
+response = ZaiPayment.users.set_disbursement_account('user_id', 'bank_account_id')
+
+puts "Disbursement account set: #{response.data['disbursement_account_id']}"
+```
+
+### Show User Bank Account
+
+Show the user's active bank account using a given user ID.
+
+```ruby
+response = ZaiPayment.users.bank_account('user_id')
+
+# Access bank account details
+account = response.data
+puts "Account ID: #{account['id']}"
+puts "Active: #{account['active']}"
+puts "Verification Status: #{account['verification_status']}"
+puts "Currency: #{account['currency']}"
+
+# Access nested bank details
+bank = account['bank']
+puts "Bank Name: #{bank['bank_name']}"
+puts "Country: #{bank['country']}"
+puts "Account Name: #{bank['account_name']}"
+puts "Routing Number: #{bank['routing_number']}"
+puts "Account Number: #{bank['account_number']}"
+puts "Holder Type: #{bank['holder_type']}"
+puts "Account Type: #{bank['account_type']}"
+
+# Access related resource links
+puts "Self URL: #{account['links']['self']}"
+puts "Users URL: #{account['links']['users']}"
+```
+
+**Response Structure:**
+
+```ruby
+{
+  "bank_accounts" => {
+    "id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
+    "created_at" => "2016-04-12T09:20:38.540Z",
+    "updated_at" => "2016-04-12T09:20:38.540Z",
+    "active" => true,
+    "verification_status" => "not_verified",
+    "currency" => "AUD",
+    "bank" => {
+      "bank_name" => "Bank of Australia",
+      "country" => "AUS",
+      "account_name" => "Samuel Seller",
+      "routing_number" => "XXXXX3",
+      "account_number" => "XXX234",
+      "holder_type" => "personal",
+      "account_type" => "checking",
+      "direct_debit_authority_status" => nil
+    },
+    "links" => {
+      "self" => "/users/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/bank_accounts",
+      "users" => "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users",
+      "direct_debit_authorities" => "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/direct_debit_authorities"
+    }
+  }
+}
+```
+
+### Verify User (Prelive Only)
+
+Sets a user's verification state to approved on pre-live environment. This endpoint only works in the pre-live environment. The user verification workflow holds for all users in production.
+
+```ruby
+response = ZaiPayment.users.verify('user_id')
+
+puts "User verified: #{response.data['verification_state']}"
+```
+
+**Note:** This is only available in the pre-live/test environment and will not work in production.
+
+### Show User Card Account
+
+Show the user's active card account using a given user ID.
+
+```ruby
+response = ZaiPayment.users.card_account('user_id')
+
+# Access card account details
+account = response.data
+puts "Account ID: #{account['id']}"
+puts "Active: #{account['active']}"
+puts "Verification Status: #{account['verification_status']}"
+puts "CVV Verified: #{account['cvv_verified']}"
+puts "Currency: #{account['currency']}"
+
+# Access nested card details
+card = account['card']
+puts "Card Type: #{card['type']}"
+puts "Cardholder Name: #{card['full_name']}"
+puts "Card Number: #{card['number']}"
+puts "Expiry: #{card['expiry_month']}/#{card['expiry_year']}"
+
+# Access related resource links
+puts "Self URL: #{account['links']['self']}"
+puts "Users URL: #{account['links']['users']}"
+```
+
+**Response Structure:**
+
+```ruby
+{
+  "card_accounts" => {
+    "active" => true,
+    "created_at" => "2020-05-06T01:38:29.022Z",
+    "updated_at" => "2020-05-06T01:38:29.022Z",
+    "id" => "35977230-7168-0138-0a1d-0a58a9feac07",
+    "verification_status" => "not_verified",
+    "cvv_verified" => true,
+    "currency" => "AUD",
+    "card" => {
+      "type" => "visa",
+      "full_name" => "Neol Test",
+      "number" => "XXXX-XXXX-XXXX-1111",
+      "expiry_month" => "7",
+      "expiry_year" => "2021"
+    },
+    "links" => {
+      "self" => "/users/buyer-71439598/card_accounts",
+      "users" => "/card_accounts/35977230-7168-0138-0a1d-0a58a9feac07/users"
+    }
+  }
+}
+```
+
+### List User's BPay Accounts
+
+List the BPay accounts the user is associated with using a given user ID.
+
+```ruby
+response = ZaiPayment.users.bpay_accounts('user_id')
+
+# Access the BPay accounts
+response.data.each do |account|
+  puts "BPay Account ID: #{account['id']}"
+  puts "Active: #{account['active']}"
+  puts "Verification Status: #{account['verification_status']}"
+  
+  # Access BPay details
+  details = account['bpay_details']
+  puts "Biller Name: #{details['biller_name']}"
+  puts "Biller Code: #{details['biller_code']}"
+  puts "Account Name: #{details['account_name']}"
+  puts "CRN: #{details['crn']}"
+  puts "Currency: #{account['currency']}"
+end
+
+# Access pagination metadata
+puts "Total accounts: #{response.meta['total']}"
+```
+
+**Response Structure:**
+
+```ruby
+{
+  "bpay_accounts" => [
+    {
+      "id" => "b0980390-ac5b-0138-8b2e-0a58a9feac03",
+      "active" => true,
+      "created_at" => "2020-07-20 02:07:33.583000+00:00",
+      "updated_at" => "2020-07-20 02:07:33.583000+00:00",
+      "bpay_details" => {
+        "biller_name" => "APIBCD AV4",
+        "account_name" => "Test Biller",
+        "biller_code" => "93815",
+        "crn" => "613295205"
+      },
+      "currency" => "AUD",
+      "verification_status" => "verified",
+      "links" => {
+        "self" => "/bpay_accounts/b0980390-ac5b-0138-8b2e-0a58a9feac03",
+        "users" => "/bpay_accounts/b0980390-ac5b-0138-8b2e-0a58a9feac03/users"
+      }
+    }
+  ],
+  "meta" => {
+    "limit" => 10,
+    "offset" => 0,
+    "total" => 1
+  }
+}
+```
+
 ### Create Business User with Company
 
 Create a payout user representing a business entity with full company details. This is useful for merchants, marketplace sellers, or any business that needs to receive payments.
@@ -175,6 +470,7 @@ When the `company` parameter is provided, the following fields are required:
 ```ruby
 response = ZaiPayment.users.create(
   # Personal details (authorized signer)
+  user_type: 'payout',
   email: 'john.director@example.com',
   first_name: 'John',
   last_name: 'Smith',
@@ -214,6 +510,7 @@ puts "Company: #{user['company']['name']}"
 
 | Field | Type | Description | Payin Required | Payout Required |
 |-------|------|-------------|----------------|-----------------|
+| `user_type` | String | User type ('payin' or 'payout') | ✓ | ✓ |
 | `email` | String | User's email address | ✓ | ✓ |
 | `first_name` | String | User's first name | ✓ | ✓ |
 | `last_name` | String | User's last name | ✓ | ✓ |
@@ -237,7 +534,6 @@ puts "Company: #{user['company']['name']}"
 | `company` | Object | Company details (see below) | Optional | Optional |
 | `device_id` | String | Device ID for fraud prevention | When charging* | N/A |
 | `ip_address` | String | IP address for fraud prevention | When charging* | N/A |
-| `user_type` | String | 'payin' or 'payout' | Optional | Optional |
 
 \* Required when an item is created and a card is charged
 
@@ -339,6 +635,7 @@ response.meta     # => Pagination metadata (for list)
 ```ruby
 # Step 1: Create a payin user with minimal info
 response = ZaiPayment.users.create(
+  user_type: 'payin',
   email: 'buyer@example.com',
   first_name: 'John',
   last_name: 'Doe',
@@ -363,6 +660,7 @@ ZaiPayment.users.update(
 ```ruby
 response = ZaiPayment.users.create(
   # Required fields
+  user_type: 'payout',
   email: 'seller@example.com',
   first_name: 'Jane',
   last_name: 'Smith',
@@ -375,8 +673,7 @@ response = ZaiPayment.users.create(
   
   # Additional recommended fields
   mobile: '+61412345678',
-  government_number: 'TFN123456789',
-  user_type: 'payout'
+  government_number: 'TFN123456789'
 )
 
 user = response.data