airwallex 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24329b3008cb6844904a266d7cfed62b05bb0743935edd22a7ea1e3c1a98606e
-  data.tar.gz: 73d9c743bfa6da7e652da8663b98965985aefcbe575d373f322a7023232278f3
+  metadata.gz: aff1a8f847f36f804c6ff9738480a8acd8e9aae867a9a3846311521337544c15
+  data.tar.gz: af199726a6f9cdcf4eef3d47c1ac1c24fd3ce92f9dd564c57730e75a8e4230ce
 SHA512:
-  metadata.gz: caae41e87cb5071ed6d8fdba00d873c6d90a6eabf20406a33e6261f960d8b65cf4355a71df4cac01c60ea5cb74705e9491843f74c1458559c8e24c1d5bebb044
-  data.tar.gz: 0b0924430871eb4065f78b75e2e1a6cad937089ebfec9801dbebcb8d5b7aa6e3ae49bbd882f8adb8406d0c3a17fd7a81956495dd9e194ea9349c41109b1faf2e
+  metadata.gz: 41ddfe80904d71772a0ed87a6f6f26ff3f857b8502bfde57c6e8b42bd53a162d6235ac6ae99ca52a11f2e4688dbe0682a96806ec2e97f1e2e3f617c038766c45
+  data.tar.gz: 907a5e84b3a38f3b4664ccf41d5ac4d62e04804073034845dfd9503b880113f2bc32d8c365ca9cca96dd6870ac4ebc1283ca93da93fb59128789b001b556ef47

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-11-25
+
+### Added
+- Foreign Exchange resources:
+  - Rate resource (retrieve, list) for real-time exchange rate queries
+  - Quote resource (create, retrieve) for locking exchange rates with expiration helpers
+  - Conversion resource (create, retrieve, list) for executing currency conversions
+  - Balance resource (list, retrieve) for querying account balances across currencies
+- Enhanced List operation to handle both array responses and paginated responses
+- 38 new tests (278 total) covering FX and balance operations
+- Comprehensive manual test suite for regression testing
+
+### Changed
+- Refactored List operation for better code quality (reduced complexity from 12 to 7)
+- Balance.retrieve now performs client-side filtering for currency lookup
+
+### Fixed
+- List operation now correctly handles Balance API's direct array response format
+
+## [0.2.1] - 2025-11-25
+
+### Added
+- BatchTransfer resource (create, retrieve, list) for bulk payout operations
+- Dispute resource (retrieve, list, accept, submit_evidence) for chargeback management
+- 25 new tests (240 total) covering batch transfers and disputes
+
 ## [0.2.0] - 2025-11-25
 
 ### Added

data/README.md

@@ -154,6 +154,102 @@ payment_intent.confirm(payment_method_id: payment_method.id)
 methods = customer.payment_methods
 ```
 
+### Batch Transfers
+
+```ruby
+# Create a batch of transfers for bulk payouts
+batch = Airwallex::BatchTransfer.create(
+  request_id: "batch_#{Time.now.to_i}",
+  source_currency: 'USD',
+  transfers: [
+    { beneficiary_id: 'ben_001', amount: 100.00, reason: 'Seller payout' },
+    { beneficiary_id: 'ben_002', amount: 250.00, reason: 'Affiliate payment' },
+    { beneficiary_id: 'ben_003', amount: 500.00, reason: 'Vendor payment' }
+  ]
+)
+
+# Check batch status
+batch = Airwallex::BatchTransfer.retrieve(batch.id)
+puts "Completed: #{batch.success_count}/#{batch.total_count}"
+
+# Check individual transfer statuses
+batch.transfers.each do |transfer|
+  puts "#{transfer.id}: #{transfer.status}"
+end
+```
+
+### Managing Disputes
+
+```ruby
+# List all open disputes
+disputes = Airwallex::Dispute.list(status: 'OPEN')
+
+# Get specific dispute
+dispute = Airwallex::Dispute.retrieve('dis_123')
+puts "Dispute amount: #{dispute.amount} #{dispute.currency}"
+puts "Reason: #{dispute.reason}"
+puts "Evidence due: #{dispute.evidence_due_by}"
+
+# Submit evidence to challenge
+dispute.submit_evidence(
+  customer_communication: 'Email showing delivery confirmation',
+  shipping_tracking_number: '1Z999AA10123456784',
+  shipping_documentation: 'Proof of delivery with signature'
+)
+
+# Or accept dispute without challenging
+dispute.accept
+```
+
+### Foreign Exchange & Multi-Currency
+
+```ruby
+# Get real-time exchange rate
+rate = Airwallex::Rate.retrieve(
+  buy_currency: 'EUR',
+  sell_currency: 'USD'
+)
+puts "Current rate: #{rate.client_rate}"
+
+# Lock in a rate with a quote (valid for 24 hours)
+quote = Airwallex::Quote.create(
+  buy_currency: 'EUR',
+  sell_currency: 'USD',
+  sell_amount: 10000.00,
+  validity: 'HR_24'
+)
+
+puts "Locked rate: #{quote.client_rate}"
+puts "Expires in: #{quote.seconds_until_expiration} seconds"
+puts "Is expired? #{quote.expired?}"
+
+# Execute conversion using locked quote
+conversion = Airwallex::Conversion.create(
+  quote_id: quote.id,
+  reason: 'Multi-currency settlement'
+)
+
+# Or convert at current market rate
+conversion = Airwallex::Conversion.create(
+  buy_currency: 'EUR',
+  sell_currency: 'USD',
+  sell_amount: 5000.00,
+  reason: 'Currency exchange'
+)
+
+# Check account balances
+balances = Airwallex::Balance.list
+balances.each do |balance|
+  next if balance.available_amount <= 0
+  puts "#{balance.currency}: #{balance.available_amount} available"
+end
+
+# Get specific currency balance
+usd_balance = Airwallex::Balance.retrieve('USD')
+puts "USD Available: #{usd_balance.available_amount}"
+puts "USD Total: #{usd_balance.total_amount}"
+```
+
 ## Usage
 
 ### Authentication
@@ -319,23 +415,29 @@ end
 
 ### Currently Implemented Resources
 
-- **Payment Acceptance**: 
+- **Payment Acceptance**:
   - PaymentIntent (create, retrieve, list, update, confirm, cancel, capture)
   - Refund (create, retrieve, list)
   - PaymentMethod (create, retrieve, list, update, delete, detach)
   - Customer (create, retrieve, list, update, delete)
-- **Payouts**: 
+  - Dispute (retrieve, list, accept, submit_evidence)
+- **Payouts**:
   - Transfer (create, retrieve, list, cancel)
   - Beneficiary (create, retrieve, list, delete)
+  - BatchTransfer (create, retrieve, list)
+- **Foreign Exchange & Multi-Currency**:
+  - Rate (retrieve, list) - Real-time exchange rate queries
+  - Quote (create, retrieve) - Lock exchange rates with expiration tracking
+  - Conversion (create, retrieve, list) - Execute currency conversions
+  - Balance (list, retrieve) - Query account balances across currencies
 - **Webhooks**: Event handling, HMAC-SHA256 signature verification
 
 ### Coming in Future Versions
 
-- Disputes and chargebacks
-- Foreign exchange (rates, quotes, conversions)
 - Global accounts
 - Card issuing
-- Batch transfers
+- Subscriptions and billing
+- Virtual account numbers
 
 ## Environment Support
 

data/lib/airwallex/api_operations/list.rb

@@ -4,20 +4,39 @@ module Airwallex
   module APIOperations
     module List
       def list(params = {}, opts = {})
-        response = Airwallex.client.get(
-          resource_path,
-          params,
-          opts[:headers] || {}
-        )
+        response = Airwallex.client.get(resource_path, params, opts[:headers] || {})
+        build_list_object(response, params)
+      end
+
+      private
 
+      def build_list_object(response, params)
         ListObject.new(
-          data: response[:items] || response["items"] || [],
-          has_more: response[:has_more] || response["has_more"] || false,
-          next_cursor: response[:next_cursor] || response["next_cursor"],
+          data: extract_data(response),
+          has_more: extract_has_more(response),
+          next_cursor: extract_next_cursor(response),
           resource_class: self,
           params: params
         )
       end
+
+      def extract_data(response)
+        return response if response.is_a?(Array)
+
+        response[:items] || response["items"] || response[:data] || response["data"] || []
+      end
+
+      def extract_has_more(response)
+        return false unless response.is_a?(Hash)
+
+        response[:has_more] || response["has_more"] || false
+      end
+
+      def extract_next_cursor(response)
+        return nil unless response.is_a?(Hash)
+
+        response[:next_cursor] || response["next_cursor"]
+      end
     end
   end
 end

data/lib/airwallex/errors.rb

@@ -59,6 +59,7 @@ module Airwallex
   class RateLimitError < Error; end
   class APIError < Error; end
   class InsufficientFundsError < Error; end
+  class QuoteExpiredError < BadRequestError; end
   class SCARequiredError < PermissionError; end
   class SignatureVerificationError < Error; end
 end

data/lib/airwallex/resources/balance.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Balance resource for account balance queries
+  #
+  # Query account balances across all currencies or for specific currencies.
+  # Shows available, pending, and reserved amounts.
+  #
+  # @example Get all balances
+  #   balances = Airwallex::Balance.list
+  #   balances.each do |balance|
+  #     puts "#{balance.currency}: #{balance.available_amount}"
+  #   end
+  #
+  # @example Get specific currency balance
+  #   usd_balance = Airwallex::Balance.retrieve('USD')
+  #   puts "Available: #{usd_balance.available_amount}"
+  #   puts "Pending: #{usd_balance.pending_amount}"
+  #   puts "Reserved: #{usd_balance.reserved_amount}"
+  #
+  class Balance < APIResource
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/balances/current"
+    end
+
+    # Retrieve balance for a specific currency
+    #
+    # @param currency [String] Currency code (e.g., 'USD', 'EUR')
+    # @return [Airwallex::Balance] Balance object for the currency
+    def self.retrieve(currency)
+      response = Airwallex.client.get(resource_path, currency: currency)
+      # Balance API returns array directly at top level
+      balances_array = response.is_a?(Array) ? response : response[:data] || response["data"] || []
+      balances = ListObject.new(
+        data: balances_array,
+        has_more: false,
+        resource_class: self
+      )
+
+      # Filter to find the requested currency
+      balance = balances.find { |b| b.currency&.upcase == currency.upcase }
+      raise NotFoundError, "Balance not found for currency: #{currency}" unless balance
+
+      balance
+    end
+
+    # Calculate total balance
+    #
+    # @return [Float] Sum of available, pending, and reserved amounts
+    def total_amount
+      available = respond_to?(:available_amount) ? available_amount.to_f : 0.0
+      pending = respond_to?(:pending_amount) ? pending_amount.to_f : 0.0
+      reserved = respond_to?(:reserved_amount) ? reserved_amount.to_f : 0.0
+      (available + pending + reserved).round(2)
+    end
+  end
+end

data/lib/airwallex/resources/batch_transfer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # BatchTransfer resource for bulk payout operations
+  #
+  # Batch transfers allow creating multiple transfers in a single API call,
+  # improving efficiency for bulk payout scenarios like marketplace payouts or payroll.
+  #
+  # @example Create a batch transfer
+  #   batch = Airwallex::BatchTransfer.create(
+  #     request_id: "batch_#{Time.now.to_i}",
+  #     source_currency: "USD",
+  #     transfers: [
+  #       { beneficiary_id: "ben_001", amount: 100.00, reason: "Payout 1" },
+  #       { beneficiary_id: "ben_002", amount: 200.00, reason: "Payout 2" }
+  #     ]
+  #   )
+  #
+  # @example Retrieve a batch transfer
+  #   batch = Airwallex::BatchTransfer.retrieve("batch_123")
+  #   batch.transfers.each { |t| puts "#{t.id}: #{t.status}" }
+  #
+  class BatchTransfer < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/batch_transfers"
+    end
+  end
+end

data/lib/airwallex/resources/conversion.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Conversion resource for currency exchange
+  #
+  # Execute currency conversions with locked quotes or at market rates.
+  # Conversions move funds between currency balances in your account.
+  #
+  # @example Convert with locked quote
+  #   quote = Airwallex::Quote.create(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD',
+  #     sell_amount: 1000.00
+  #   )
+  #   conversion = Airwallex::Conversion.create(
+  #     quote_id: quote.id,
+  #     request_id: "conv_#{Time.now.to_i}"
+  #   )
+  #
+  # @example Convert at market rate
+  #   conversion = Airwallex::Conversion.create(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD',
+  #     sell_amount: 500.00,
+  #     request_id: "conv_#{Time.now.to_i}"
+  #   )
+  #
+  # @example List conversion history
+  #   conversions = Airwallex::Conversion.list(
+  #     sell_currency: 'USD',
+  #     status: 'COMPLETED'
+  #   )
+  #
+  class Conversion < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/conversions"
+    end
+  end
+end

data/lib/airwallex/resources/customer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a customer for organizing payment methods and transactions
+  #
+  # Customers allow you to group payment methods and track payment history
+  # for individual users or accounts.
+  #
+  # @example Create a customer
+  #   customer = Airwallex::Customer.create(
+  #     email: "john@example.com",
+  #     first_name: "John",
+  #     last_name: "Doe",
+  #     metadata: { internal_id: "user_789" }
+  #   )
+  #
+  # @example List payment methods for a customer
+  #   methods = Airwallex::PaymentMethod.list(customer_id: customer.id)
+  class Customer < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    extend APIOperations::Update
+    include APIOperations::Update
+    extend APIOperations::Delete
+
+    # @return [String] API resource path for customers
+    def self.resource_path
+      "/api/v1/pa/customers"
+    end
+
+    # List payment methods for this customer
+    #
+    # @param params [Hash] additional parameters
+    # @return [ListObject<PaymentMethod>] list of payment methods
+    def payment_methods(params = {})
+      PaymentMethod.list(params.merge(customer_id: id))
+    end
+  end
+end

data/lib/airwallex/resources/dispute.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Dispute resource for handling chargebacks and payment disputes
+  #
+  # Disputes represent chargebacks or payment disputes initiated by cardholders.
+  # Merchants can view disputes, submit evidence to challenge them, or accept them.
+  #
+  # @example List open disputes
+  #   disputes = Airwallex::Dispute.list(status: 'OPEN')
+  #
+  # @example Retrieve a dispute
+  #   dispute = Airwallex::Dispute.retrieve('dis_123')
+  #
+  # @example Submit evidence
+  #   dispute = Airwallex::Dispute.retrieve('dis_123')
+  #   dispute.submit_evidence(
+  #     customer_communication: "Email showing delivery confirmation",
+  #     shipping_tracking_number: "1Z999AA10123456784"
+  #   )
+  #
+  # @example Accept a dispute
+  #   dispute = Airwallex::Dispute.retrieve('dis_123')
+  #   dispute.accept
+  #
+  class Dispute < APIResource
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/disputes"
+    end
+
+    # Accept a dispute without challenging it
+    #
+    # @return [Airwallex::Dispute] The updated dispute object
+    def accept
+      response = Airwallex.client.post("#{resource_path}/#{id}/accept", {})
+      refresh_from(response)
+      self
+    end
+
+    # Submit evidence to challenge a dispute
+    #
+    # @param evidence [Hash] Evidence details
+    # @option evidence [String] :customer_communication Email or chat logs
+    # @option evidence [String] :shipping_tracking_number Tracking number
+    # @option evidence [String] :shipping_documentation Proof of shipping
+    # @option evidence [String] :customer_signature Signed receipt
+    # @option evidence [String] :receipt Proof of purchase
+    # @option evidence [String] :refund_policy Refund policy document
+    # @option evidence [String] :cancellation_policy Cancellation policy
+    # @option evidence [String] :additional_information Other relevant info
+    #
+    # @return [Airwallex::Dispute] The updated dispute object
+    def submit_evidence(evidence)
+      response = Airwallex.client.post("#{resource_path}/#{id}/evidence", evidence)
+      refresh_from(response)
+      self
+    end
+
+    private
+
+    def resource_path
+      self.class.resource_path
+    end
+  end
+end

data/lib/airwallex/resources/payment_method.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a payment method (card, bank account, etc.) that can be reused
+  #
+  # Payment methods allow you to store customer payment credentials securely
+  # and reuse them for future payments without collecting details again.
+  #
+  # @example Create a card payment method
+  #   pm = Airwallex::PaymentMethod.create(
+  #     type: "card",
+  #     card: {
+  #       number: "4242424242424242",
+  #       expiry_month: "12",
+  #       expiry_year: "2025",
+  #       cvc: "123"
+  #     },
+  #     billing: {
+  #       first_name: "John",
+  #       email: "john@example.com"
+  #     }
+  #   )
+  #
+  # @example Use saved payment method
+  #   payment_intent.confirm(payment_method_id: pm.id)
+  #
+  # @example Update billing details
+  #   pm.update(billing: { address: { postal_code: "10001" } })
+  class PaymentMethod < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    extend APIOperations::Update
+    include APIOperations::Update
+    extend APIOperations::Delete
+
+    # @return [String] API resource path for payment methods
+    def self.resource_path
+      "/api/v1/pa/payment_methods"
+    end
+
+    # Detach this payment method from its customer
+    #
+    # @return [PaymentMethod] self
+    def detach
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/detach", {})
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/quote.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Quote resource for locked exchange rates
+  #
+  # Create quotes to lock exchange rates for a short period (typically 30-60 seconds).
+  # Use quotes to guarantee the rate when executing conversions.
+  #
+  # @example Create a quote
+  #   quote = Airwallex::Quote.create(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD',
+  #     sell_amount: 1000.00
+  #   )
+  #   puts "Locked rate: #{quote.client_rate}, expires: #{quote.expires_at}"
+  #
+  # @example Use quote for conversion
+  #   conversion = Airwallex::Conversion.create(quote_id: quote.id)
+  #
+  class Quote < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+
+    def self.resource_path
+      "/api/v1/fx/quotes"
+    end
+
+    # Check if quote has expired
+    #
+    # @return [Boolean] true if quote is expired
+    def expired?
+      return false unless respond_to?(:expires_at) && expires_at
+
+      Time.parse(expires_at) < Time.now
+    rescue ArgumentError
+      true
+    end
+
+    # Get seconds until expiration
+    #
+    # @return [Integer, nil] seconds remaining, 0 if expired, nil if no expiration
+    def seconds_until_expiration
+      return nil unless respond_to?(:expires_at) && expires_at
+
+      remaining = Time.parse(expires_at) - Time.now
+      [remaining.to_i, 0].max
+    rescue ArgumentError
+      0
+    end
+  end
+end

data/lib/airwallex/resources/rate.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Rate resource for real-time exchange rates
+  #
+  # Get indicative exchange rates for currency pairs.
+  # Rates are real-time but not locked - use Quote for guaranteed rates.
+  #
+  # @example Get current rate
+  #   rate = Airwallex::Rate.retrieve(buy_currency: 'EUR', sell_currency: 'USD')
+  #   puts "1 USD = #{rate.client_rate} EUR"
+  #
+  # @example Get multiple rates (Note: API may not support multiple at once)
+  #   rate = Airwallex::Rate.retrieve(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD'
+  #   )
+  #
+  class Rate < APIResource
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/fx/rates/current"
+    end
+
+    # Override retrieve to handle query parameters instead of ID
+    def self.retrieve(params = {})
+      response = Airwallex.client.get(resource_path, params)
+      new(response)
+    end
+  end
+end

data/lib/airwallex/resources/refund.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a refund of a payment intent
+  #
+  # Refunds can be full or partial. Multiple refunds can be created for a single
+  # payment intent as long as the total refunded amount doesn't exceed the original amount.
+  #
+  # @example Create a full refund
+  #   refund = Airwallex::Refund.create(
+  #     payment_intent_id: "pi_123",
+  #     amount: 100.00,
+  #     reason: "requested_by_customer"
+  #   )
+  #
+  # @example Create a partial refund
+  #   refund = Airwallex::Refund.create(
+  #     payment_intent_id: "pi_123",
+  #     amount: 25.00
+  #   )
+  #
+  # @example List refunds for a payment
+  #   refunds = Airwallex::Refund.list(payment_intent_id: "pi_123")
+  class Refund < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for refunds
+    def self.resource_path
+      "/api/v1/pa/refunds"
+    end
+  end
+end

data/lib/airwallex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Airwallex
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/airwallex.rb

@@ -27,6 +27,12 @@ require_relative "airwallex/resources/beneficiary"
 require_relative "airwallex/resources/refund"
 require_relative "airwallex/resources/payment_method"
 require_relative "airwallex/resources/customer"
+require_relative "airwallex/resources/batch_transfer"
+require_relative "airwallex/resources/dispute"
+require_relative "airwallex/resources/rate"
+require_relative "airwallex/resources/quote"
+require_relative "airwallex/resources/conversion"
+require_relative "airwallex/resources/balance"
 
 module Airwallex
   class << self