airwallex 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24329b3008cb6844904a266d7cfed62b05bb0743935edd22a7ea1e3c1a98606e
-  data.tar.gz: 73d9c743bfa6da7e652da8663b98965985aefcbe575d373f322a7023232278f3
+  metadata.gz: ec7542a0e82153bbd60acceadb071eba2d48d328d89fa34d72d8a23dc30aeb45
+  data.tar.gz: b14a15b3b70878c6291bc6ffd447ccf81d4cab5d86e61b806cc0708bd70590e2
 SHA512:
-  metadata.gz: caae41e87cb5071ed6d8fdba00d873c6d90a6eabf20406a33e6261f960d8b65cf4355a71df4cac01c60ea5cb74705e9491843f74c1458559c8e24c1d5bebb044
-  data.tar.gz: 0b0924430871eb4065f78b75e2e1a6cad937089ebfec9801dbebcb8d5b7aa6e3ae49bbd882f8adb8406d0c3a17fd7a81956495dd9e194ea9349c41109b1faf2e
+  metadata.gz: 1e401e23580f1347cbf2caae60b985138c59e73a22ba758578c7ffd99b2318859f766e7c0e0a13f55bff4da29a6796029a359a12a9c1db32b213c972244e70a3
+  data.tar.gz: b7779fbdc8227ae72d20eda510799bb6898edb43c74d7aa6a6a30b7110f304be96b2e17673b02e832c2a9638c48f987b6ecf54027fc4b18f754d218fbaec4398

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-28
+
+### Fixed
+- `Webhook::Event` now correctly exposes the event type. Airwallex sends this field as `"name"` in
+  the webhook payload, not `"type"` — the previous `Event#type` reader was reading a key that doesn't
+  exist and always returned `nil`. The accessor is renamed to `Event#name` to match Airwallex's actual
+  field. **Breaking change:** `event.type` → `event.name`.
+
+## [0.5.0] - 2026-08-28
+
+### Fixed
+- Webhook signature verification no longer rejects valid webhooks when Airwallex sends
+  millisecond-precision timestamps. `verify_timestamp` now detects millisecond values (anything at or
+  above `MS_THRESHOLD = 10_000_000_000`, which safely distinguishes seconds from milliseconds until the
+  year 2286) and normalizes them to seconds before comparing against the tolerance window.
+
+## [0.4.0] - 2026-08-27
+
+### Fixed
+- `Idempotency` and `AuthRefresh` middleware are now actually registered on the Faraday connection.
+  Previously both classes existed but were never wired in, so the "automatic `request_id` generation"
+  and "retry once after a 401" behavior documented in the README did not happen at runtime.
+- Fixed a bug in `AuthRefresh` where the 401-retry guard used `env[:request][:auth_retry]`, a key that
+  doesn't exist on `Faraday::RequestOptions` and would have raised `NoMethodError` the first time it ran.
+- CI now triggers on pushes to `main` (previously configured for `master`, so pushes never ran CI).
+
+### Changed
+- `Client#request` no longer manually manages the `Authorization` header or calls
+  `ensure_authenticated!` directly; this is now owned by the `AuthRefresh` middleware.
+
+## [0.3.0] - 2025-11-25
+
+### Added
+- BatchTransfer resource (create, retrieve, list) for bulk payout operations
+- Dispute resource (retrieve, list, accept, submit_evidence) for chargeback management
+- 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
+- 63 new tests (278 total) covering batch transfers, disputes, 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.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
@@ -223,8 +319,8 @@ begin
     timestamp,
     tolerance: 300 # 5 minutes
   )
-  
-  case event.type
+
+  case event.name
   when 'payment_intent.succeeded'
     handle_successful_payment(event.data)
   when 'payout.transfer.failed'
@@ -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/client.rb

@@ -7,6 +7,8 @@ require "json"
 
 module Airwallex
   class Client
+    LOGIN_PATH = "/api/v1/authentication/login"
+
     attr_reader :config, :access_token, :token_expires_at
 
     def initialize(config = Airwallex.configuration)
@@ -19,11 +21,7 @@ module Airwallex
 
     def connection
       @connection ||= Faraday.new(url: config.api_url) do |conn|
-        conn.request :json
-        conn.request :multipart
-        conn.request :retry, retry_options
-        conn.response :json, content_type: /\bjson$/
-        conn.response :logger, config.logger, { headers: true, bodies: true } if config.logger
+        configure_middleware(conn)
 
         conn.headers["Content-Type"] = "application/json"
         conn.headers["User-Agent"] = user_agent
@@ -55,10 +53,9 @@ module Airwallex
 
     def authenticate!
       @token_mutex.synchronize do
-        response = connection.post("/api/v1/authentication/login") do |req|
+        response = connection.post(LOGIN_PATH) do |req|
           req.headers["x-client-id"] = config.client_id
           req.headers["x-api-key"] = config.api_key
-          req.headers.delete("Authorization")
         end
 
         handle_response_errors(response)
@@ -85,12 +82,9 @@ module Airwallex
     private
 
     def request(method, path, data, headers)
-      ensure_authenticated!
-
       response = connection.public_send(method) do |req|
         req.url(path)
         req.headers.merge!(headers)
-        req.headers["Authorization"] = "Bearer #{access_token}"
 
         case method
         when :get, :delete
@@ -104,6 +98,16 @@ module Airwallex
       response.body
     end
 
+    def configure_middleware(conn)
+      conn.use Airwallex::Middleware::Idempotency
+      conn.request :json
+      conn.request :multipart
+      conn.request :retry, retry_options
+      conn.use Airwallex::Middleware::AuthRefresh, self
+      conn.response :json, content_type: /\bjson$/
+      conn.response :logger, config.logger, { headers: true, bodies: true } if config.logger
+    end
+
     def handle_response_errors(response)
       return if response.success?
 

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/middleware/auth_refresh.rb

@@ -9,24 +9,38 @@ module Airwallex
       end
 
       def call(env)
-        # Skip authentication refresh for login endpoint
-        return @app.call(env) if env[:url].path.include?("/authentication/login")
+        # Skip authentication entirely for the login endpoint itself
+        return @app.call(env) if login_request?(env)
 
-        # Ensure token is valid before making request
-        @client.ensure_authenticated! unless env[:url].path.include?("/authentication/")
+        # Ensure token is valid before making the request, then attach it
+        @client.ensure_authenticated! unless authentication_request?(env)
+        authorize!(env)
 
         response = @app.call(env)
 
         # If we get a 401, try refreshing the token and retrying once
-        if response.status == 401 && !env[:request].fetch(:auth_retry, false)
+        if response.status == 401
           @client.authenticate!
-          env[:request][:auth_retry] = true
-          env[:request_headers]["Authorization"] = "Bearer #{@client.access_token}"
+          authorize!(env)
           response = @app.call(env)
         end
 
         response
       end
+
+      private
+
+      def login_request?(env)
+        env[:url].path.include?(Client::LOGIN_PATH)
+      end
+
+      def authentication_request?(env)
+        env[:url].path.include?("/authentication/")
+      end
+
+      def authorize!(env)
+        env[:request_headers]["Authorization"] = "Bearer #{@client.access_token}"
+      end
     end
   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