airwallex 0.6.0 → 0.7.0

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] raw response (the generated letter/document reference)
+    def generate_statement_letter(params = {})
+      Airwallex.client.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

data/lib/airwallex/resources/global_account_alias.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents an alias (e.g. PayID, email, or phone-linked VAN) attached to
+  # a GlobalAccount. Always accessed through its parent GlobalAccount, since
+  # its API path is scoped by global_account_id.
+  class GlobalAccountAlias < APIResource
+    # @param global_account_id [String] the parent GlobalAccount's id
+    # @return [String] API resource path for this account's aliases
+    def self.resource_path(global_account_id)
+      "/api/v1/global_accounts/#{global_account_id}/aliases"
+    end
+
+    # Begin porting this alias in from another provider
+    #
+    # @param params [Hash] additional porting params
+    # @return [GlobalAccountAlias] self
+    def initiate_port(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path(global_account_id)}/#{id}/initiate_port", params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Submit the verification code sent to confirm this alias
+    #
+    # @param params [Hash] e.g. code:
+    # @return [GlobalAccountAlias] self
+    def submit_verification_code(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path(global_account_id)}/#{id}/submit_verification_code", params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Request a new verification code for this alias
+    #
+    # @param params [Hash] additional params
+    # @return [GlobalAccountAlias] self
+    def request_new_verification_code(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path(global_account_id)}/#{id}/request_new_verification_code", params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Cancel this alias
+    #
+    # @param params [Hash] additional params
+    # @return [GlobalAccountAlias] self
+    def cancel(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path(global_account_id)}/#{id}/cancel", params
+      )
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/global_account_mandate.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a direct debit mandate on a GlobalAccount. Always accessed
+  # through its parent GlobalAccount, since its API path is scoped by
+  # global_account_id.
+  class GlobalAccountMandate < APIResource
+    # @param global_account_id [String] the parent GlobalAccount's id
+    # @return [String] API resource path for this account's mandates
+    def self.resource_path(global_account_id)
+      "/api/v1/global_accounts/#{global_account_id}/mandates"
+    end
+
+    # Cancel this mandate
+    #
+    # @param params [Hash] additional params
+    # @return [GlobalAccountMandate] self
+    def cancel(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path(global_account_id)}/#{id}/cancel", params
+      )
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/global_account_transaction.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Read-only representation of a single Global Account inbound transaction
+  class GlobalAccountTransaction < APIResource
+  end
+end

data/lib/airwallex/resources/payment_consent.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Payment Consent — a saved card/payment method authorized for
+  # future off-session charges without re-prompting the customer.
+  #
+  # Does NOT attach directly to a BillingSubscription — a subscription's
+  # payment_source_id references a PaymentSource (see Airwallex::PaymentSource),
+  # a separate Billing object created FROM a verified, merchant-initiated
+  # PaymentConsent. See PaymentSource's docstring for the full chain.
+  #
+  # @example Create and verify a consent for merchant-initiated (unscheduled) charges
+  #   # next_triggered_by/merchant_trigger_reason are required for the
+  #   # consent to later be usable to create a PaymentSource.
+  #   consent = Airwallex::PaymentConsent.create(
+  #     customer_id: customer.id,
+  #     payment_method: { type: "card", card: { ... } },
+  #     next_triggered_by: "merchant",
+  #     merchant_trigger_reason: "unscheduled"
+  #   )
+  #   consent.verify(payment_method: { card: { cvc: "123" } })
+  #
+  # @example Disable a consent
+  #   consent.disable
+  class PaymentConsent < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    # @return [String] API resource path for payment consents
+    def self.resource_path
+      "/api/v1/pa/payment_consents"
+    end
+
+    # Verify this consent (e.g. via a zero/low-value authorization) before
+    # it can be used for off-session charges
+    #
+    # @param params [Hash] verification params (e.g. payment_method details)
+    # @return [PaymentConsent] self
+    def verify(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/verify", params)
+      refresh_from(response)
+      self
+    end
+
+    # Continue a verification that requires further customer action
+    # (e.g. completing 3DS)
+    #
+    # @param params [Hash] continuation params
+    # @return [PaymentConsent] self
+    def verify_continue(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/verify_continue", params)
+      refresh_from(response)
+      self
+    end
+
+    # Disable this consent so it can no longer be charged
+    #
+    # @param params [Hash] additional params
+    # @return [PaymentConsent] self
+    def disable(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/disable", params)
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/payment_method.rb

@@ -6,6 +6,11 @@ module Airwallex
   # Payment methods allow you to store customer payment credentials securely
   # and reuse them for future payments without collecting details again.
   #
+  # Note: raw card tokenization via .create requires PCI-scoped "Native API"
+  # account access, which isn't enabled by default — if your account isn't
+  # provisioned for it, collect cards via Airwallex's hosted checkout or
+  # Embedded Elements instead.
+  #
   # @example Create a card payment method
   #   pm = Airwallex::PaymentMethod.create(
   #     type: "card",
@@ -26,24 +31,27 @@ module Airwallex
   #
   # @example Update billing details
   #   pm.update(billing: { address: { postal_code: "10001" } })
+  #
+  # @example Disable a payment method
+  #   pm.disable
   class PaymentMethod < APIResource
     extend APIOperations::Create
     extend APIOperations::Retrieve
     extend APIOperations::List
-    extend APIOperations::Update
     include APIOperations::Update
-    extend APIOperations::Delete
 
     # @return [String] API resource path for payment methods
     def self.resource_path
       "/api/v1/pa/payment_methods"
     end
 
-    # Detach this payment method from its customer
+    # Disable this payment method (Airwallex has no delete/detach endpoint;
+    # disabling is the real lifecycle operation and preserves history)
     #
+    # @param params [Hash] additional params
     # @return [PaymentMethod] self
-    def detach
-      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/detach", {})
+    def disable(params = {})
+      response = Airwallex.client.post("#{self.class.resource_path}/#{id}/disable", params)
       refresh_from(response)
       self
     end

data/lib/airwallex/resources/payment_source.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Billing Payment Source — the object a BillingSubscription's
+  # payment_source_id actually references. NOT the same object as
+  # PaymentConsent (/pa/payment_consents).
+  #
+  # external_id is the id of a PaymentMethod (/pa/payment_methods), not a
+  # PaymentConsent's own id. The PaymentConsent is still part of the flow —
+  # it's what authorizes that PaymentMethod for merchant-initiated
+  # (unscheduled) charges — but the id PaymentSource wants is the underlying
+  # PaymentMethod's.
+  #
+  # @example Full flow: PaymentMethod -> PaymentConsent -> PaymentSource -> BillingSubscription
+  #   payment_method = Airwallex::PaymentMethod.create(
+  #     customer_id: customer.id,
+  #     type: "card",
+  #     card: { ... } # a real test card in sandbox
+  #   )
+  #
+  #   consent = Airwallex::PaymentConsent.create(
+  #     customer_id: customer.id,
+  #     payment_method: { id: payment_method.id },
+  #     next_triggered_by: "merchant",
+  #     merchant_trigger_reason: "unscheduled"
+  #   )
+  #   consent.verify(...)
+  #
+  #   source = Airwallex::PaymentSource.create(
+  #     billing_customer_id: billing_customer.id,
+  #     external_id: payment_method.id,
+  #     linked_payment_account_id: connected_account.id
+  #   )
+  #
+  #   Airwallex::BillingSubscription.create(
+  #     billing_customer_id: billing_customer.id,
+  #     legal_entity_id: connected_account.legal_entity_id,
+  #     collection_method: "AUTO_CHARGE",
+  #     payment_source_id: source.id,
+  #     items: [{ price_id: price.id, quantity: 1 }]
+  #   )
+  class PaymentSource < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for billing payment sources
+    def self.resource_path
+      "/api/v1/billing/payment_sources"
+    end
+  end
+end

data/lib/airwallex/resources/quote.rb

@@ -3,14 +3,16 @@
 module Airwallex
   # Quote resource for locked exchange rates
   #
-  # Create quotes to lock exchange rates for a short period (typically 30-60 seconds).
-  # Use quotes to guarantee the rate when executing conversions.
+  # Create quotes to lock exchange rates for a period you choose (validity:
+  # MIN_1 through HR_24 — see .create). Use quotes to guarantee the rate when
+  # executing conversions.
   #
   # @example Create a quote
   #   quote = Airwallex::Quote.create(
   #     buy_currency: 'EUR',
   #     sell_currency: 'USD',
-  #     sell_amount: 1000.00
+  #     sell_amount: 1000.00,
+  #     validity: "MIN_1"
   #   )
   #   puts "Locked rate: #{quote.client_rate}, expires: #{quote.expires_at}"
   #

data/lib/airwallex/resources/rate.rb

@@ -10,15 +10,10 @@ module Airwallex
   #   rate = Airwallex::Rate.retrieve(buy_currency: 'EUR', sell_currency: 'USD')
   #   puts "1 USD = #{rate.client_rate} EUR"
   #
-  # @example Get multiple rates (Note: API may not support multiple at once)
-  #   rate = Airwallex::Rate.retrieve(
-  #     buy_currency: 'EUR',
-  #     sell_currency: 'USD'
-  #   )
-  #
+  # There is no .list — /fx/rates/current always returns the rate for one
+  # specific currency pair, not a collection.
   class Rate < APIResource
     extend APIOperations::Retrieve
-    extend APIOperations::List
 
     def self.resource_path
       "/api/v1/fx/rates/current"

data/lib/airwallex/version.rb

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

data/lib/airwallex.rb

@@ -26,6 +26,7 @@ require_relative "airwallex/resources/transfer"
 require_relative "airwallex/resources/beneficiary"
 require_relative "airwallex/resources/refund"
 require_relative "airwallex/resources/payment_method"
+require_relative "airwallex/resources/payment_consent"
 require_relative "airwallex/resources/customer"
 require_relative "airwallex/resources/batch_transfer"
 require_relative "airwallex/resources/dispute"
@@ -33,6 +34,20 @@ require_relative "airwallex/resources/rate"
 require_relative "airwallex/resources/quote"
 require_relative "airwallex/resources/conversion"
 require_relative "airwallex/resources/balance"
+require_relative "airwallex/resources/global_account"
+require_relative "airwallex/resources/global_account_transaction"
+require_relative "airwallex/resources/global_account_alias"
+require_relative "airwallex/resources/global_account_mandate"
+require_relative "airwallex/resources/billing_product"
+require_relative "airwallex/resources/billing_price"
+require_relative "airwallex/resources/billing_customer"
+require_relative "airwallex/resources/billing_subscription"
+require_relative "airwallex/resources/billing_subscription_item"
+require_relative "airwallex/resources/payment_source"
+require_relative "airwallex/resources/connected_account"
+require_relative "airwallex/resources/account_amendment"
+require_relative "airwallex/resources/funds_split"
+require_relative "airwallex/resources/charge"
 
 module Airwallex
   class << self