airwallex 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aff1a8f847f36f804c6ff9738480a8acd8e9aae867a9a3846311521337544c15
-  data.tar.gz: af199726a6f9cdcf4eef3d47c1ac1c24fd3ce92f9dd564c57730e75a8e4230ce
+  metadata.gz: fad10ff0adfb96f6cb5e3a88ec1825a17b840d73658bd6fb6813f18e2746fea1
+  data.tar.gz: 9f59e5dfc64382838c7b1485b4ca28b19e9b71248ea51070ff106ad33cb1af32
 SHA512:
-  metadata.gz: 41ddfe80904d71772a0ed87a6f6f26ff3f857b8502bfde57c6e8b42bd53a162d6235ac6ae99ca52a11f2e4688dbe0682a96806ec2e97f1e2e3f617c038766c45
-  data.tar.gz: 907a5e84b3a38f3b4664ccf41d5ac4d62e04804073034845dfd9503b880113f2bc32d8c365ca9cca96dd6870ac4ebc1283ca93da93fb59128789b001b556ef47
+  metadata.gz: de57501742d42048dd6a9286672c18050a17734ac2e21780f85e2d23e16e856bf406df20842352d55cd46aff22bfb0ade9676e1e6578865a7c966eba833880eb
+  data.tar.gz: 809fce3bea1462cecb398388b34863f65edf4ef00a5742ce0c30776c0dcbf942b474daef0551e64cd81b79ddb8a44fb01ef210fd2cec8470dbe844ce4f5968c6

data/CHANGELOG.md

@@ -1,15 +1,104 @@
 ## [Unreleased]
 
+## [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
+- `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
-- 38 new tests (278 total) covering FX and balance operations
+- 63 new tests (278 total) covering batch transfers, disputes, FX, and balance operations
 - Comprehensive manual test suite for regression testing
 
 ### Changed
@@ -19,13 +108,6 @@
 ### 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

@@ -319,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'

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/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,15 +21,11 @@ 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
-        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
@@ -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/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/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/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] raw validation result
+    def self.validate(params = {})
+      Airwallex.client.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)
+    def self.verify_account(params = {})
+      Airwallex.client.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
+    def self.api_schema(params = {})
+      Airwallex.client.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
+    def self.form_schema(params = {})
+      Airwallex.client.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] raw response listing supported institutions
+    def self.supported_financial_institutions(params = {})
+      Airwallex.client.get(SUPPORTED_FINANCIAL_INSTITUTIONS_PATH, params)
+    end
   end
 end

data/lib/airwallex/resources/billing_customer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Billing customer — the entity a BillingSubscription is
+  # scoped to. Distinct from Airwallex::Customer, which belongs to Payment
+  # Acceptance (/api/v1/pa/customers), not Billing.
+  #
+  # @example Create a billing customer
+  #   # Flat payload, no wrapper key (unlike Beneficiary/ConnectedAccount).
+  #   # type is "INDIVIDUAL" or "BUSINESS". default_legal_entity_id is not a
+  #   # separate resource — it's account_details.legal_entity_id from a
+  #   # ConnectedAccount's own retrieve response (see
+  #   # ConnectedAccount#legal_entity_id).
+  #   connected_account = Airwallex::ConnectedAccount.retrieve("acct_123")
+  #   billing_customer = Airwallex::BillingCustomer.create(
+  #     name: "Acme Corp",
+  #     email: "billing@acme.example",
+  #     type: "BUSINESS",
+  #     default_billing_currency: "AUD",
+  #     default_legal_entity_id: connected_account.legal_entity_id,
+  #     address: {
+  #       street: "200 Collins Street",
+  #       city: "Melbourne",
+  #       state: "VIC",
+  #       postcode: "3000",
+  #       country_code: "AU"
+  #     }
+  #   )
+  class BillingCustomer < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for billing customers
+    def self.resource_path
+      "/api/v1/billing/billing_customers"
+    end
+
+    # 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
+    def bank_transfer_instructions
+      Airwallex.client.get("#{self.class.resource_path}/#{id}/bank_transfer_instructions")
+    end
+  end
+end

data/lib/airwallex/resources/billing_price.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Billing price — the amount/currency/cadence attached to a
+  # BillingProduct that a BillingSubscription is created against.
+  #
+  # @example Create a simple per-unit recurring price
+  #   # Flat payload, no wrapper key. pricing_model is required (PER_UNIT /
+  #   # FLAT / GRADUATED / VOLUME — GRADUATED uses tiers: instead of
+  #   # unit_amount:). recurring: is what makes a price usable for a
+  #   # subscription.
+  #   price = Airwallex::BillingPrice.create(
+  #     product_id: product.id,
+  #     currency: "AUD",
+  #     pricing_model: "PER_UNIT",
+  #     unit_amount: 250.00,
+  #     recurring: { period: 1, period_unit: "MONTH" }
+  #   )
+  class BillingPrice < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for billing prices
+    def self.resource_path
+      "/api/v1/billing/prices"
+    end
+  end
+end

data/lib/airwallex/resources/billing_product.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Billing product — the thing being sold on a subscription
+  # (distinct from Payment Acceptance's Customer/PaymentMethod resources).
+  #
+  # @example Create a product
+  #   product = Airwallex::BillingProduct.create(name: "Instalment Plan")
+  #
+  # @example Update a product
+  #   product.update(name: "Instalment Plan (v2)")
+  class BillingProduct < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for billing products
+    def self.resource_path
+      "/api/v1/billing/products"
+    end
+  end
+end

data/lib/airwallex/resources/billing_subscription.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Billing subscription, e.g. a multi-part instalment plan.
+  #
+  # @example Create a subscription with a deferred start date
+  #   # Flat payload, no wrapper key. Prices attach via an items: array of
+  #   # { price_id:, quantity: }, not a flat price_id. legal_entity_id comes
+  #   # from ConnectedAccount#legal_entity_id, not a separate resource.
+  #   # payment_source_id references a PaymentSource (see
+  #   # Airwallex::PaymentSource for the full consent -> source -> subscription
+  #   # chain), not a PaymentConsent directly.
+  #   connected_account = Airwallex::ConnectedAccount.retrieve("acct_123")
+  #   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 }]
+  #   )
+  #   subscription.status #=> "PENDING"
+  #
+  # @example Cancel a subscription
+  #   subscription.cancel
+  class BillingSubscription < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for billing subscriptions
+    def self.resource_path
+      "/api/v1/billing/subscriptions"
+    end
+
+    # Cancel this subscription
+    #
+    # @param params [Hash] additional cancellation params
+    # @return [BillingSubscription] self
+    def cancel(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/cancel", params)
+      refresh_from(response)
+      self
+    end
+
+    # List the line items on this subscription
+    #
+    # @param params [Hash] additional query params (e.g. pagination)
+    # @return [ListObject<BillingSubscriptionItem>] list of subscription items
+    def items(params = {})
+      response = Airwallex.client.get("#{self.class.resource_path}/#{id}/items", params)
+
+      ListObject.new(
+        data: extract_item_rows(response),
+        has_more: extract_has_more(response),
+        next_cursor: extract_next_cursor(response),
+        resource_class: BillingSubscriptionItem,
+        params: params
+      )
+    end
+
+    # Retrieve a single line item on this subscription
+    #
+    # @param item_id [String] the subscription item id
+    # @return [BillingSubscriptionItem]
+    def item(item_id)
+      response = Airwallex.client.get("#{self.class.resource_path}/#{id}/items/#{item_id}")
+      BillingSubscriptionItem.new(response)
+    end
+
+    private
+
+    def extract_item_rows(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

data/lib/airwallex/resources/billing_subscription_item.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Read-only representation of a single Billing subscription line item
+  class BillingSubscriptionItem < APIResource
+  end
+end