zai_payment 2.9.0 → 2.9.1

data/examples/rails_card_payment.md

@@ -1,1252 +0,0 @@
-# Rails Card Payment Example
-
-This guide demonstrates how to implement a complete card payment workflow in a Rails application using the `zai_payment` gem.
-
-## Table of Contents
-
-1. [Setup](#setup)
-2. [Configuration](#configuration)
-3. [User Management](#user-management)
-4. [Card Account Setup](#card-account-setup)
-5. [Creating an Item](#creating-an-item)
-6. [Making a Payment](#making-a-payment)
-7. [Webhook Handling](#webhook-handling)
-8. [Complete Flow Example](#complete-flow-example)
-9. [Reference](#reference)
-
-## Setup
-
-Add the gem to your Gemfile:
-
-```ruby
-gem 'zai_payment'
-```
-
-Then run:
-
-```bash
-bundle install
-```
-
-## Configuration
-
-Configure the gem in an initializer (`config/initializers/zai_payment.rb`):
-
-```ruby
-ZaiPayment.configure do |config|
-  config.environment = Rails.env.production? ? 'production' : 'prelive'
-  config.client_id = ENV.fetch("ZAI_CLIENT_ID")
-  config.client_secret = ENV.fetch("ZAI_CLIENT_SECRET")
-  config.scope = ENV.fetch("ZAI_OAUTH_SCOPE")
-end
-```
-
-## User Management
-
-### Creating Users
-
-```ruby
-# In your controller or service object
-class PaymentService
-  def initialize
-    @client = ZaiPayment::Client.new
-  end
-
-  # Create a buyer
-  def create_buyer(email:, first_name:, last_name:, mobile:)
-    response = @client.users.create(
-      id: "buyer_#{SecureRandom.hex(8)}", # Your internal user ID
-      first_name: first_name,
-      last_name: last_name,
-      email: email,
-      mobile: mobile,
-      country: 'AUS'
-    )
-    
-    # Store zai_user_id in your database
-    response.data['id']
-  end
-
-  # Create a seller
-  def create_seller(email:, first_name:, last_name:, mobile:)
-    response = @client.users.create(
-      id: "seller_#{SecureRandom.hex(8)}",
-      first_name: first_name,
-      last_name: last_name,
-      email: email,
-      mobile: mobile,
-      country: 'AUS'
-    )
-    
-    response.data['id']
-  end
-end
-```
-
-### Example Controller
-
-```ruby
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  def create_zai_user
-    service = PaymentService.new
-    
-    zai_user_id = service.create_buyer(
-      email: current_user.email,
-      first_name: current_user.first_name,
-      last_name: current_user.last_name,
-      mobile: current_user.phone
-    )
-    
-    # Update your user record
-    current_user.update(zai_user_id: zai_user_id)
-    
-    redirect_to dashboard_path, notice: 'User created successfully'
-  rescue ZaiPayment::Errors::ApiError => e
-    redirect_to dashboard_path, alert: "Error: #{e.message}"
-  end
-end
-```
-
-## Card Account Setup
-
-### Generating a Card Auth Token
-
-```ruby
-# app/controllers/card_accounts_controller.rb
-class CardAccountsController < ApplicationController
-  def new
-    # Generate a card auth token for the hosted form
-    client = ZaiPayment::Client.new
-    
-    response = client.token_auths.create(
-      token_type: 'card',
-      user_id: current_user.zai_user_id
-    )
-    
-    @card_token = response.data['token']
-  end
-end
-```
-
-### View with Hosted Form
-
-
-```erb
-<!-- app/views/card_accounts/new.html.erb -->
-<div class="card-form-container">
-  <h2>Add Your Card</h2>
-  
-  <div id="card-container"></div>
-  
-  <script src="https://hosted.assemblypay.com/assembly.js"></script>
-  <script>
-    let dropinHandler = DropIn.create({
-      cardTokenAuth: '<%= @card_token %>',
-      environment: '<%= Rails.env.production? ? 'production' : 'prelive' %>',
-      targetElementId: '#card-container',
-      cardAccountCreationCallback: function(cardAccountResult) {
-        // Send the card account ID to your server
-        fetch('/card_accounts', {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'X-CSRF-Token': document.querySelector('[name="csrf-token"]').content
-          },
-          body: JSON.stringify({
-            card_account_id: cardAccountResult.id
-          })
-        })
-        .then(response => response.json())
-        .then(data => {
-          alert("Card saved successfully!");
-          window.location.href = '/payments/new';
-        })
-        .catch(error => {
-          alert("Error saving card: " + error);
-        });
-      }
-    }, function (error, instance) {
-      if(error) {
-        alert("Error: " + error);
-      }
-    });
-  </script>
-</div>
-```
-
-> **Note:** For more details on the Hosted Form integration, including PCI compliance, supported browsers, and error handling, see the [Zai Hosted Form Documentation](https://developer.hellozai.com/docs/integrating-drop-in-ui-for-capturing-a-credit-card).
-
-### Storing Card Account ID
-
-```ruby
-# app/controllers/card_accounts_controller.rb
-class CardAccountsController < ApplicationController
-  def create
-    # Store the card account ID returned from the hosted form
-    current_user.update(
-      zai_card_account_id: params[:card_account_id]
-    )
-    
-    render json: { success: true }
-  end
-  
-  # List user's card accounts
-  def index
-    client = ZaiPayment::Client.new
-    
-    response = client.card_accounts.list(
-      user_id: current_user.zai_user_id
-    )
-    
-    @card_accounts = response.data['card_accounts']
-  end
-end
-```
-
-## Creating an Item
-
-```ruby
-# app/controllers/items_controller.rb
-class ItemsController < ApplicationController
-  def create
-    client = ZaiPayment::Client.new
-    
-    # Assuming you have a transaction/order model
-    transaction = current_user.transactions.create!(
-      amount: params[:amount],
-      seller_id: params[:seller_id],
-      description: params[:description]
-    )
-    
-    # Create item in Zai
-    response = client.items.create(
-      id: "order_#{transaction.id}", # Your internal order ID
-      name: params[:description],
-      amount: (params[:amount].to_f * 100).to_i, # Convert to cents
-      payment_type: 1, # 1 = Payin
-      buyer_id: current_user.zai_user_id,
-      seller_id: User.find(params[:seller_id]).zai_user_id,
-      fee_ids: '', # Optional: platform fees
-      description: params[:description]
-    )
-    
-    zai_item_id = response.data['id']
-    transaction.update(zai_item_id: zai_item_id)
-    
-    redirect_to payment_path(transaction), notice: 'Ready to make payment'
-  rescue ZaiPayment::Errors::ApiError => e
-    redirect_to new_item_path, alert: "Error: #{e.message}"
-  end
-end
-```
-
-## Making a Payment
-
-Once you have an item created and the buyer has a card account, you can process the payment.
-
-### Basic Payment
-
-```ruby
-# app/controllers/payments_controller.rb
-class PaymentsController < ApplicationController
-  def create
-    transaction = current_user.transactions.find(params[:transaction_id])
-    client = ZaiPayment::Client.new
-    
-    # Make payment using card account
-    response = client.items.make_payment(
-      transaction.zai_item_id,
-      account_id: params[:card_account_id]  # Required
-    )
-    
-    if response.success?
-      transaction.update(
-        status: 'processing',
-        payment_state: response.data['payment_state']
-      )
-      
-      redirect_to transaction_path(transaction), 
-                  notice: 'Payment initiated successfully!'
-    else
-      redirect_to payment_path(transaction), 
-                  alert: "Payment failed: #{response.error_message}"
-    end
-  rescue ZaiPayment::Errors::ValidationError => e
-    # Handles missing account_id or other validation errors
-    redirect_to payment_path(transaction), alert: "Validation error: #{e.message}"
-  rescue ZaiPayment::Errors::ApiError => e
-    redirect_to payment_path(transaction), alert: "Error: #{e.message}"
-  end
-end
-```
-
-### Payment with Fraud Protection
-
-Include device information and IP address for enhanced fraud protection:
-
-```ruby
-def create
-  transaction = current_user.transactions.find(params[:transaction_id])
-  client = ZaiPayment::Client.new
-  
-  response = client.items.make_payment(
-    transaction.zai_item_id,
-    account_id: params[:card_account_id],  # Required
-    device_id: session[:device_id],        # Track device
-    ip_address: request.remote_ip,         # Client IP address
-    merchant_phone: current_user.phone     # Merchant contact
-  )
-  
-  if response.success?
-    transaction.update(
-      status: 'processing',
-      payment_state: response.data['payment_state'],
-      zai_state: response.data['state']
-    )
-    
-    # Log the payment for tracking
-    Rails.logger.info "Payment initiated: Item #{transaction.zai_item_id}, IP: #{request.remote_ip}"
-    
-    flash[:notice] = 'Payment is being processed. You will receive confirmation shortly.'
-    redirect_to transaction_path(transaction)
-  else
-    handle_payment_error(transaction, response)
-  end
-rescue ZaiPayment::Errors::ApiError => e
-  handle_payment_exception(transaction, e)
-end
-
-private
-
-def handle_payment_error(transaction, response)
-  case response.status
-  when 422
-    # Validation error - likely card declined or insufficient funds
-    flash[:alert] = "Payment declined: #{response.error_message}"
-  when 404
-    flash[:alert] = "Item or card account not found. Please try again."
-  else
-    flash[:alert] = "Payment error: #{response.error_message}"
-  end
-  
-  transaction.update(status: 'failed', error_message: response.error_message)
-  redirect_to payment_path(transaction)
-end
-
-def handle_payment_exception(transaction, error)
-  Rails.logger.error "Payment exception: #{error.class} - #{error.message}"
-  
-  transaction.update(status: 'error', error_message: error.message)
-  redirect_to payment_path(transaction), alert: "An error occurred: #{error.message}"
-end
-```
-
-### Payment with CVV Verification
-
-For additional security, collect and pass CVV:
-
-```ruby
-def create
-  transaction = current_user.transactions.find(params[:transaction_id])
-  client = ZaiPayment::Client.new
-  
-  response = client.items.make_payment(
-    transaction.zai_item_id,
-    account_id: params[:card_account_id],  # Required
-    cvv: params[:cvv],                     # From secure form input
-    ip_address: request.remote_ip
-  )
-  
-  if response.success?
-    transaction.update(status: 'processing')
-    redirect_to transaction_path(transaction), 
-                notice: 'Payment processed with CVV verification.'
-  else
-    redirect_to payment_path(transaction), 
-                alert: "CVV verification failed: #{response.error_message}"
-  end
-end
-```
-
-### Complete Payment Service
-
-A comprehensive service object for handling payments:
-
-```ruby
-# app/services/payment_processor.rb
-class PaymentProcessor
-  attr_reader :transaction, :errors
-  
-  def initialize(transaction)
-    @transaction = transaction
-    @client = ZaiPayment::Client.new
-    @errors = []
-  end
-  
-  def process(card_account_id:, ip_address:, device_id: nil, cvv: nil)
-    validate_payment_readiness
-    return false if @errors.any?
-    
-    make_payment(card_account_id, ip_address, device_id, cvv)
-  end
-  
-  private
-  
-  def validate_payment_readiness
-    @errors << "Transaction already processed" if transaction.paid?
-    @errors << "Item ID missing" unless transaction.zai_item_id.present?
-    @errors << "Buyer missing" unless transaction.buyer.zai_user_id.present?
-  end
-  
-  def make_payment(card_account_id, ip_address, device_id, cvv)
-    payment_params = {
-      account_id: card_account_id,  # Required
-      ip_address: ip_address
-    }
-    payment_params[:device_id] = device_id if device_id.present?
-    payment_params[:cvv] = cvv if cvv.present?
-    
-    response = @client.items.make_payment(
-      transaction.zai_item_id,
-      **payment_params
-    )
-    
-    if response.success?
-      update_transaction_success(response)
-      notify_success
-      true
-    else
-      update_transaction_failure(response)
-      @errors << response.error_message
-      false
-    end
-  rescue ZaiPayment::Errors::ApiError => e
-    handle_api_error(e)
-    false
-  end
-  
-  def update_transaction_success(response)
-    transaction.update!(
-      status: 'processing',
-      payment_state: response.data['payment_state'],
-      zai_state: response.data['state'],
-      paid_at: Time.current
-    )
-  end
-  
-  def update_transaction_failure(response)
-    transaction.update!(
-      status: 'failed',
-      error_message: response.error_message,
-      failed_at: Time.current
-    )
-  end
-  
-  def handle_api_error(error)
-    transaction.update!(
-      status: 'error',
-      error_message: error.message
-    )
-    @errors << error.message
-    
-    # Log for monitoring
-    Rails.logger.error "Payment API Error: #{error.class} - #{error.message}"
-    
-    # Send to error tracking (e.g., Sentry)
-    Sentry.capture_exception(error) if defined?(Sentry)
-  end
-  
-  def notify_success
-    # Send success notification
-    PaymentMailer.payment_initiated(transaction).deliver_later
-  end
-end
-
-# Usage in controller:
-def create
-  transaction = current_user.transactions.find(params[:transaction_id])
-  processor = PaymentProcessor.new(transaction)
-  
-  if processor.process(
-    card_account_id: params[:card_account_id],
-    ip_address: request.remote_ip,
-    device_id: session[:device_id],
-    cvv: params[:cvv]
-  )
-    redirect_to transaction_path(transaction), notice: 'Payment processing!'
-  else
-    flash[:alert] = processor.errors.join(', ')
-    redirect_to payment_path(transaction)
-  end
-end
-```
-
-### Payment Controller (Complete)
-
-```ruby
-# app/controllers/payments_controller.rb
-class PaymentsController < ApplicationController
-  before_action :authenticate_user!
-  before_action :set_transaction, only: [:show, :create]
-  
-  def show
-    @card_accounts = fetch_card_accounts
-    
-    unless @card_accounts.any?
-      redirect_to new_card_account_path, 
-                  alert: 'Please add a payment method first.'
-    end
-  end
-  
-  def create
-    processor = PaymentProcessor.new(@transaction)
-    
-    if processor.process(
-      card_account_id: params[:card_account_id],
-      ip_address: request.remote_ip,
-      device_id: session[:device_id],
-      cvv: params[:cvv]
-    )
-      flash[:success] = 'Payment initiated! Check your email for confirmation.'
-      redirect_to transaction_path(@transaction)
-    else
-      flash.now[:alert] = processor.errors.join(', ')
-      @card_accounts = fetch_card_accounts
-      render :show
-    end
-  end
-  
-  private
-  
-  def set_transaction
-    @transaction = current_user.transactions.find(params[:id] || params[:transaction_id])
-  rescue ActiveRecord::RecordNotFound
-    redirect_to transactions_path, alert: 'Transaction not found.'
-  end
-  
-  def fetch_card_accounts
-    client = ZaiPayment::Client.new
-    response = client.card_accounts.list(user_id: current_user.zai_user_id)
-    
-    if response.success?
-      response.data['card_accounts'] || []
-    else
-      []
-    end
-  rescue ZaiPayment::Errors::ApiError => e
-    Rails.logger.error "Failed to fetch card accounts: #{e.message}"
-    []
-  end
-end
-```
-
-### Payment View
-
-```erb
-<!-- app/views/payments/show.html.erb -->
-<div class="payment-page">
-  <h2>Complete Payment</h2>
-  
-  <div class="transaction-details">
-    <p><strong>Amount:</strong> <%= number_to_currency(@transaction.amount) %></p>
-    <p><strong>Description:</strong> <%= @transaction.description %></p>
-    <p><strong>Seller:</strong> <%= @transaction.seller.name %></p>
-  </div>
-  
-  <%= form_with url: payments_path, method: :post do |f| %>
-    <%= f.hidden_field :transaction_id, value: @transaction.id %>
-    
-    <div class="form-group">
-      <%= f.label :card_account_id, "Select Card" %>
-      <%= f.select :card_account_id, 
-          options_for_select(@card_accounts.map { |ca| 
-            ["#{ca['card']['type']} ending in #{ca['card']['number']}", ca['id']] 
-          }), 
-          { include_blank: 'Choose a card' },
-          class: 'form-control' %>
-    </div>
-    
-    <div class="actions">
-      <%= f.submit "Pay #{number_to_currency(@transaction.amount)}", 
-          class: 'btn btn-primary' %>
-      <%= link_to 'Add New Card', new_card_account_path, 
-          class: 'btn btn-secondary' %>
-    </div>
-  <% end %>
-</div>
-```
-
-## Webhook Handling
-
-### Setting Up Webhooks
-
-```ruby
-# One-time setup (can be done in Rails console or a rake task)
-# lib/tasks/zai_setup.rake
-
-namespace :zai do
-  desc "Setup Zai webhooks"
-  task setup_webhooks: :environment do
-    client = ZaiPayment::Client.new
-    
-    # Item status changes
-    client.webhooks.create(
-      object_type: 'items',
-      url: "#{ENV['APP_URL']}/webhooks/zai/items"
-    )
-    
-    # Transaction events
-    client.webhooks.create(
-      object_type: 'transactions',
-      url: "#{ENV['APP_URL']}/webhooks/zai/transactions"
-    )
-    
-    # Batch transaction events (settlement)
-    client.webhooks.create(
-      object_type: 'batch_transactions',
-      url: "#{ENV['APP_URL']}/webhooks/zai/batch_transactions"
-    )
-    
-    puts "Webhooks configured successfully!"
-  end
-end
-```
-
-### Webhook Controller
-
-```ruby
-# app/controllers/webhooks/zai_controller.rb
-module Webhooks
-  class ZaiController < ApplicationController
-    skip_before_action :verify_authenticity_token
-    before_action :verify_webhook_signature
-    
-    # Handle item status changes
-    def items
-      payload = JSON.parse(request.body.read)
-      
-      # Item completed
-      if payload['status'] == 'completed'
-        item_id = payload['id']
-        transaction = Transaction.find_by(zai_item_id: item_id)
-        
-        if transaction
-          transaction.update(
-            status: 'completed',
-            released_amount: payload['released_amount']
-          )
-          
-          # Notify user
-          PaymentMailer.payment_completed(transaction).deliver_later
-        end
-      end
-      
-      head :ok
-    end
-    
-    # Handle transaction events (card authorized)
-    def transactions
-      payload = JSON.parse(request.body.read)
-      
-      if payload['type'] == 'payment' && payload['type_method'] == 'credit_card'
-        transaction = Transaction.find_by(zai_transaction_id: payload['id'])
-        
-        if transaction
-          if payload['status'] == 'successful'
-            transaction.update(status: 'authorized')
-            # Notify user
-            PaymentMailer.payment_authorized(transaction).deliver_later
-          elsif payload['status'] == 'failed'
-            transaction.update(status: 'failed', failure_reason: payload['failure_reason'])
-            PaymentMailer.payment_failed(transaction).deliver_later
-          end
-        end
-      end
-      
-      head :ok
-    end
-    
-    # Handle batch transactions (funds settled)
-    def batch_transactions
-      payload = JSON.parse(request.body.read)
-      
-      if payload['type'] == 'payment_funding' && 
-         payload['type_method'] == 'credit_card' &&
-         payload['status'] == 'successful'
-        
-        # Find related item and mark as settled
-        batch_id = payload['id']
-        transaction = Transaction.find_by(zai_batch_transaction_id: batch_id)
-        
-        if transaction
-          transaction.update(status: 'settled')
-          # Funds are now in seller's wallet
-          PaymentMailer.payment_settled(transaction).deliver_later
-        end
-      end
-      
-      head :ok
-    end
-    
-    private
-    
-    def verify_webhook_signature
-      # Verify the webhook signature using the gem's helper
-      signature = request.headers['X-Webhook-Signature']
-      
-      unless ZaiPayment::Webhook.verify_signature?(
-        payload: request.body.read,
-        signature: signature,
-        secret: ENV['ZAI_WEBHOOK_SECRET']
-      )
-        head :unauthorized
-      end
-    end
-  end
-end
-```
-
-### Routes for Webhooks
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  namespace :webhooks do
-    post 'zai/items', to: 'zai#items'
-    post 'zai/transactions', to: 'zai#transactions'
-    post 'zai/batch_transactions', to: 'zai#batch_transactions'
-  end
-end
-```
-
-## Complete Flow Example
-
-### Service Object for Complete Payment Flow
-
-```ruby
-# app/services/card_payment_flow.rb
-class CardPaymentFlow
-  attr_reader :client, :errors
-  
-  def initialize
-    @client = ZaiPayment::Client.new
-    @errors = []
-  end
-  
-  # Complete flow from creating users to payment
-  def execute(buyer_params:, seller_params:, payment_params:)
-    ActiveRecord::Base.transaction do
-      # Step 1: Create or get buyer
-      buyer_id = ensure_zai_user(buyer_params)
-      return false unless buyer_id
-      
-      # Step 2: Create or get seller
-      seller_id = ensure_zai_user(seller_params)
-      return false unless seller_id
-      
-      # Step 3: Create item
-      item_id = create_item(
-        buyer_id: buyer_id,
-        seller_id: seller_id,
-        amount: payment_params[:amount],
-        description: payment_params[:description]
-      )
-      return false unless item_id
-      
-      # Step 4: Make payment
-      make_payment(
-        item_id: item_id,
-        card_account_id: payment_params[:card_account_id]
-      )
-    end
-  rescue ZaiPayment::Errors::ApiError => e
-    @errors << e.message
-    false
-  end
-  
-  private
-  
-  def ensure_zai_user(user_params)
-    # Check if user already exists in Zai
-    return user_params[:zai_user_id] if user_params[:zai_user_id].present?
-    
-    # Create new user
-    response = @client.users.create(
-      id: user_params[:id],
-      first_name: user_params[:first_name],
-      last_name: user_params[:last_name],
-      email: user_params[:email],
-      mobile: user_params[:mobile],
-      country: 'AUS'
-    )
-    
-    response.data['id']
-  end
-  
-  def create_item(buyer_id:, seller_id:, amount:, description:)
-    response = @client.items.create(
-      id: "item_#{SecureRandom.hex(8)}",
-      name: description,
-      amount: (amount.to_f * 100).to_i,
-      payment_type: 1,
-      buyer_id: buyer_id,
-      seller_id: seller_id,
-      description: description
-    )
-    
-    response.data['id']
-  end
-  
-  def make_payment(item_id:, card_account_id:)
-    response = @client.items.make_payment(
-      item_id,
-      account_id: card_account_id  # Required
-    )
-    
-    response.success?
-  end
-end
-```
-
-### Usage Example
-
-```ruby
-# In a controller or background job
-class ProcessPaymentJob < ApplicationJob
-  queue_as :default
-  
-  def perform(transaction_id)
-    transaction = Transaction.find(transaction_id)
-    flow = CardPaymentFlow.new
-    
-    success = flow.execute(
-      buyer_params: {
-        id: "buyer_#{transaction.buyer.id}",
-        zai_user_id: transaction.buyer.zai_user_id,
-        first_name: transaction.buyer.first_name,
-        last_name: transaction.buyer.last_name,
-        email: transaction.buyer.email,
-        mobile: transaction.buyer.phone
-      },
-      seller_params: {
-        id: "seller_#{transaction.seller.id}",
-        zai_user_id: transaction.seller.zai_user_id,
-        first_name: transaction.seller.first_name,
-        last_name: transaction.seller.last_name,
-        email: transaction.seller.email,
-        mobile: transaction.seller.phone
-      },
-      payment_params: {
-        amount: transaction.amount,
-        description: transaction.description,
-        card_account_id: transaction.buyer.zai_card_account_id
-      }
-    )
-    
-    if success
-      transaction.update(status: 'processing')
-      PaymentMailer.payment_initiated(transaction).deliver_now
-    else
-      transaction.update(status: 'failed', error_message: flow.errors.join(', '))
-      PaymentMailer.payment_failed(transaction).deliver_now
-    end
-  end
-end
-```
-
-## Authorize Payment
-
-Authorize a payment without immediately capturing funds. This is useful for scenarios like hotel bookings or rental deposits where you want to verify the card and hold funds before completing the transaction.
-
-### Basic Authorization
-
-```ruby
-# app/controllers/authorizations_controller.rb
-class AuthorizationsController < ApplicationController
-  def create
-    transaction = current_user.transactions.find(params[:transaction_id])
-    client = ZaiPayment::Client.new
-    
-    # Authorize payment (hold funds without capturing)
-    response = client.items.authorize_payment(
-      transaction.zai_item_id,
-      account_id: params[:card_account_id]  # Required
-    )
-    
-    if response.success?
-      transaction.update(
-        status: 'authorized',
-        payment_state: response.data['payment_state']
-      )
-      
-      redirect_to transaction_path(transaction), 
-                  notice: 'Payment authorized successfully! Funds are on hold.'
-    else
-      redirect_to payment_path(transaction), 
-                  alert: "Authorization failed: #{response.error_message}"
-    end
-  rescue ZaiPayment::Errors::ValidationError => e
-    redirect_to payment_path(transaction), alert: "Validation error: #{e.message}"
-  rescue ZaiPayment::Errors::ApiError => e
-    redirect_to payment_path(transaction), alert: "Error: #{e.message}"
-  end
-end
-```
-
-### Authorization with CVV
-
-For additional security, include CVV verification:
-
-```ruby
-def create
-  transaction = current_user.transactions.find(params[:transaction_id])
-  client = ZaiPayment::Client.new
-  
-  response = client.items.authorize_payment(
-    transaction.zai_item_id,
-    account_id: params[:card_account_id],  # Required
-    cvv: params[:cvv],                     # From secure form input
-    merchant_phone: current_user.phone
-  )
-  
-  if response.success?
-    transaction.update(
-      status: 'authorized',
-      payment_state: response.data['payment_state'],
-      zai_state: response.data['state']
-    )
-    
-    # Log the authorization
-    Rails.logger.info "Payment authorized: Item #{transaction.zai_item_id}"
-    
-    flash[:notice] = 'Payment authorized. Funds are on hold for 7 days.'
-    redirect_to transaction_path(transaction)
-  else
-    handle_authorization_error(transaction, response)
-  end
-rescue ZaiPayment::Errors::ApiError => e
-  handle_authorization_exception(transaction, e)
-end
-
-private
-
-def handle_authorization_error(transaction, response)
-  case response.status
-  when 422
-    flash[:alert] = "Authorization declined: #{response.error_message}"
-  when 404
-    flash[:alert] = "Item or card account not found. Please try again."
-  else
-    flash[:alert] = "Authorization error: #{response.error_message}"
-  end
-  
-  transaction.update(status: 'authorization_failed', error_message: response.error_message)
-  redirect_to payment_path(transaction)
-end
-
-def handle_authorization_exception(transaction, error)
-  Rails.logger.error "Authorization exception: #{error.class} - #{error.message}"
-  
-  transaction.update(status: 'error', error_message: error.message)
-  redirect_to payment_path(transaction), alert: "An error occurred: #{error.message}"
-end
-```
-
-### Complete Authorization Service
-
-A comprehensive service object for handling payment authorizations:
-
-```ruby
-# app/services/payment_authorizer.rb
-class PaymentAuthorizer
-  attr_reader :transaction, :errors
-  
-  def initialize(transaction)
-    @transaction = transaction
-    @client = ZaiPayment::Client.new
-    @errors = []
-  end
-  
-  def authorize(card_account_id:, cvv: nil, merchant_phone: nil)
-    validate_authorization_readiness
-    return false if @errors.any?
-    
-    perform_authorization(card_account_id, cvv, merchant_phone)
-  end
-  
-  private
-  
-  def validate_authorization_readiness
-    @errors << "Transaction already authorized" if transaction.authorized?
-    @errors << "Item ID missing" unless transaction.zai_item_id.present?
-    @errors << "Buyer missing" unless transaction.buyer.zai_user_id.present?
-  end
-  
-  def perform_authorization(card_account_id, cvv, merchant_phone)
-    auth_params = {
-      account_id: card_account_id  # Required
-    }
-    auth_params[:cvv] = cvv if cvv.present?
-    auth_params[:merchant_phone] = merchant_phone if merchant_phone.present?
-    
-    response = @client.items.authorize_payment(
-      transaction.zai_item_id,
-      **auth_params
-    )
-    
-    if response.success?
-      update_transaction_success(response)
-      notify_success
-      true
-    else
-      update_transaction_failure(response)
-      @errors << response.error_message
-      false
-    end
-  rescue ZaiPayment::Errors::ApiError => e
-    handle_api_error(e)
-    false
-  end
-  
-  def update_transaction_success(response)
-    transaction.update!(
-      status: 'authorized',
-      payment_state: response.data['payment_state'],
-      zai_state: response.data['state'],
-      authorized_at: Time.current,
-      authorization_expires_at: 7.days.from_now  # Typical hold period
-    )
-  end
-  
-  def update_transaction_failure(response)
-    transaction.update!(
-      status: 'authorization_failed',
-      error_message: response.error_message,
-      failed_at: Time.current
-    )
-  end
-  
-  def handle_api_error(error)
-    transaction.update!(
-      status: 'error',
-      error_message: error.message
-    )
-    @errors << error.message
-    
-    Rails.logger.error "Authorization API Error: #{error.class} - #{error.message}"
-    Sentry.capture_exception(error) if defined?(Sentry)
-  end
-  
-  def notify_success
-    PaymentMailer.payment_authorized(transaction).deliver_later
-  end
-end
-
-# Usage in controller:
-def create
-  transaction = current_user.transactions.find(params[:transaction_id])
-  authorizer = PaymentAuthorizer.new(transaction)
-  
-  if authorizer.authorize(
-    card_account_id: params[:card_account_id],
-    cvv: params[:cvv],
-    merchant_phone: current_user.phone
-  )
-    redirect_to transaction_path(transaction), 
-                notice: 'Payment authorized! Funds are on hold.'
-  else
-    flash[:alert] = authorizer.errors.join(', ')
-    redirect_to payment_path(transaction)
-  end
-end
-```
-
-### Authorization Flow States
-
-After calling `authorize_payment`, track these states:
-
-| State | Description | Next Action |
-|-------|-------------|-------------|
-| `authorized` | Payment authorized, funds on hold | Capture or cancel |
-| `payment_held` | Authorized but held for review | Wait for review |
-| `authorization_failed` | Authorization failed | Retry or cancel |
-
-### Capturing an Authorized Payment
-
-After authorization, you can capture the payment:
-
-```ruby
-# When ready to complete the transaction (e.g., after service delivery)
-def capture_payment
-  transaction = Transaction.find(params[:id])
-  
-  # Check if authorization is still valid
-  if transaction.authorized? && transaction.authorization_expires_at > Time.current
-    # Use make_payment to capture or complete the item
-    client = ZaiPayment::Client.new
-    response = client.items.make_payment(
-      transaction.zai_item_id,
-      account_id: transaction.card_account_id
-    )
-    
-    if response.success?
-      transaction.update(
-        status: 'captured',
-        captured_at: Time.current
-      )
-      flash[:notice] = 'Payment captured successfully!'
-    else
-      flash[:alert] = "Capture failed: #{response.error_message}"
-    end
-  else
-    flash[:alert] = 'Authorization expired or invalid'
-  end
-  
-  redirect_to transaction_path(transaction)
-end
-```
-
-### Canceling an Authorization
-
-To release held funds:
-
-```ruby
-def cancel_authorization
-  transaction = Transaction.find(params[:id])
-  
-  if transaction.authorized?
-    client = ZaiPayment::Client.new
-    response = client.items.cancel(transaction.zai_item_id)
-    
-    if response.success?
-      transaction.update(
-        status: 'authorization_cancelled',
-        cancelled_at: Time.current
-      )
-      flash[:notice] = 'Authorization cancelled. Funds released.'
-    else
-      flash[:alert] = "Cancellation failed: #{response.error_message}"
-    end
-  end
-  
-  redirect_to transaction_path(transaction)
-end
-```
-
-## Pre-live Testing
-
-For testing in the pre-live environment:
-
-```ruby
-# After making a payment, simulate settlement
-class SimulateSettlement
-  def self.call(transaction_id)
-    transaction = Transaction.find(transaction_id)
-    client = ZaiPayment::Client.new
-    
-    # Step 1: Export batch transactions
-    response = client.batch_transactions.export
-    batch_transactions = response.data['batch_transactions']
-    
-    # Find the relevant batch transaction
-    batch_tx = batch_transactions.find do |bt|
-      bt['related_items']&.include?(transaction.zai_item_id)
-    end
-    
-    return unless batch_tx
-    
-    # Step 2: Move to batched state (12700)
-    client.batches.update_transaction_state(
-      id: batch_tx['batch_id'],
-      exported_ids: [batch_tx['id']],
-      state: 12700
-    )
-    
-    # Step 3: Move to successful state (12000)
-    client.batches.update_transaction_state(
-      id: batch_tx['batch_id'],
-      exported_ids: [batch_tx['id']],
-      state: 12000
-    )
-    
-    puts "Settlement simulated for transaction #{transaction_id}"
-  end
-end
-```
-
-## Error Handling
-
-```ruby
-# app/services/payment_error_handler.rb
-class PaymentErrorHandler
-  RETRY_ERRORS = [
-    ZaiPayment::Errors::TimeoutError,
-    ZaiPayment::Errors::ConnectionError,
-    ZaiPayment::Errors::ServerError
-  ]
-  
-  PERMANENT_ERRORS = [
-    ZaiPayment::Errors::ValidationError,
-    ZaiPayment::Errors::UnauthorizedError,
-    ZaiPayment::Errors::ForbiddenError,
-    ZaiPayment::Errors::NotFoundError
-  ]
-  
-  def self.handle(error, transaction)
-    case error
-    when *RETRY_ERRORS
-      # Retry the job
-      ProcessPaymentJob.set(wait: 5.minutes).perform_later(transaction.id)
-    when *PERMANENT_ERRORS
-      # Mark as failed permanently
-      transaction.update(
-        status: 'failed',
-        error_message: error.message
-      )
-      PaymentMailer.payment_error(transaction, error).deliver_now
-    when ZaiPayment::Errors::RateLimitError
-      # Retry after longer delay
-      ProcessPaymentJob.set(wait: 1.hour).perform_later(transaction.id)
-    else
-      # Log unknown error
-      Rails.logger.error("Unknown payment error: #{error.class} - #{error.message}")
-      Sentry.capture_exception(error) if defined?(Sentry)
-    end
-  end
-end
-```
-
-## Summary
-
-This example demonstrates:
-
-1. **User Creation**: Creating buyer and seller users in Zai
-2. **Card Capture**: Using the hosted form to securely capture card details
-3. **Item Creation**: Creating a payment item between buyer and seller
-4. **Payment Processing**: Making a payment using a card account
-5. **Webhook Handling**: Responding to payment events (authorized, completed, settled)
-6. **Error Handling**: Properly handling various error scenarios
-7. **Testing**: Simulating settlements in pre-live environment
-
-### Payment Flow States
-
-1. **Item Created** → Item exists but no payment made
-2. **Payment Initiated** → `make_payment` called
-3. **Authorized** → Card transaction successful (webhook: `transactions`)
-4. **Completed** → Item status changed to completed (webhook: `items`)
-5. **Settled** → Funds moved to seller's wallet (webhook: `batch_transactions`)
-
-### Important Notes
-
-- Always store Zai IDs (`zai_user_id`, `zai_item_id`, `zai_card_account_id`) in your database
-- Use webhooks for asynchronous updates rather than polling
-- Implement proper error handling and retries
-- Use background jobs for payment processing
-- Test thoroughly in pre-live environment before production
-- Verify webhook signatures for security
-- Handle PCI compliance requirements (the hosted form helps with this)
-
-
-## Reference
-- [Zai Cards Payin Workflow](https://developer.hellozai.com/docs/cards-payin-workflow)