zai_payment 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de2e744f1102ac7982d84422f7381d5c4928bd2afc1e2c2104946dbe57ebbb15
-  data.tar.gz: d00b49b1354c78899ead062c890fb4bfeab0057d82df45d88ff64a66916f6119
+  metadata.gz: 875d506340e0ebde15266915492626d10e454df4630a74fa17881cbc04b9e6fe
+  data.tar.gz: d0fae97dd2dc5d219f46af7ea61a04e0fcc74239b0860f3cfed251782c34086a
 SHA512:
-  metadata.gz: ba4b187933438167c31b91fbaa42372d285861e0cb5b806dddde7d9f1cb2b2986ee0477d341ffecff033a85c104abe3b13636afc4979f46855c20d8e6a1c6d9d
-  data.tar.gz: 2d12d31b7e02a9b24169bae9fddacb1b61bd3dec45e210bdea5ddaf6343533f8269184de881f77f25c3dab610f13e82c7bdfa157e506ad792d903e328c574427
+  metadata.gz: aa334f191958e38c6e87846daac9fd33391a3e34ae0ebcca24395c501aac4b283c44fb059d6f24b70c5bd1f91f9a241abe668f81e66facfc194dfd10f66065e4
+  data.tar.gz: c81b7ceb54b8947859c62a49c98efba981e6ee0a8550e7c4bb810c23bd66aad06eece483db51d9d6cc9e1c0f05afb0e37fb1bacdadbb222fbd8dc59887e907c3

data/badges/coverage.json

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

data/changelog.md

@@ -1,4 +1,32 @@
 ## [Released]
+## [2.1.0] - 2025-10-24
+### Added
+- **Token Auth API**: Token generation for bank and card accounts 🔐
+  - `ZaiPayment.token_auths.generate(user_id:, token_type:)` - Generate tokens for secure payment data collection
+  - Support for bank tokens (collecting bank account information)
+  - Support for card tokens (collecting credit card information)
+  - Token type validation (bank or card)
+  - User ID validation
+  - Full RSpec test suite for TokenAuth resource
+  - Comprehensive examples documentation in `examples/token_auths.md`
+
+### Documentation
+- Added detailed TokenAuth API examples with complete integration patterns
+- Frontend integration examples (PromisePay.js)
+- Rails controller integration examples
+- Service object pattern examples
+- Error handling and retry logic examples
+- Security best practices (token expiry management, audit logging, rate limiting)
+- Complete payment flow example
+
+### Testing
+- 20+ new test cases for TokenAuth resource
+- Validation error handling tested
+- Case-insensitive token type support tested
+- Default parameter behavior tested
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.0.2...v2.1.0
+
 ## [2.0.2] - 2025-10-24
 ### Fixed
 - **Items API**: Fixed endpoint configuration to use `core_base` instead of `va_base`

data/docs/readme.md

@@ -5,24 +5,30 @@ Welcome to the Zai Payment Ruby gem documentation. This guide will help you find
 ## 📖 Getting Started
 
 **New to the gem?** Start here:
-1. [Main README](../README.md) - Installation and basic configuration
-2. [Authentication Guide](AUTHENTICATION.md) - Get tokens with two approaches (short & long way)
-3. [Webhook Quick Start](WEBHOOK_SECURITY_QUICKSTART.md) - Set up secure webhooks in 5 minutes
+1. [Main README](../readme.md) - Installation and basic configuration
+2. [Authentication Guide](authentication.md) - Get tokens with two approaches (short & long way)
+3. [Webhook Quick Start](webhook_security_quickstart.md) - Set up secure webhooks in 5 minutes
 4. [Webhook Examples](../examples/webhooks.md) - Complete usage examples
 
 ## 🏗️ Architecture & Design
 
-- [**ARCHITECTURE.md**](ARCHITECTURE.md) - System architecture and design principles
-- [**AUTHENTICATION.md**](AUTHENTICATION.md) - OAuth2 implementation, token management, two approaches
-- [**WEBHOOKS.md**](WEBHOOKS.md) - Webhook implementation details, best practices, and patterns
+- [**architecture.md**](architecture.md) - System architecture and design principles
+- [**authentication.md**](authentication.md) - OAuth2 implementation, token management, two approaches
+- [**users.md**](users.md) - User management for payin (buyers) and payout (sellers/merchants)
+- [**items.md**](items.md) - Item management for transactions and payments
+- [**token_auths.md**](token_auths.md) - Token generation for secure bank and card data collection
+- [**webhooks.md**](webhooks.md) - Webhook implementation details, best practices, and patterns
 
 ## 🔐 Security Guides
 
-- [**WEBHOOK_SECURITY_QUICKSTART.md**](WEBHOOK_SECURITY_QUICKSTART.md) - Quick 5-minute security setup guide
-- [**WEBHOOK_SIGNATURE.md**](WEBHOOK_SIGNATURE.md) - Detailed signature verification implementation
+- [**webhook_security_quickstart.md**](webhook_security_quickstart.md) - Quick 5-minute security setup guide
+- [**webhook_signature.md**](webhook_signature.md) - Detailed signature verification implementation
 
 ## 📝 Examples
 
+- [**User Examples**](../examples/users.md) - User management examples and patterns
+- [**Item Examples**](../examples/items.md) - Transaction and payment workflows
+- [**Token Auth Examples**](../examples/token_auths.md) - Token generation and PromisePay.js integration
 - [**Webhook Examples**](../examples/webhooks.md) - Comprehensive webhook usage examples including:
   - Basic CRUD operations
   - Rails controller implementation
@@ -34,15 +40,30 @@ Welcome to the Zai Payment Ruby gem documentation. This guide will help you find
 ## 🔗 Quick Links
 
 ### Authentication
-- **Getting Started**: [Authentication Guide](AUTHENTICATION.md)
+- **Getting Started**: [Authentication Guide](authentication.md)
 - **Short Way**: `ZaiPayment.token` (one-liner)
 - **Long Way**: `TokenProvider.new(config: config).bearer_token` (full control)
 
+### Users
+- **Guide**: [User Management](users.md)
+- **Examples**: [User Examples](../examples/users.md)
+- **API Reference**: [Zai Users API](https://developer.hellozai.com/reference/getallusers)
+
+### Items
+- **Guide**: [Item Management](items.md)
+- **Examples**: [Item Examples](../examples/items.md)
+- **API Reference**: [Zai Items API](https://developer.hellozai.com/reference/listitems)
+
+### Token Auth
+- **Guide**: [Token Auth](token_auths.md)
+- **Examples**: [Token Auth Examples](../examples/token_auths.md)
+- **API Reference**: [Zai Generate Token API](https://developer.hellozai.com/reference/generatetoken)
+
 ### Webhooks
-- **Setup**: [Quick Start Guide](WEBHOOK_SECURITY_QUICKSTART.md)
+- **Setup**: [Quick Start Guide](webhook_security_quickstart.md)
 - **Examples**: [Complete Examples](../examples/webhooks.md)
-- **Details**: [Technical Documentation](WEBHOOKS.md)
-- **Security**: [Signature Verification](WEBHOOK_SIGNATURE.md)
+- **Details**: [Technical Documentation](webhooks.md)
+- **Security**: [Signature Verification](webhook_signature.md)
 
 ### External Resources
 - [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
 
 ```
 docs/
-├── README.md                        # This file - documentation index
-├── AUTHENTICATION.md                # OAuth2 authentication guide (NEW!)
-├── ARCHITECTURE.md                  # System architecture
-├── WEBHOOKS.md                      # Webhook technical docs
-├── WEBHOOK_SECURITY_QUICKSTART.md   # Quick security setup
-└── WEBHOOK_SIGNATURE.md             # Signature implementation
+├── readme.md                        # This file - documentation index
+├── authentication.md                # OAuth2 authentication guide
+├── users.md                         # User management guide
+├── items.md                         # Item management guide
+├── token_auths.md                   # Token generation guide (NEW!)
+├── architecture.md                  # System architecture
+├── webhooks.md                      # Webhook technical docs
+├── webhook_security_quickstart.md   # Quick security setup
+└── webhook_signature.md             # Signature implementation
 
 examples/
-└── webhooks.md                      # Complete webhook examples
+├── users.md                         # User management examples
+├── items.md                         # Item examples
+├── token_auths.md                   # Token auth examples (NEW!)
+└── webhooks.md                      # Webhook examples
 ```
 
 ## 💡 Tips
 
-- **Getting tokens?** Check [AUTHENTICATION.md](AUTHENTICATION.md) for both approaches
-- **Looking for code examples?** Check [examples/webhooks.md](../examples/webhooks.md)
-- **Need quick setup?** See [WEBHOOK_SECURITY_QUICKSTART.md](WEBHOOK_SECURITY_QUICKSTART.md)
-- **Want to understand the design?** Read [ARCHITECTURE.md](ARCHITECTURE.md)
-- **Security details?** Review [WEBHOOK_SIGNATURE.md](WEBHOOK_SIGNATURE.md)
+- **Getting tokens?** Check [authentication.md](authentication.md) for both approaches
+- **Managing users?** See [users.md](users.md) for payin and payout user guides
+- **Creating transactions?** Review [items.md](items.md) for item management
+- **Collecting payment data?** See [token_auths.md](token_auths.md) for secure token generation
+- **Looking for code examples?** Check the [examples](../examples/) directory
+- **Need quick setup?** See [webhook_security_quickstart.md](webhook_security_quickstart.md)
+- **Want to understand the design?** Read [architecture.md](architecture.md)
+- **Security details?** Review [webhook_signature.md](webhook_signature.md)
 
 ## 🆘 Need Help?
 
 1. Check the relevant documentation section above
-2. Review the [examples](../examples/webhooks.md)
+2. Review the [examples](../examples/)
 3. Consult the [Zai API documentation](https://developer.hellozai.com/)
 4. Open an issue on GitHub
 

data/docs/token_auths.md

@@ -0,0 +1,523 @@
+# Token Auth API
+
+## Overview
+
+The TokenAuth resource provides secure token generation for collecting bank account and credit card information. These tokens are used with the PromisePay.js library to securely transmit sensitive payment data without it ever touching your server.
+
+This is particularly useful for PCI compliance when collecting credit card information, and for securely collecting bank account details.
+
+## Table of Contents
+
+- [When to Use Token Auth](#when-to-use-token-auth)
+- [How It Works](#how-it-works)
+- [API Methods](#api-methods)
+- [Token Types](#token-types)
+- [Security Considerations](#security-considerations)
+- [Integration Guide](#integration-guide)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+
+## When to Use Token Auth
+
+You should use Token Auth when you need to:
+
+1. **Collect Credit Card Information** - Generate a card token for buyers to securely enter their credit card details
+2. **Collect Bank Account Details** - Generate a bank token for sellers to securely provide their bank account information
+3. **PCI Compliance** - Ensure sensitive payment data never touches your server
+4. **Frontend Integration** - Use with PromisePay.js to handle payment data collection on the client side
+
+## How It Works
+
+```
+1. Backend (Your Server)
+   ↓
+   Generate token using ZaiPayment.token_auths.generate()
+   ↓
+   Return token to frontend
+   
+2. Frontend (Browser/App)
+   ↓
+   Use PromisePay.js with the token
+   ↓
+   User enters payment details
+   ↓
+   PromisePay.js sends data directly to Zai (not your server)
+   ↓
+   Returns payment account ID
+   
+3. Backend (Your Server)
+   ↓
+   Use payment account ID to create items/transactions
+```
+
+## API Methods
+
+### `generate(user_id:, token_type:)`
+
+Generate a token for bank or card account data collection.
+
+**Parameters:**
+- `user_id` (String, required) - The ID of the buyer or seller user (already created)
+- `token_type` (String, optional) - Type of token to generate: `'bank'` or `'card'` (default: `'bank'`)
+
+**Returns:**
+- `Response` object containing the generated token and metadata
+
+**Example:**
+
+```ruby
+# Generate a bank token
+response = ZaiPayment.token_auths.generate(
+  user_id: "seller-68611249",
+  token_type: "bank"
+)
+
+token = response.data['token_auth']['token']
+# => "tok_bank_abc123xyz..."
+```
+
+## Token Types
+
+### Bank Tokens
+
+Bank tokens are used to collect bank account information from payout users (sellers/merchants).
+
+**Use Case:** Collecting bank account details for disbursements to sellers.
+
+**Typical Flow:**
+1. Create a payout user (seller)
+2. Generate a bank token for the seller
+3. Send token to frontend
+4. Use PromisePay.js to collect bank account details
+5. Receive bank account ID from Zai
+6. Associate bank account with items/transactions
+
+**Example:**
+
+```ruby
+# Step 1: Create seller
+seller = ZaiPayment.users.create(
+  user_type: "payout",
+  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"
+)
+
+seller_id = seller.data['users']['id']
+
+# Step 2: Generate bank token
+token_response = ZaiPayment.token_auths.generate(
+  user_id: seller_id,
+  token_type: "bank"
+)
+
+bank_token = token_response.data['token_auth']['token']
+
+# Step 3: Send to frontend for PromisePay.js integration
+```
+
+### Card Tokens
+
+Card tokens are used to collect credit card information from payin users (buyers).
+
+**Use Case:** Collecting credit card details for payments from buyers.
+
+**Typical Flow:**
+1. Create a payin user (buyer)
+2. Generate a card token for the buyer
+3. Send token to frontend
+4. Use PromisePay.js to collect credit card details
+5. Receive card account ID from Zai
+6. Use card account to process payments
+
+**Example:**
+
+```ruby
+# Step 1: Create buyer
+buyer = ZaiPayment.users.create(
+  user_type: "payin",
+  email: "buyer@example.com",
+  first_name: "John",
+  last_name: "Doe",
+  country: "USA"
+)
+
+buyer_id = buyer.data['users']['id']
+
+# Step 2: Generate card token
+token_response = ZaiPayment.token_auths.generate(
+  user_id: buyer_id,
+  token_type: "card"
+)
+
+card_token = token_response.data['token_auth']['token']
+
+# Step 3: Send to frontend for PromisePay.js integration
+```
+
+## Security Considerations
+
+### Token Expiration
+
+Tokens have a limited lifespan (typically 1 hour). Always:
+- Check the `expires_at` field in the response
+- Generate fresh tokens for each payment session
+- Don't store tokens for later use
+- Handle token expiration gracefully on the frontend
+
+### Token Scope
+
+Each token is:
+- **User-specific**: Tied to a single user ID
+- **Single-use**: Should be used once per payment session
+- **Type-specific**: Bank tokens only for bank accounts, card tokens only for cards
+
+### PCI Compliance
+
+Token Auth helps maintain PCI compliance by:
+- Preventing card data from touching your server
+- Using secure HTTPS transmission
+- Leveraging Zai's PCI-compliant infrastructure
+- Minimizing your PCI scope
+
+## Integration Guide
+
+### Backend Integration
+
+```ruby
+# app/controllers/payment_tokens_controller.rb
+class PaymentTokensController < ApplicationController
+  before_action :authenticate_user!
+  
+  def create
+    user_id = current_user.zai_user_id
+    token_type = params[:token_type] || 'card'
+    
+    response = ZaiPayment.token_auths.generate(
+      user_id: user_id,
+      token_type: token_type
+    )
+    
+    render json: {
+      token: response.data['token_auth']['token'],
+      expires_at: response.data['token_auth']['expires_at']
+    }
+  rescue ZaiPayment::Errors::ApiError => e
+    render json: { error: e.message }, status: :bad_gateway
+  end
+end
+```
+
+### Frontend Integration (JavaScript)
+
+```html
+<!-- Include PromisePay.js -->
+<script src="https://cdn.assemblypay.com/promisepay.js"></script>
+
+<script>
+  // 1. Fetch token from your backend
+  async function getPaymentToken(tokenType) {
+    const response = await fetch('/api/payment_tokens', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token_type: tokenType })
+    });
+    
+    const data = await response.json();
+    return data.token;
+  }
+  
+  // 2. Use token with PromisePay.js to collect card details
+  async function collectCardDetails() {
+    const token = await getPaymentToken('card');
+    
+    PromisePay.setToken(token);
+    
+    PromisePay.createCardAccount({
+      card_number: document.getElementById('card_number').value,
+      expiry_month: document.getElementById('expiry_month').value,
+      expiry_year: document.getElementById('expiry_year').value,
+      cvv: document.getElementById('cvv').value
+    }, function(response) {
+      if (response.error) {
+        console.error('Error:', response.error);
+      } else {
+        // Card account created successfully
+        const cardAccountId = response.card_accounts.id;
+        // Send cardAccountId to your backend to create item/transaction
+        processPayment(cardAccountId);
+      }
+    });
+  }
+  
+  // 3. Use token with PromisePay.js to collect bank details
+  async function collectBankDetails() {
+    const token = await getPaymentToken('bank');
+    
+    PromisePay.setToken(token);
+    
+    PromisePay.createBankAccount({
+      account_name: document.getElementById('account_name').value,
+      account_number: document.getElementById('account_number').value,
+      routing_number: document.getElementById('routing_number').value,
+      account_type: 'savings' // or 'checking'
+    }, function(response) {
+      if (response.error) {
+        console.error('Error:', response.error);
+      } else {
+        // Bank account created successfully
+        const bankAccountId = response.bank_accounts.id;
+        // Send bankAccountId to your backend
+        saveBankAccount(bankAccountId);
+      }
+    });
+  }
+</script>
+```
+
+### Complete Payment Flow
+
+```ruby
+# 1. Create users (buyer and seller)
+buyer = ZaiPayment.users.create(
+  user_type: "payin",
+  email: "buyer@example.com",
+  first_name: "John",
+  last_name: "Doe",
+  country: "USA"
+)
+
+seller = ZaiPayment.users.create(
+  user_type: "payout",
+  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"
+)
+
+# 2. Generate card token for buyer
+card_token_response = ZaiPayment.token_auths.generate(
+  user_id: buyer.data['users']['id'],
+  token_type: "card"
+)
+
+# Send card_token to frontend, collect card details, get card_account_id
+
+# 3. Generate bank token for seller
+bank_token_response = ZaiPayment.token_auths.generate(
+  user_id: seller.data['users']['id'],
+  token_type: "bank"
+)
+
+# Send bank_token to frontend, collect bank details, get bank_account_id
+
+# 4. Create item for payment
+item = ZaiPayment.items.create(
+  name: "Product Purchase",
+  amount: 10000, # $100.00
+  payment_type: 2, # Credit card
+  buyer_id: buyer.data['users']['id'],
+  seller_id: seller.data['users']['id']
+)
+
+# 5. Process payment using card_account_id
+# (Use Items Actions API or Payment API - to be implemented)
+```
+
+## Error Handling
+
+### Common Errors
+
+```ruby
+begin
+  response = ZaiPayment.token_auths.generate(
+    user_id: user_id,
+    token_type: token_type
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  # Invalid user_id or token_type
+  { error: "Validation error: #{e.message}", retryable: false }
+rescue ZaiPayment::Errors::NotFoundError => e
+  # User not found
+  { error: "User not found: #{user_id}", retryable: false }
+rescue ZaiPayment::Errors::UnauthorizedError => e
+  # Authentication failed
+  { error: "Authentication failed", retryable: false }
+rescue ZaiPayment::Errors::RateLimitError => e
+  # Rate limit exceeded
+  { error: "Rate limit exceeded", retryable: true, retry_after: 60 }
+rescue ZaiPayment::Errors::ServerError => e
+  # Server error (5xx)
+  { error: "Server error", retryable: true }
+rescue ZaiPayment::Errors::TimeoutError => e
+  # Request timeout
+  { error: "Timeout", retryable: true }
+end
+```
+
+### Validation Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `user_id is required and cannot be blank` | Missing or empty user_id | Provide a valid user ID |
+| `token_type must be one of: bank, card` | Invalid token_type | Use 'bank' or 'card' |
+| `User not found` | User doesn't exist | Create user first |
+
+## Best Practices
+
+### 1. Token Lifecycle Management
+
+```ruby
+class TokenManager
+  def initialize(user_id)
+    @user_id = user_id
+    @cache = {}
+  end
+  
+  def get_token(type)
+    cache_key = "#{@user_id}_#{type}"
+    
+    # Don't reuse expired tokens
+    if @cache[cache_key] && !token_expired?(@cache[cache_key][:expires_at])
+      return @cache[cache_key][:token]
+    end
+    
+    # Generate fresh token
+    response = ZaiPayment.token_auths.generate(
+      user_id: @user_id,
+      token_type: type
+    )
+    
+    token_data = response.data['token_auth']
+    
+    @cache[cache_key] = {
+      token: token_data['token'],
+      expires_at: Time.parse(token_data['expires_at'])
+    }
+    
+    token_data['token']
+  end
+  
+  private
+  
+  def token_expired?(expires_at)
+    # Consider expired 5 minutes before actual expiry
+    expires_at < Time.now + 300
+  end
+end
+```
+
+### 2. Audit Logging
+
+```ruby
+def generate_token_with_audit(user_id:, token_type:, context: {})
+  start_time = Time.now
+  
+  begin
+    response = ZaiPayment.token_auths.generate(
+      user_id: user_id,
+      token_type: token_type
+    )
+    
+    log_event(
+      event: 'token_generated',
+      user_id: user_id,
+      token_type: token_type,
+      success: true,
+      duration: Time.now - start_time,
+      context: context
+    )
+    
+    response
+  rescue => e
+    log_event(
+      event: 'token_generation_failed',
+      user_id: user_id,
+      token_type: token_type,
+      success: false,
+      error: e.message,
+      duration: Time.now - start_time,
+      context: context
+    )
+    
+    raise
+  end
+end
+```
+
+### 3. Rate Limiting
+
+```ruby
+class RateLimitedTokenGenerator
+  def initialize(user_id)
+    @user_id = user_id
+    @redis = Redis.new
+  end
+  
+  def generate(token_type:, limit: 10, window: 3600)
+    rate_limit_key = "token_gen:#{@user_id}:#{Time.now.to_i / window}"
+    current_count = @redis.incr(rate_limit_key)
+    @redis.expire(rate_limit_key, window)
+    
+    if current_count > limit
+      raise "Rate limit exceeded: #{limit} tokens per #{window} seconds"
+    end
+    
+    ZaiPayment.token_auths.generate(
+      user_id: @user_id,
+      token_type: token_type
+    )
+  end
+end
+```
+
+### 4. Retry Logic
+
+```ruby
+def generate_token_with_retry(user_id, token_type, max_retries: 3)
+  retries = 0
+  
+  begin
+    ZaiPayment.token_auths.generate(
+      user_id: user_id,
+      token_type: token_type
+    )
+  rescue ZaiPayment::Errors::RateLimitError, 
+         ZaiPayment::Errors::ServerError,
+         ZaiPayment::Errors::TimeoutError => e
+    retries += 1
+    
+    if retries < max_retries
+      sleep_time = 2 ** retries # Exponential backoff
+      sleep(sleep_time)
+      retry
+    else
+      raise
+    end
+  end
+end
+```
+
+## API Reference
+
+For complete API documentation, see:
+- [Zai: Generate Token API Reference](https://developer.hellozai.com/reference/generatetoken)
+- [Token Auth Examples](../examples/token_auths.md)
+
+## Related Resources
+
+- [User Management](users.md) - Create users before generating tokens
+- [Item Management](items.md) - Use payment accounts to create items
+- [PromisePay.js Documentation](https://developer.hellozai.com/docs/promisepay-js)
+