airwallex 0.6.0 → 0.8.0

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] symbolized bank transfer instructions
+    def bank_transfer_instructions
+      self.class.symbolized_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

data/lib/airwallex/resources/charge.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Charge (Scale product) — funds attributed to a Connected
+  # Account, tracked before payout.
+  #
+  # @example Retrieve a charge
+  #   charge = Airwallex::Charge.retrieve("chg_123")
+  class Charge < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for charges
+    def self.resource_path
+      "/api/v1/charges"
+    end
+  end
+end

data/lib/airwallex/resources/connected_account.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Connected Account (Scale product) — a sub-account container
+  # used to onboard and track funds for a platform's connected entities.
+  #
+  # @example Create a connected account (business entity)
+  #   # account_details is a required top-level wrapper. customer_agreements,
+  #   # nickname, and primary_contact are top-level siblings, not nested
+  #   # inside it. legal_entity_type is "BUSINESS" or "INDIVIDUAL", not
+  #   # "COMPANY" (business_structure below is the field that uses "COMPANY").
+  #   # This is a minimal subset of Airwallex's real KYB schema — the full
+  #   # schema also supports trustee entities and much more optional detail
+  #   # (identity documents, store details, business person details, etc).
+  #   account = Airwallex::ConnectedAccount.create(
+  #     nickname: "Acme Advertiser",
+  #     primary_contact: { email: "contact@acme.example" },
+  #     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: "Acme Corp",
+  #         business_structure: "COMPANY",
+  #         business_address: {
+  #           address_line1: "200 Collins Street",
+  #           country_code: "AU",
+  #           postcode: "3000",
+  #           state: "VIC",
+  #           suburb: "Melbourne"
+  #         }
+  #       }
+  #     }
+  #   )
+  #
+  # @example Trigger KYC/KYB verification
+  #   account.submit
+  #
+  # @example Look up whichever account you're currently authenticated as
+  #   Airwallex::ConnectedAccount.current
+  #
+  # @example Get the legal_entity_id needed by BillingCustomer/BillingSubscription
+  #   account = Airwallex::ConnectedAccount.retrieve("acct_123")
+  #   account.legal_entity_id
+  class ConnectedAccount < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # Not nested under /accounts/{id} — these endpoints are implicitly
+    # scoped to whichever account the request is authenticated as (the
+    # platform's own account, or a connected account via x-on-behalf-of).
+    CURRENT_ACCOUNT_PATH = "/api/v1/account"
+    WALLET_INFO_PATH = "/api/v1/account/wallet_info"
+
+    # @return [String] API resource path for connected accounts
+    def self.resource_path
+      "/api/v1/accounts"
+    end
+
+    # Retrieve whichever account the current request is authenticated as
+    #
+    # @param params [Hash] additional params
+    # @return [ConnectedAccount]
+    def self.current(params = {})
+      response = Airwallex.client.get(CURRENT_ACCOUNT_PATH, params)
+      new(response)
+    end
+
+    # Retrieve wallet info for whichever account the current request is
+    # authenticated as
+    #
+    # @param params [Hash] additional params
+    # @return [Hash] symbolized wallet info response
+    def self.wallet_info(params = {})
+      symbolized_get(WALLET_INFO_PATH, params)
+    end
+
+    # The legal_entity_id needed by BillingCustomer.create's
+    # default_legal_entity_id and BillingSubscription.create's
+    # legal_entity_id — nested inside account_details on this account's own
+    # response, not a separate resource.
+    #
+    # @return [String, nil]
+    def legal_entity_id
+      attributes.dig(:account_details, :legal_entity_id)
+    end
+
+    # Submit the account for KYC/KYB verification
+    #
+    # @param params [Hash] additional submission params
+    # @return [ConnectedAccount] self
+    def submit(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/submit", params)
+      refresh_from(response)
+      self
+    end
+
+    # Agree to Airwallex's terms and conditions on behalf of this account
+    #
+    # @param params [Hash] e.g. agreed_at:, service_agreement_type:,
+    #   device_data: { ip_address:, user_agent: }
+    # @return [ConnectedAccount] self
+    def agree_to_terms_and_conditions(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path}/#{id}/terms_and_conditions/agree", params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Suspend this account
+    #
+    # @param params [Hash] e.g. message: "reason for suspension"
+    # @return [ConnectedAccount] self
+    def suspend(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/suspend", params)
+      refresh_from(response)
+      self
+    end
+
+    # Reactivate a suspended account
+    #
+    # @param params [Hash] e.g. message: "reason for reactivation"
+    # @return [ConnectedAccount] self
+    def reactivate(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/reactivate", params)
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/conversion.rb

@@ -37,7 +37,7 @@ module Airwallex
     extend APIOperations::List
 
     def self.resource_path
-      "/api/v1/conversions"
+      "/api/v1/fx/conversions"
     end
   end
 end

data/lib/airwallex/resources/customer.rb

@@ -7,11 +7,15 @@ module Airwallex
   # for individual users or accounts.
   #
   # @example Create a customer
+  #   # merchant_customer_id is required — your own reference id for this
+  #   # customer. request_id is optional (the gem's Idempotency middleware
+  #   # injects one automatically).
   #   customer = Airwallex::Customer.create(
+  #     merchant_customer_id: SecureRandom.uuid,
   #     email: "john@example.com",
   #     first_name: "John",
   #     last_name: "Doe",
-  #     metadata: { internal_id: "user_789" }
+  #     phone_number: "+1 1234567890"
   #   )
   #
   # @example List payment methods for a customer
@@ -20,7 +24,6 @@ module Airwallex
     extend APIOperations::Create
     extend APIOperations::Retrieve
     extend APIOperations::List
-    extend APIOperations::Update
     include APIOperations::Update
     extend APIOperations::Delete
 

data/lib/airwallex/resources/dispute.rb

@@ -4,7 +4,8 @@ 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.
+  # Merchants can view disputes, challenge them with evidence, or accept them.
+  # There is no create — disputes originate from card networks/issuing banks.
   #
   # @example List open disputes
   #   disputes = Airwallex::Dispute.list(status: 'OPEN')
@@ -12,57 +13,76 @@ module Airwallex
   # @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
   #
+  # @example Challenge a dispute
+  #   dispute.challenge(...)
   class Dispute < APIResource
     extend APIOperations::Retrieve
     extend APIOperations::List
+    include APIOperations::Update
 
     def self.resource_path
-      "/api/v1/disputes"
+      "/api/v1/pa/payment_disputes"
     end
 
     # Accept a dispute without challenging it
     #
-    # @return [Airwallex::Dispute] The updated dispute object
+    # @return [Airwallex::Dispute] self
     def accept
-      response = Airwallex.client.post("#{resource_path}/#{id}/accept", {})
+      response = Airwallex.client.post("#{self.class.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
+    # Challenge a dispute with evidence
     #
-    # @return [Airwallex::Dispute] The updated dispute object
-    def submit_evidence(evidence)
-      response = Airwallex.client.post("#{resource_path}/#{id}/evidence", evidence)
+    # @param params [Hash] challenge params — exact shape unconfirmed, pass
+    #   through whatever Airwallex's challenge schema requires
+    # @return [Airwallex::Dispute] self
+    def challenge(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/challenge", params)
       refresh_from(response)
       self
     end
 
+    # List payment intents related to this dispute
+    #
+    # @param params [Hash] additional query params (e.g. pagination)
+    # @return [ListObject<PaymentIntent>]
+    def related_payment_intents(params = {})
+      response = Airwallex.client.get(
+        "#{self.class.resource_path}/#{id}/related_payment_intents", params
+      )
+
+      ListObject.new(
+        data: extract_items(response),
+        has_more: extract_has_more(response),
+        next_cursor: extract_next_cursor(response),
+        resource_class: PaymentIntent,
+        params: params
+      )
+    end
+
     private
 
-    def resource_path
-      self.class.resource_path
+    def extract_items(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/funds_split.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Funds Split — how a single PaymentIntent/inbound transaction
+  # is divided between the platform and a Connected Account at collection
+  # time (the Scale-product mechanism for splitting deposits).
+  #
+  # @example Create a split
+  #   split = Airwallex::FundsSplit.create(
+  #     payment_intent_id: intent.id,
+  #     splits: [{ account_id: connected_account.id, amount: 50.00 }]
+  #   )
+  #
+  # @example Release the split funds
+  #   split.release
+  class FundsSplit < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for funds splits
+    def self.resource_path
+      "/api/v1/pa/funds_splits"
+    end
+
+    # Release this funds split (make the split amount available to the
+    # connected account)
+    #
+    # @param params [Hash] additional params
+    # @return [FundsSplit] self
+    def release(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/release", params)
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/global_account.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Global Account (Virtual Account Number) used to collect
+  # local bank transfers into a specific currency and jurisdiction.
+  #
+  # @example Provision a VAN
+  #   account = Airwallex::GlobalAccount.create(
+  #     country_code: "AU",
+  #     nick_name: "booking_12345",
+  #     required_features: [{ transfer_method: "LOCAL" }]
+  #   )
+  #
+  # @example Reconcile inbound deposits
+  #   account.transactions.each { |txn| puts "#{txn.amount} from #{txn.remitter}" }
+  #
+  # @example 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")
+  class GlobalAccount < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for global accounts
+    def self.resource_path
+      "/api/v1/global_accounts"
+    end
+
+    # Close this global account
+    #
+    # @param params [Hash] additional closure params
+    # @return [GlobalAccount] self
+    def close(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/close", params)
+      refresh_from(response)
+      self
+    end
+
+    # Generate a bank-ownership statement letter for this account — e.g. for
+    # marketplace seller verification (known value: "AMAZON"; other
+    # marketplace-specific values likely exist).
+    #
+    # @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] symbolized response (the generated letter/document reference)
+    def 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
+    #
+    # @param params [Hash] additional query params (e.g. pagination)
+    # @return [ListObject<GlobalAccountTransaction>] list of transactions
+    def transactions(params = {})
+      response = Airwallex.client.get("#{self.class.resource_path}/#{id}/transactions", params)
+      build_list(response, GlobalAccountTransaction, params)
+    end
+
+    # Create an alias (e.g. PayID, email, or phone-linked VAN) on this account
+    #
+    # @param params [Hash] alias attributes
+    # @return [GlobalAccountAlias]
+    def create_alias(params = {})
+      response = Airwallex.client.post("#{GlobalAccountAlias.resource_path(id)}/create", params)
+      GlobalAccountAlias.new(response)
+    end
+
+    # Retrieve a single alias on this account
+    #
+    # @param alias_id [String]
+    # @return [GlobalAccountAlias]
+    def alias(alias_id)
+      response = Airwallex.client.get("#{GlobalAccountAlias.resource_path(id)}/#{alias_id}")
+      GlobalAccountAlias.new(response)
+    end
+
+    # List aliases on this account
+    #
+    # @param params [Hash] additional query params (e.g. pagination)
+    # @return [ListObject<GlobalAccountAlias>] list of aliases
+    def aliases(params = {})
+      response = Airwallex.client.get(GlobalAccountAlias.resource_path(id), params)
+      build_list(response, GlobalAccountAlias, params)
+    end
+
+    # Retrieve a single direct debit mandate on this account
+    #
+    # @param mandate_id [String]
+    # @return [GlobalAccountMandate]
+    def mandate(mandate_id)
+      response = Airwallex.client.get("#{GlobalAccountMandate.resource_path(id)}/#{mandate_id}")
+      GlobalAccountMandate.new(response)
+    end
+
+    # List direct debit mandates on this account
+    #
+    # @param params [Hash] additional query params (e.g. pagination)
+    # @return [ListObject<GlobalAccountMandate>] list of mandates
+    def mandates(params = {})
+      response = Airwallex.client.get(GlobalAccountMandate.resource_path(id), params)
+      build_list(response, GlobalAccountMandate, params)
+    end
+
+    private
+
+    def build_list(response, resource_class, params)
+      ListObject.new(
+        data: extract_items(response),
+        has_more: extract_has_more(response),
+        next_cursor: extract_next_cursor(response),
+        resource_class: resource_class,
+        params: params
+      )
+    end
+
+    def extract_items(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