airwallex 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fad10ff0adfb96f6cb5e3a88ec1825a17b840d73658bd6fb6813f18e2746fea1
-  data.tar.gz: 9f59e5dfc64382838c7b1485b4ca28b19e9b71248ea51070ff106ad33cb1af32
+  metadata.gz: be0adbfbafc982fa5c899a9df4230e9c65a68e46d2e7eb248b981e41ccc23bd4
+  data.tar.gz: 599bdc078288f934cc5f8b06fced1668605c8e2e6af4763d943a9f227a32e563
 SHA512:
-  metadata.gz: de57501742d42048dd6a9286672c18050a17734ac2e21780f85e2d23e16e856bf406df20842352d55cd46aff22bfb0ade9676e1e6578865a7c966eba833880eb
-  data.tar.gz: 809fce3bea1462cecb398388b34863f65edf4ef00a5742ce0c30776c0dcbf942b474daef0551e64cd81b79ddb8a44fb01ef210fd2cec8470dbe844ce4f5968c6
+  metadata.gz: 4cd20d177f642d64bdb07922f673483ab3d86499c0a938c8a7db7854f06fd5dff86b10326c09496dbf9a0bc8099a64834fc0ee4a56ff91d822dd721aff911e7a
+  data.tar.gz: 56b071c9ff52ccf48f6526c6f3a8264d55c1d8cfcc5794d869894535baf7685c7642bdebf498f5c4ed01e362631f62a9721d4151bc6f860cf91b574a2a2d54b7

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-02
+
+### Fixed
+- `Util.deep_symbolize_keys` now recurses into `Array`s, matching `ActiveSupport#deep_transform_keys`'s
+  behavior. Previously any `Array` value was copied through untouched, so hashes nested inside an array
+  (e.g. `beneficiary_form_schemas`'s `fields` list) kept string keys even after "deep" symbolizing.
+- `Beneficiary.validate`, `.verify_account`, `.api_schema`, `.form_schema`, and
+  `.supported_financial_institutions`, `ConnectedAccount.wallet_info`, `BillingCustomer#bank_transfer_instructions`,
+  and `GlobalAccount#generate_statement_letter` now return `Util.deep_symbolize_keys`-processed responses,
+  via two new shared helpers, `APIResource.symbolized_post`/`.symbolized_get`. Previously these methods
+  (unlike `.create`/`.retrieve`/`.update`/`.delete`/`.list`, which already funnel through `APIResource`'s
+  symbolization) returned the raw parsed JSON response with string keys, with nothing in the method
+  signature or naming to distinguish them from the symbolized methods on the same class.
+- `Airwallex::Error#details` is now symbolized too (via the same `Util.deep_symbolize_keys` fix), instead
+  of holding the raw, string-keyed error body.
+
+  **Breaking change:** any code reading these nine methods'/`#details`' values with string keys
+  (`response["field"]`) must switch to symbol keys (`response[:field]`).
+
 ## [0.7.0] - 2026-08-28
 
 ### Added

data/README.md

@@ -6,17 +6,22 @@ A Ruby client library for the [Airwallex API](https://www.airwallex.com/docs/api
 
 This gem provides a Ruby interface to Airwallex's payment infrastructure, designed for Ruby 3.1+ applications. It includes core functionality for authentication management, idempotency guarantees, webhook verification, and multi-environment support.
 
-**Current Features (v0.1.0):**
+**Current Features:**
 
 - **Authentication**: Bearer token authentication with automatic refresh
-- **Payment Acceptance**: Payment intent creation, confirmation, and management
-- **Payouts**: Transfer creation and beneficiary management
+- **Payment Acceptance**: Payment intents, refunds, payment methods, customers, disputes
+- **Payouts**: Transfers, batch transfers, and beneficiary management
+- **Foreign Exchange**: Real-time rates, locked quotes, and currency conversions
+- **Global Accounts**: Virtual account numbers (VANs), inbound transaction reconciliation, aliases, and direct debit mandates
+- **Billing**: Products, prices, billing customers, and subscriptions for recurring/instalment billing
+- **Recurring Payments**: Payment consents and payment sources for merchant-initiated (off-session) charges
+- **Scale**: Connected accounts, funds splits, and charges for platforms onboarding sub-merchants
 - **Idempotency**: Automatic request deduplication for safe retries
 - **Pagination**: Unified interface over cursor-based and offset-based pagination
 - **Webhook Security**: HMAC-SHA256 signature verification with replay protection
 - **Sandbox Support**: Full testing environment for development
 
-**Note:** This is an initial MVP release. Additional resources (FX, cards, refunds, etc.) will be added in future versions.
+**Not yet implemented:** Card issuing.
 
 ## Installation
 
@@ -82,14 +87,30 @@ payment_intent.confirm(
 ```ruby
 # Create a beneficiary
 beneficiary = Airwallex::Beneficiary.create(
-  bank_details: {
-    account_number: '123456789',
-    account_routing_type1: 'aba',
-    account_routing_value1: '026009593',
-    bank_country_code: 'US'
-  },
-  beneficiary_type: 'BUSINESS',
-  company_name: 'Acme Corp'
+  nickname: 'Acme Corp',
+  payer_entity_type: 'COMPANY',
+  transfer_methods: ['LOCAL'],
+  beneficiary: {
+    entity_type: 'COMPANY',
+    company_name: 'Acme Corp',
+    address: {
+      country_code: 'AU',
+      city: 'Melbourne',
+      state: 'VIC',
+      postcode: '3000',
+      street_address: '15 William Street'
+    },
+    bank_details: {
+      account_name: 'Acme Corp',
+      account_number: '12750852',
+      account_currency: 'AUD',
+      bank_country_code: 'AU',
+      bank_name: 'National Australia Bank',
+      account_routing_type1: 'bsb',
+      account_routing_value1: '083064',
+      local_clearing_system: 'BANK_TRANSFER'
+    }
+  }
 )
 
 # Execute transfer
@@ -127,6 +148,7 @@ refunds = Airwallex::Refund.list(payment_intent_id: payment_intent.id)
 ```ruby
 # Create a customer
 customer = Airwallex::Customer.create(
+  merchant_customer_id: 'internal_customer_001',
   email: 'customer@example.com',
   first_name: 'John',
   last_name: 'Doe'
@@ -152,6 +174,9 @@ payment_intent.confirm(payment_method_id: payment_method.id)
 
 # List customer's payment methods
 methods = customer.payment_methods
+
+# Disable a payment method (PaymentMethods have no delete/detach endpoint)
+payment_method.disable
 ```
 
 ### Batch Transfers
@@ -190,8 +215,8 @@ 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(
+# Challenge the dispute with evidence
+dispute.challenge(
   customer_communication: 'Email showing delivery confirmation',
   shipping_tracking_number: '1Z999AA10123456784',
   shipping_documentation: 'Proof of delivery with signature'
@@ -199,6 +224,9 @@ dispute.submit_evidence(
 
 # Or accept dispute without challenging
 dispute.accept
+
+# List the payment intents related to a dispute
+dispute.related_payment_intents
 ```
 
 ### Foreign Exchange & Multi-Currency
@@ -250,6 +278,144 @@ puts "USD Available: #{usd_balance.available_amount}"
 puts "USD Total: #{usd_balance.total_amount}"
 ```
 
+### Global Accounts (Virtual Account Numbers)
+
+```ruby
+# Provision a VAN
+account = Airwallex::GlobalAccount.create(
+  country_code: 'AU',
+  nick_name: 'booking_12345',
+  required_features: [{ transfer_method: 'LOCAL' }]
+)
+
+# List inbound transactions for reconciliation
+account.transactions.each { |txn| puts "#{txn.amount} from #{txn.remitter}" }
+
+# Add and verify an alias (e.g. a phone number or email VAN)
+alias_record = account.create_alias(type: 'PAYID_PHONE', value: '+61400000000')
+alias_record.submit_verification_code(code: '123456')
+account.aliases
+
+# Manage direct debit mandates
+account.mandates
+mandate = account.mandate('mandate_id')
+mandate.cancel
+```
+
+### Billing & Subscriptions
+
+```ruby
+# Create a billing customer
+billing_customer = Airwallex::BillingCustomer.create(
+  name: 'Acme Corp',
+  email: 'billing@acme.com',
+  type: 'BUSINESS',
+  default_billing_currency: 'AUD',
+  default_legal_entity_id: connected_account.legal_entity_id,
+  address: {
+    street: '15 William Street',
+    city: 'Melbourne',
+    state: 'VIC',
+    postcode: '3000',
+    country_code: 'AU'
+  }
+)
+
+# Define a product and a recurring price
+product = Airwallex::BillingProduct.create(name: 'Pro Plan')
+price = Airwallex::BillingPrice.create(
+  product_id: product.id,
+  currency: 'AUD',
+  unit_amount: 99.00,
+  pricing_model: 'PER_UNIT',
+  recurring: { period: 1, period_unit: 'MONTH' }
+)
+
+# Subscriptions bill against a PaymentSource, not a PaymentConsent directly
+# (see "Recurring Payments" below for how to obtain one)
+subscription = Airwallex::BillingSubscription.create(
+  billing_customer_id: billing_customer.id,
+  currency: 'AUD',
+  collection_method: 'AUTO_CHARGE',
+  legal_entity_id: connected_account.legal_entity_id,
+  payment_source_id: payment_source.id,
+  starts_at: '2026-09-01T00:00:00+1000',
+  items: [{ price_id: price.id, quantity: 1 }]
+)
+
+# Inspect subscription line items
+subscription.items
+```
+
+### Recurring Payments (Payment Consents & Sources)
+
+Off-session charges flow through three linked resources: a `PaymentMethod` is
+consented to future charges via a `PaymentConsent`, which then backs a
+`PaymentSource` that `BillingSubscription` (and other billing resources) can
+charge automatically.
+
+```ruby
+# Consent to future merchant-initiated charges on a saved payment method
+consent = Airwallex::PaymentConsent.create(
+  customer_id: customer.id,
+  payment_method: { id: payment_method.id },
+  next_triggered_by: 'merchant',
+  merchant_trigger_reason: 'unscheduled'
+)
+consent.verify(payment_method: { card: { cvc: '123' } })
+
+# Wrap the consented payment method as a Payment Source for Billing
+# external_id is the PaymentMethod's id, not the PaymentConsent's id
+payment_source = Airwallex::PaymentSource.create(
+  billing_customer_id: billing_customer.id,
+  external_id: payment_method.id,
+  linked_payment_account_id: connected_account.id
+)
+```
+
+### Scale (Connected Accounts, Funds Splits, Charges)
+
+For platforms onboarding sub-merchants:
+
+```ruby
+# Onboard a connected account
+# account_details is a required top-level wrapper; nickname/primary_contact/
+# customer_agreements are top-level siblings, not nested inside it.
+connected_account = Airwallex::ConnectedAccount.create(
+  nickname: 'Sub-merchant Co',
+  primary_contact: { email: 'contact@submerchant.com' },
+  customer_agreements: {
+    agreed_to_terms_and_conditions: true,
+    agreed_to_data_usage: true,
+    terms_and_conditions: { service_agreement_type: 'FULL' }
+  },
+  account_details: {
+    legal_entity_type: 'BUSINESS',
+    business_details: {
+      business_name: 'Sub-merchant Co',
+      business_structure: 'COMPANY'
+    }
+  }
+)
+connected_account.legal_entity_id
+connected_account.agree_to_terms_and_conditions
+connected_account.submit
+
+# Inspect the platform's own account
+Airwallex::ConnectedAccount.current
+Airwallex::ConnectedAccount.wallet_info
+
+# Split a charge's funds between the platform and a connected account
+split = Airwallex::FundsSplit.create(
+  payment_intent_id: payment_intent.id,
+  splits: [{ account_id: connected_account.id, amount: 10.00 }]
+)
+split.release
+
+# Charges (create, retrieve, list)
+charge = Airwallex::Charge.retrieve('charge_id')
+```
+
 ## Usage
 
 ### Authentication
@@ -367,10 +533,16 @@ end
 ```
 lib/airwallex/
 ├── api_operations/        # CRUD operation mixins (Create, Retrieve, List, Update, Delete)
-├── resources/             # Implemented resources
-│   ├── payment_intent.rb  # Payment acceptance
-│   ├── transfer.rb        # Payouts
-│   └── beneficiary.rb     # Payout beneficiaries
+├── resources/             # Implemented resources, grouped by API area:
+│   │                      #   payment acceptance    - payment_intent, refund, payment_method, customer, dispute
+│   │                      #   payouts                - transfer, batch_transfer, beneficiary
+│   │                      #   foreign exchange        - rate, quote, conversion, balance
+│   │                      #   global accounts         - global_account(+_alias, _mandate, _transaction)
+│   │                      #   billing                 - billing_customer, billing_product, billing_price,
+│   │                      #                             billing_subscription(+_item)
+│   │                      #   recurring payments      - payment_consent, payment_source
+│   │                      #   scale                   - connected_account, account_amendment, funds_split, charge
+│   └── ...                # see lib/airwallex/resources/ for the full, current list
 ├── api_resource.rb        # Base resource class with dynamic attributes
 ├── list_object.rb         # Pagination wrapper
 ├── errors.rb              # Exception hierarchy
@@ -418,26 +590,40 @@ end
 - **Payment Acceptance**:
   - PaymentIntent (create, retrieve, list, update, confirm, cancel, capture)
   - Refund (create, retrieve, list)
-  - PaymentMethod (create, retrieve, list, update, delete, detach)
+  - PaymentMethod (create, retrieve, list, update, disable)
   - Customer (create, retrieve, list, update, delete)
-  - Dispute (retrieve, list, accept, submit_evidence)
+  - Dispute (retrieve, list, accept, challenge, related_payment_intents)
 - **Payouts**:
   - Transfer (create, retrieve, list, cancel)
-  - Beneficiary (create, retrieve, list, delete)
+  - Beneficiary (create, retrieve, list, update, delete, validate, verify_account, api_schema, form_schema, supported_financial_institutions)
   - BatchTransfer (create, retrieve, list)
 - **Foreign Exchange & Multi-Currency**:
-  - Rate (retrieve, list) - Real-time exchange rate queries
+  - Rate (retrieve) - 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
+- **Global Accounts**:
+  - GlobalAccount (create, retrieve, list, update, close, generate_statement_letter, create_alias, aliases, mandate, mandates)
+  - GlobalAccountTransaction, GlobalAccountAlias, GlobalAccountMandate (list/lifecycle actions scoped to a parent account)
+- **Billing & Subscriptions**:
+  - BillingCustomer (create, retrieve, list, update, bank_transfer_instructions)
+  - BillingProduct (create, retrieve, list, update)
+  - BillingPrice (create, retrieve, list, update)
+  - BillingSubscription (create, retrieve, list, update, items)
+  - BillingSubscriptionItem (scoped to a parent subscription)
+- **Recurring Payments**:
+  - PaymentConsent (create, retrieve, list, update, verify, verify_continue, disable)
+  - PaymentSource (create, retrieve, list)
+- **Scale**:
+  - ConnectedAccount (create, retrieve, list, update, current, wallet_info, submit, agree_to_terms_and_conditions, suspend, reactivate)
+  - AccountAmendment (create, retrieve) - requires Admin-level API key permissions
+  - FundsSplit (create, retrieve, list, release)
+  - Charge (create, retrieve, list)
 - **Webhooks**: Event handling, HMAC-SHA256 signature verification
 
 ### Coming in Future Versions
 
-- Global accounts
 - Card issuing
-- Subscriptions and billing
-- Virtual account numbers
 
 ## Environment Support
 

data/lib/airwallex/api_resource.rb

@@ -24,6 +24,28 @@ module Airwallex
       raise NotImplementedError, "#{self} must implement .resource_path"
     end
 
+    # Perform a one-off POST that returns a plain, symbolized Hash rather
+    # than an APIResource — for actions with no id/refresh lifecycle of
+    # their own (e.g. Beneficiary.verify_account, a bank-detail check that
+    # never becomes a resource).
+    #
+    # @param path [String] the request path
+    # @param params [Hash] request body
+    # @return [Hash] symbolized response
+    def self.symbolized_post(path, params = {})
+      Util.deep_symbolize_keys(Airwallex.client.post(path, params))
+    end
+
+    # Perform a one-off GET that returns a plain, symbolized Hash rather
+    # than an APIResource. See .symbolized_post.
+    #
+    # @param path [String] the request path
+    # @param params [Hash] query params
+    # @return [Hash] symbolized response
+    def self.symbolized_get(path, params = {})
+      Util.deep_symbolize_keys(Airwallex.client.get(path, params))
+    end
+
     # Dynamic attribute accessors
     def method_missing(method_name, *args, &)
       method_str = method_name.to_s

data/lib/airwallex/errors.rb

@@ -2,13 +2,18 @@
 
 module Airwallex
   class Error < StandardError
+    # @return [String, nil] error code
+    # @return [String, nil] param the offending field path, from the response's `source`
+    # @return [Hash, Array, nil] details symbolized field-level error detail, e.g. from a
+    #   validation_failed response (was raw/string-keyed prior to 0.8.0)
+    # @return [Integer, nil] http_status
     attr_reader :code, :message, :param, :details, :http_status
 
     def initialize(message = nil, code: nil, param: nil, details: nil, http_status: nil)
       @code = code
       @message = message
       @param = param
-      @details = details
+      @details = Util.deep_symbolize_keys(details)
       @http_status = http_status
       super(message)
     end

data/lib/airwallex/resources/beneficiary.rb

@@ -64,36 +64,36 @@ module Airwallex
     # method) before attempting to create the beneficiary.
     #
     # @param params [Hash] the same shape of params you'd pass to .create
-    # @return [Hash] raw validation result
+    # @return [Hash] symbolized validation result
     def self.validate(params = {})
-      Airwallex.client.post("#{resource_path}/validate", params)
+      symbolized_post("#{resource_path}/validate", params)
     end
 
     # Verify ownership of a beneficiary's bank account via Confirmation of
     # Payee (CoP) before creation.
     #
     # @param params [Hash] beneficiary bank account details to verify
-    # @return [Hash] raw verification result (status, account_name_match_result)
+    # @return [Hash] symbolized verification result (status, account_name_match_result)
     def self.verify_account(params = {})
-      Airwallex.client.post("#{resource_path}/verify_account", params)
+      symbolized_post("#{resource_path}/verify_account", params)
     end
 
     # Retrieve the API schema (field validation rules) for beneficiary bank
     # details, keyed by beneficiary type / entity type / bank country.
     #
     # @param params [Hash] e.g. beneficiary_type:, bank_country_code:
-    # @return [Hash] raw schema response
+    # @return [Hash] symbolized schema response
     def self.api_schema(params = {})
-      Airwallex.client.post(API_SCHEMA_PATH, params)
+      symbolized_post(API_SCHEMA_PATH, params)
     end
 
     # Retrieve the dynamic form schema used to render beneficiary bank-detail
     # forms in the UI, keyed by beneficiary type / entity type / bank country.
     #
     # @param params [Hash] e.g. beneficiary_type:, bank_country_code:
-    # @return [Hash] raw schema response
+    # @return [Hash] symbolized schema response
     def self.form_schema(params = {})
-      Airwallex.client.post(FORM_SCHEMA_PATH, params)
+      symbolized_post(FORM_SCHEMA_PATH, params)
     end
 
     # Search financial institutions supported for a given country, currency,
@@ -102,9 +102,9 @@ module Airwallex
     # @param params [Hash] required: bank_country_code:, account_currency:,
     #   entity_type:, transfer_method:, keyword: (a bank-name search term,
     #   min 3 chars)
-    # @return [Hash] raw response listing supported institutions
+    # @return [Hash] symbolized response listing supported institutions
     def self.supported_financial_institutions(params = {})
-      Airwallex.client.get(SUPPORTED_FINANCIAL_INSTITUTIONS_PATH, params)
+      symbolized_get(SUPPORTED_FINANCIAL_INSTITUTIONS_PATH, params)
     end
   end
 end

data/lib/airwallex/resources/billing_customer.rb

@@ -40,9 +40,9 @@ module Airwallex
     # Retrieve the bank transfer instructions for funding this customer's
     # subscriptions (e.g. for a BT-funded instalment plan).
     #
-    # @return [Hash] raw bank transfer instructions
+    # @return [Hash] symbolized bank transfer instructions
     def bank_transfer_instructions
-      Airwallex.client.get("#{self.class.resource_path}/#{id}/bank_transfer_instructions")
+      self.class.symbolized_get("#{self.class.resource_path}/#{id}/bank_transfer_instructions")
     end
   end
 end

data/lib/airwallex/resources/connected_account.rb

@@ -75,9 +75,9 @@ module Airwallex
     # authenticated as
     #
     # @param params [Hash] additional params
-    # @return [Hash] raw wallet info response
+    # @return [Hash] symbolized wallet info response
     def self.wallet_info(params = {})
-      Airwallex.client.get(WALLET_INFO_PATH, params)
+      symbolized_get(WALLET_INFO_PATH, params)
     end
 
     # The legal_entity_id needed by BillingCustomer.create's

data/lib/airwallex/resources/global_account.rb

@@ -45,9 +45,9 @@ module Airwallex
     # @param params [Hash] account_statement_type: (e.g. "AMAZON"),
     #   registration_info: { agreement:, registered_name:, registered_email:,
     #   registered_address: { address:, city:, state:, postcode:, country: } }
-    # @return [Hash] raw response (the generated letter/document reference)
+    # @return [Hash] symbolized response (the generated letter/document reference)
     def generate_statement_letter(params = {})
-      Airwallex.client.post("#{self.class.resource_path}/#{id}/generate_statement_letter", params)
+      self.class.symbolized_post("#{self.class.resource_path}/#{id}/generate_statement_letter", params)
     end
 
     # List inbound transactions (deposits) received into this account

data/lib/airwallex/util.rb

@@ -40,11 +40,14 @@ module Airwallex
       hash.transform_keys(&:to_sym)
     end
 
-    def deep_symbolize_keys(hash)
-      return hash unless hash.is_a?(Hash)
-
-      hash.each_with_object({}) do |(key, value), result|
-        result[key.to_sym] = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
+    def deep_symbolize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), result| result[k.to_sym] = deep_symbolize_keys(v) }
+      when Array
+        value.map { |v| deep_symbolize_keys(v) }
+      else
+        value
       end
     end
 

data/lib/airwallex/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airwallex
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -137,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Production-grade Ruby client for the Airwallex API