airwallex 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec7542a0e82153bbd60acceadb071eba2d48d328d89fa34d72d8a23dc30aeb45
-  data.tar.gz: b14a15b3b70878c6291bc6ffd447ccf81d4cab5d86e61b806cc0708bd70590e2
+  metadata.gz: be0adbfbafc982fa5c899a9df4230e9c65a68e46d2e7eb248b981e41ccc23bd4
+  data.tar.gz: 599bdc078288f934cc5f8b06fced1668605c8e2e6af4763d943a9f227a32e563
 SHA512:
-  metadata.gz: 1e401e23580f1347cbf2caae60b985138c59e73a22ba758578c7ffd99b2318859f766e7c0e0a13f55bff4da29a6796029a359a12a9c1db32b213c972244e70a3
-  data.tar.gz: b7779fbdc8227ae72d20eda510799bb6898edb43c74d7aa6a6a30b7110f304be96b2e17673b02e832c2a9638c48f987b6ecf54027fc4b18f754d218fbaec4398
+  metadata.gz: 4cd20d177f642d64bdb07922f673483ab3d86499c0a938c8a7db7854f06fd5dff86b10326c09496dbf9a0bc8099a64834fc0ee4a56ff91d822dd721aff911e7a
+  data.tar.gz: 56b071c9ff52ccf48f6526c6f3a8264d55c1d8cfcc5794d869894535baf7685c7642bdebf498f5c4ed01e362631f62a9721d4151bc6f860cf91b574a2a2d54b7

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 ## [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
+- GlobalAccount resource (create, retrieve, list, update, `#close`, `#generate_statement_letter`,
+  `#transactions`)
+  - GlobalAccountAlias nested resource (`#create_alias`, `#alias`, `#aliases`, `#initiate_port`,
+    `#submit_verification_code`, `#request_new_verification_code`, `#cancel`)
+  - GlobalAccountMandate nested resource (`#mandate`, `#mandates`, `#cancel`)
+- Billing resources: BillingCustomer, BillingProduct, BillingPrice, BillingSubscription (with `#items`/`#item`)
+- PaymentConsent resource (create, retrieve, list, update, `#verify`, `#verify_continue`, `#disable`)
+- PaymentSource resource (create, retrieve, list)
+- ConnectedAccount resource (create, retrieve, list, update, `#submit`, `#agree_to_terms_and_conditions`,
+  `#suspend`, `#reactivate`, `.current`, `.wallet_info`, `#legal_entity_id`)
+- AccountAmendment resource (create, retrieve)
+- FundsSplit resource (create, retrieve, list, `#release`)
+- Charge resource (create, retrieve, list)
+- Beneficiary gained `.update`/`#update`, `.validate`, `.verify_account`, `.api_schema`, `.form_schema`, and
+  `.supported_financial_institutions`
+- Dispute gained `.update`, `#challenge` (replacing `#submit_evidence`), and `#related_payment_intents`
+- PaymentMethod gained `#disable`
+- New tests covering all of the above (378 total)
+
+### Fixed
+- `APIOperations::Update` now sends `POST #{resource_path}/{id}/update` instead of `PUT #{resource_path}/{id}`
+- `APIOperations::Delete` now sends `POST #{resource_path}/{id}/delete` instead of `DELETE #{resource_path}/{id}`,
+  and checks the response instead of always returning `true`
+- `Dispute`'s resource path corrected from `/api/v1/disputes` to `/api/v1/pa/payment_disputes`
+- `Conversion`'s resource path corrected from `/api/v1/conversions` to `/api/v1/fx/conversions`
+- `Configuration#api_version` now defaults to `nil` instead of a hardcoded date, and `x-api-version` is only
+  sent when explicitly set
+- `Beneficiary.create`/`.validate`/`.update` payloads corrected: wrapped under a top-level `beneficiary` key,
+  with `nickname`/`payer_entity_type`/`transfer_methods`/`transfer_reason` as top-level siblings;
+  `entity_type` replaces the nonexistent `beneficiary_type`
+- `Beneficiary#update`/`.update` requires the full payload, not a partial patch
+- `Beneficiary.supported_financial_institutions` requires `account_currency`, `entity_type`,
+  `transfer_method`, and `keyword` in addition to `bank_country_code`
+- `Customer.create` requires `merchant_customer_id`
+- `GlobalAccount#generate_statement_letter` requires `account_statement_type` and `registration_info`
+- `ConnectedAccount.create` payload corrected: `account_details` is a required top-level wrapper;
+  `legal_entity_type` is `"BUSINESS"`/`"INDIVIDUAL"`, not `"COMPANY"`
+- `BillingCustomer.create` payload corrected to match the real flat schema (`name`/`email`/`type`/
+  `default_billing_currency`/`address`/`default_legal_entity_id`)
+- `BillingPrice.create` requires `pricing_model` and `recurring`
+- `BillingSubscription.create` payload corrected: prices attach via an `items:` array, not a flat
+  `price_id`; `starts_at` replaces `start_date`; added `legal_entity_id` and `payment_source_id`
+- `AccountAmendment.create` payload corrected to use `target` plus the changed section as a top-level
+  sibling, not a generic `changes:` wrapper
+- `PaymentSource.create`'s `external_id` corrected to reference a `PaymentMethod` id, not a `PaymentConsent` id
+- `ConnectedAccount#legal_entity_id` added as the source for `BillingCustomer`/`BillingSubscription`'s
+  `legal_entity_id`, rather than a separate resource
+- `Rate`/`Quote` use `sell_currency`/`buy_currency`, not `from_currency`/`to_currency`
+- `Quote.create` requires `validity` (`MIN_1`, `MIN_15`, `MIN_30`, `HR_1`, `HR_4`, `HR_8`, or `HR_24`)
+
+### Removed
+- `Rate.list` — the endpoint has no "list all rates" concept, only `.retrieve(sell_currency:, buy_currency:)`
+- `PaymentMethod.delete` and `PaymentMethod#detach` — replaced by `#disable`, the real lifecycle operation
+
 ## [0.6.0] - 2026-08-28
 
 ### Fixed

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_operations/delete.rb

@@ -4,12 +4,12 @@ module Airwallex
   module APIOperations
     module Delete
       def delete(id, opts = {})
-        Airwallex.client.delete(
-          "#{resource_path}/#{id}",
+        response = Airwallex.client.post(
+          "#{resource_path}/#{id}/delete",
           {},
           opts[:headers] || {}
         )
-        true
+        response == true
       end
     end
   end

data/lib/airwallex/api_operations/update.rb

@@ -9,8 +9,8 @@ module Airwallex
 
       module ClassMethods
         def update(id, params = {}, opts = {})
-          response = Airwallex.client.put(
-            "#{resource_path}/#{id}",
+          response = Airwallex.client.post(
+            "#{resource_path}/#{id}/update",
             params,
             opts[:headers] || {}
           )
@@ -20,8 +20,8 @@ module Airwallex
 
       # Instance methods
       def update(params = {})
-        response = Airwallex.client.put(
-          "#{self.class.resource_path}/#{id}",
+        response = Airwallex.client.post(
+          "#{self.class.resource_path}/#{id}/update",
           params
         )
         refresh_from(response)

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/client.rb

@@ -25,7 +25,7 @@ module Airwallex
 
         conn.headers["Content-Type"] = "application/json"
         conn.headers["User-Agent"] = user_agent
-        conn.headers["x-api-version"] = config.api_version
+        conn.headers["x-api-version"] = config.api_version if config.api_version
 
         conn.adapter Faraday.default_adapter
       end

data/lib/airwallex/configuration.rb

@@ -10,12 +10,16 @@ module Airwallex
     SANDBOX_FILES_URL = "https://files-demo.airwallex.com"
     PRODUCTION_FILES_URL = "https://files.airwallex.com"
 
-    DEFAULT_API_VERSION = "2024-09-27"
     VALID_ENVIRONMENTS = %i[sandbox production].freeze
 
+    # api_version is nil by default. Airwallex stores a version on your
+    # account and applies it automatically; the x-api-version header is only
+    # for exceptional per-call overrides (testing/migrating), not a
+    # permanent pin — see https://www.airwallex.com/docs/api/versioning.
+    # Set this explicitly if you want reproducible, pinned behavior instead.
     def initialize
       @environment = :sandbox
-      @api_version = DEFAULT_API_VERSION
+      @api_version = nil
       @log_level = :info
     end
 

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/account_amendment.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents an amendment to whichever account the request is
+  # authenticated as (the platform's own account, or a connected account via
+  # x-on-behalf-of). Not nested under /accounts/{id} — scoped implicitly by
+  # auth context, same as ConnectedAccount.current.
+  #
+  # .create requires Admin-level API key permissions, a separate tier from
+  # the normal per-resource Read/Write scopes.
+  #
+  # @example Submit an amendment
+  #   # `target` identifies the dotted path being amended; the changed
+  #   # section is a top-level sibling keyed by its own name (e.g.
+  #   # store_details), not wrapped in a generic "changes" key.
+  #   amendment = Airwallex::AccountAmendment.create(
+  #     target: "account_details.store_details",
+  #     store_details: { store_name: "New Store Name" }
+  #   )
+  class AccountAmendment < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+
+    # @return [String] API resource path for account amendments
+    def self.resource_path
+      "/api/v1/account/amendments"
+    end
+  end
+end

data/lib/airwallex/resources/beneficiary.rb

@@ -1,14 +1,110 @@
 # frozen_string_literal: true
 
 module Airwallex
+  # @example Create a beneficiary
+  #   # nickname/payer_entity_type/transfer_methods are top-level siblings of
+  #   # `beneficiary`, not nested inside it. request_id is optional (the
+  #   # gem's Idempotency middleware injects one automatically). Call
+  #   # .api_schema / .form_schema for the exact required fields per
+  #   # entity_type + bank_country_code.
+  #   beneficiary = Airwallex::Beneficiary.create(
+  #     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" # country-specific enum
+  #       }
+  #     }
+  #   )
+  #
+  # @example Update a beneficiary
+  #   # .update doesn't support a partial patch — resend the full payload
+  #   # with your change merged in.
+  #   beneficiary.update(
+  #     transfer_methods: ["LOCAL"],
+  #     beneficiary: {
+  #       entity_type: "COMPANY",
+  #       company_name: "Acme Corp Ltd",
+  #       bank_details: { account_currency: "AUD", bank_country_code: "AU", ... }
+  #     }
+  #   )
   class Beneficiary < APIResource
     extend APIOperations::Create
     extend APIOperations::Retrieve
     extend APIOperations::List
     extend APIOperations::Delete
+    include APIOperations::Update
+
+    API_SCHEMA_PATH = "/api/v1/beneficiary_api_schemas/generate"
+    FORM_SCHEMA_PATH = "/api/v1/beneficiary_form_schemas/generate"
+    SUPPORTED_FINANCIAL_INSTITUTIONS_PATH = "/api/v1/beneficiary_form_schemas/supported_financial_institutions"
 
     def self.resource_path
       "/api/v1/beneficiaries"
     end
+
+    # Validate beneficiary details (address, bank details, entity type, transfer
+    # method) before attempting to create the beneficiary.
+    #
+    # @param params [Hash] the same shape of params you'd pass to .create
+    # @return [Hash] symbolized validation result
+    def self.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] symbolized verification result (status, account_name_match_result)
+    def self.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] symbolized schema response
+    def self.api_schema(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] symbolized schema response
+    def self.form_schema(params = {})
+      symbolized_post(FORM_SCHEMA_PATH, params)
+    end
+
+    # Search financial institutions supported for a given country, currency,
+    # entity type, and transfer method, by name keyword.
+    #
+    # @param params [Hash] required: bank_country_code:, account_currency:,
+    #   entity_type:, transfer_method:, keyword: (a bank-name search term,
+    #   min 3 chars)
+    # @return [Hash] symbolized response listing supported institutions
+    def self.supported_financial_institutions(params = {})
+      symbolized_get(SUPPORTED_FINANCIAL_INSTITUTIONS_PATH, params)
+    end
   end
 end