airwallex 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '018417ed2b3091ca1c5eafdf99df79c1a81be1d13ddda2524a917d2bc9a2c3ff'
-  data.tar.gz: 0abdb483ebe91136353cc77efb5023cb1d0a05b3fd986c8c3ba59750dfeccfdd
+  metadata.gz: f1288d75bff8a6f00a8c0dfffc318b6df1821cb26c945e062930de6035e83822
+  data.tar.gz: 5452a4a8aed172764129f05043646e9f074c1c9e62df84246ffe6ff575ba0140
 SHA512:
-  metadata.gz: 1b48a815ca9ca948b4695cfa28b12e70c5dc21a7c6ff37781d20fe0b2f219b12daf205ec997eaaf51eca19bce49d3ffd0fbb890773cd99f5573c4733680e1ec6
-  data.tar.gz: ff66015473fee32cd8ec4bd7cdbb03072b340111d1c354db181c07e0722c936d7b14565210eabd6583f8cd223be9f4c96889b1e329a79b41709ed4626b474427
+  metadata.gz: 02e3eea25661113f96af469d3154ede00aae144c671c42fcdf48d2e08d900c74ff2291b9b901ebc2b2072688b840d07d58f6b7eb21bd14aaf2c75d2e4625e6f2
+  data.tar.gz: 31bb06a6c4a99f4d433c63b5eb9e209e31deeec63dd3d98a516d259801530e874b66b70d4680d386eba0e569589a55e51c59640af3907fbade0e1da9171b6698

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-01
+
+### Added
+
+- `FundsSplitReversal` resource (`.create`, `.retrieve`, `.list`) for
+  `/api/v1/pa/funds_split_reversals`, which moves split funds back from a
+  connected account to the platform. `.list` takes the required `funds_split_id:`.
+  Partial reversals are allowed until the full split is reversed
+- `ConnectedAccountTransfer` resource (`.create`, `.retrieve`, `.list`) for
+  `/api/v1/connected_account_transfers`, which moves funds between the platform
+  and a connected account. Pass `headers: { "x-on-behalf-of" => ... }` to
+  debit a connected account instead of the platform
+- `Transfer.simulate_transition`, `Transfer#simulate_transition` and
+  `Transfer#cancel` accept `headers:`. A transfer created `x-on-behalf-of` a
+  connected account can only be found with that same header
+
+### Fixed
+
+- `FundsSplit` docs (README and class comment) now show the real create body:
+  `request_id`, `source_id`, `source_type: "PAYMENT_INTENT"`, `amount` (string),
+  `destination`, `auto_release`, `metadata`, with one split per destination.
+  The docs previously showed `payment_intent_id:` and `splits: [...]`
+- Documented that `funds_split.*` webhook payloads use `split_id` (not `id`)
+  and carry no `request_id`, and that the sandbox rejects a PROCESSING -> PAID
+  transfer transition (go through SENT)
+
 ## [0.10.0] - 2026-09-29
 
 ### Added

data/README.md

@@ -375,7 +375,7 @@ payment_source = Airwallex::PaymentSource.create(
 )
 ```
 
-### Scale (Connected Accounts, Funds Splits, Charges)
+### Scale (Connected Accounts, Funds Splits, Reversals, Connected Account Transfers, Charges)
 
 For platforms onboarding sub-merchants:
 
@@ -407,17 +407,56 @@ connected_account.submit
 Airwallex::ConnectedAccount.current
 Airwallex::ConnectedAccount.wallet_info
 
-# Split a charge's funds between the platform and a connected account
+# Split part of a PaymentIntent's funds to a connected account. One split per
+# destination: create several splits to pay several connected accounts.
+# A reused request_id raises BadRequestError (duplicate_request); splitting
+# more than the PaymentIntent amount raises amount_above_limit.
 split = Airwallex::FundsSplit.create(
-  payment_intent_id: payment_intent.id,
-  splits: [{ account_id: connected_account.id, amount: 10.00 }]
+  request_id: 'split-order-123',  # required, max 64
+  source_id: payment_intent.id,   # required
+  source_type: 'PAYMENT_INTENT',  # required
+  amount: '10.00',                # required, string
+  destination: connected_account.id,
+  auto_release: false,            # optional, default true
+  metadata: { order_id: '123' }   # optional
+)
+split.release # only needed when auto_release: false
+
+# Reverse split funds back to the platform. Partial reversals are allowed
+# until the full split is reversed. Statuses: CREATED, RELEASED, SETTLED
+reversal = Airwallex::FundsSplitReversal.create(
+  request_id: 'rev-order-123',    # required, max 64
+  funds_split_id: split.id,       # required
+  amount: '5.00',                 # required, string
+  metadata: { reason: 'refund' }  # optional
 )
-split.release
+Airwallex::FundsSplitReversal.retrieve(reversal.id)
+Airwallex::FundsSplitReversal.list(funds_split_id: split.id) # funds_split_id is required
+
+# Move funds between the platform and a connected account's wallet. Pass
+# x-on-behalf-of to debit a connected account instead of the platform.
+# Statuses: NEW, PENDING, SETTLED, SUSPENDED, FAILED
+cat = Airwallex::ConnectedAccountTransfer.create(
+  request_id: 'top-up-123',       # required, 1-50
+  amount: '100.00',
+  currency: 'AUD',
+  destination: connected_account.id,
+  reason: 'transfer_to_own_account',
+  reference: 'Ledger top-up'      # required, 1-140
+)
+Airwallex::ConnectedAccountTransfer.retrieve(cat.id)
+Airwallex::ConnectedAccountTransfer.list(destination: connected_account.id, status: 'SETTLED')
+
+# Pay out from a connected account: create the Transfer on its behalf
+Airwallex::Transfer.create(transfer_params, headers: { 'x-on-behalf-of' => connected_account.id })
 
 # Charges (create, retrieve, list)
 charge = Airwallex::Charge.retrieve('charge_id')
 ```
 
+`funds_split.*` webhook payloads name the split `split_id`, not `id`, and carry
+no `request_id`: `{ split_id, status, amount, currency, source_id, source_type, destination, ... }`.
+
 ### Requests for Information (RFIs)
 
 RFIs are compliance questions Airwallex raises against an account. They use
@@ -555,8 +594,18 @@ transfer.simulate_transition(next_status: 'FAILED', failure_type: 'INSUFFICIENT_
 
 # Class-level equivalent takes a transfer_id directly instead of an instance
 Airwallex::Transfer.simulate_transition('tfr_123', next_status: 'CANCELLED')
+
+# A transfer created x-on-behalf-of a connected account can only be found
+# with the same header (cancel takes it too)
+headers = { 'x-on-behalf-of' => 'acct_123' }
+transfer.simulate_transition(next_status: 'SENT', headers: headers)
+Airwallex::Transfer.simulate_transition('tfr_123', next_status: 'PAID', headers: headers)
+transfer.cancel(headers: headers)
 ```
 
+The sandbox rejects PROCESSING -> PAID with a 500 `operation_failed`. Move the
+transfer to SENT first.
+
 #### Connected Accounts & Offboarding
 
 ```ruby
@@ -746,6 +795,10 @@ begin
     handle_successful_payment(event.data)
   when 'payout.transfer.failed'
     handle_failed_payout(event.data)
+  when 'funds_split.settled'
+    # funds_split.* payloads identify the split by split_id (not id) and
+    # carry no request_id — see the Scale section
+    handle_settled_split(event.data)
   end
 rescue Airwallex::SignatureVerificationError => e
   # Invalid signature
@@ -849,7 +902,7 @@ end
   - Customer (create, retrieve, list, update, delete)
   - Dispute (retrieve, list, accept, challenge, related_payment_intents, simulate_create, simulate_escalate, simulate_resolve)
 - **Payouts**:
-  - Transfer (create, retrieve, list, cancel, simulate_transition)
+  - Transfer (create, retrieve, list, cancel, simulate_transition; cancel/simulate_transition take headers: for x-on-behalf-of)
   - Beneficiary (create, retrieve, list, update, delete, validate, verify_account, api_schema, form_schema, supported_financial_institutions)
   - BatchTransfer (create, retrieve, list)
 - **Foreign Exchange & Multi-Currency**:
@@ -876,6 +929,8 @@ end
   - AccountAmendment (create, retrieve, simulate_approve, simulate_reject) - requires Admin-level API key permissions
   - AccountOffboarding — sandbox Simulation only, scoped to a parent ConnectedAccount (simulate_complete, simulate_cancel)
   - FundsSplit (create, retrieve, list, release)
+  - FundsSplitReversal (create, retrieve, list)
+  - ConnectedAccountTransfer (create, retrieve, list)
   - Charge (create, retrieve, list)
 - **Issuing** (sandbox Simulation only — no live Card/Cardholder resources yet):
   - IssuingTransaction (simulate_create with single_phase, simulate_capture, simulate_reverse, simulate_refund, simulate_notify_three_ds)

data/lib/airwallex/resources/connected_account_transfer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Connected Account Transfer — moves funds between the platform
+  # account and a connected account's wallet. Send x-on-behalf-of to debit a
+  # connected account instead of the platform.
+  #
+  # Statuses: NEW, PENDING, SETTLED, SUSPENDED, FAILED. Create errors include
+  # insufficient_fund and request_id_duplicate.
+  #
+  # @example Fund a connected account from the platform
+  #   transfer = Airwallex::ConnectedAccountTransfer.create(
+  #     request_id: "cat-req-123",  # required, 1-50
+  #     amount: "100.00",
+  #     currency: "AUD",
+  #     destination: "acct_123",    # connected account id
+  #     reason: "transfer_to_own_account",
+  #     reference: "Ledger top-up"  # required, 1-140
+  #   )
+  #
+  # @example List settled transfers to an account
+  #   Airwallex::ConnectedAccountTransfer.list(destination: "acct_123", status: "SETTLED")
+  class ConnectedAccountTransfer < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for connected account transfers
+    def self.resource_path
+      "/api/v1/connected_account_transfers"
+    end
+  end
+end

data/lib/airwallex/resources/funds_split.rb

@@ -1,18 +1,32 @@
 # 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).
+  # Represents a Funds Split — moves part of a PaymentIntent's funds from the
+  # platform account to a Connected Account. Each split has exactly one
+  # destination; create one split per connected account.
+  #
+  # Create errors include duplicate_request (reused request_id) and
+  # amount_above_limit (splits exceed the PaymentIntent amount).
+  #
+  # funds_split.* webhook payloads name the split split_id, not id, and carry
+  # no request_id: { split_id:, status:, amount:, currency:, source_id:,
+  # source_type:, destination:, ... }.
   #
   # @example Create a split
   #   split = Airwallex::FundsSplit.create(
-  #     payment_intent_id: intent.id,
-  #     splits: [{ account_id: connected_account.id, amount: 50.00 }]
+  #     request_id: "split-req-123",   # required, max 64
+  #     source_id: intent.id,          # required, PaymentIntent id
+  #     source_type: "PAYMENT_INTENT", # required
+  #     amount: "50.00",               # required, string
+  #     destination: connected_account.id,
+  #     auto_release: true,            # optional, default true
+  #     metadata: { order_id: "123" }  # optional
   #   )
   #
-  # @example Release the split funds
+  # @example Release the split funds (when created with auto_release: false)
   #   split.release
+  #
+  # @see FundsSplitReversal to move split funds back to the platform
   class FundsSplit < APIResource
     extend APIOperations::Create
     extend APIOperations::Retrieve

data/lib/airwallex/resources/funds_split_reversal.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a Funds Split Reversal — moves previously split funds back from
+  # the connected account (the split's destination) to the platform account.
+  # Partial reversals are allowed until the full split amount is reversed.
+  #
+  # Statuses: CREATED, RELEASED, SETTLED.
+  #
+  # @example Reverse part of a split
+  #   reversal = Airwallex::FundsSplitReversal.create(
+  #     request_id: "rev-req-123",  # required, max 64
+  #     funds_split_id: split.id,   # required
+  #     amount: "5.00",             # required, string
+  #     metadata: { reason: "refund" }
+  #   )
+  #   reversal.status # => "CREATED"
+  #
+  # @example List the reversals of a split
+  #   Airwallex::FundsSplitReversal.list(funds_split_id: split.id)
+  class FundsSplitReversal < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for funds split reversals
+    def self.resource_path
+      "/api/v1/pa/funds_split_reversals"
+    end
+  end
+end

data/lib/airwallex/resources/transfer.rb

@@ -14,10 +14,14 @@ module Airwallex
     end
 
     # Cancel a pending transfer
-    def cancel
+    #
+    # @param opts [Hash] headers: (e.g. { "x-on-behalf-of" => account_id })
+    # @return [Transfer] self
+    def cancel(opts = {})
       response = Airwallex.client.post(
         "#{self.class.resource_path}/#{id}/cancel",
-        {}
+        {},
+        opts[:headers] || {}
       )
       refresh_from(response)
       self
@@ -25,18 +29,21 @@ module Airwallex
 
     # Simulate this transfer's status advancing one step. The standard
     # lifecycle is SCHEDULED -> PROCESSING -> SENT -> PAID, progressed one
-    # step at a time; OVERDUE, FAILED, and CANCELLED can be jumped to
-    # directly.
+    # step at a time (the sandbox rejects PROCESSING -> PAID with a 500
+    # operation_failed; go through SENT); OVERDUE, FAILED, and CANCELLED can
+    # be jumped to directly.
     #
     # @param next_status [String] one of "OVERDUE", "PROCESSING", "SENT",
     #   "PAID", "FAILED", "CANCELLED"
     # @param failure_type [String, nil] failure reason code, only
     #   meaningful when next_status is "FAILED"
+    # @param headers [Hash] e.g. { "x-on-behalf-of" => account_id } — required
+    #   for a transfer created on behalf of a connected account
     # @return [Transfer] self
-    def simulate_transition(next_status:, failure_type: nil)
+    def simulate_transition(next_status:, failure_type: nil, headers: {})
       params = { next_status: next_status }
       params[:failure_type] = failure_type if failure_type
-      response = Airwallex.client.post("#{SIMULATION_PATH}/#{id}/transition", params)
+      response = Airwallex.client.post("#{SIMULATION_PATH}/#{id}/transition", params, headers)
       refresh_from(response)
       self
     end
@@ -48,11 +55,13 @@ module Airwallex
     #   "PAID", "FAILED", "CANCELLED"
     # @param failure_type [String, nil] failure reason code, only
     #   meaningful when next_status is "FAILED"
+    # @param headers [Hash] e.g. { "x-on-behalf-of" => account_id } — required
+    #   for a transfer created on behalf of a connected account
     # @return [Transfer]
-    def self.simulate_transition(transfer_id, next_status:, failure_type: nil)
+    def self.simulate_transition(transfer_id, next_status:, failure_type: nil, headers: {})
       params = { next_status: next_status }
       params[:failure_type] = failure_type if failure_type
-      response = Airwallex.client.post("#{SIMULATION_PATH}/#{transfer_id}/transition", params)
+      response = Airwallex.client.post("#{SIMULATION_PATH}/#{transfer_id}/transition", params, headers)
       new(response)
     end
   end

data/lib/airwallex/version.rb

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

data/lib/airwallex.rb

@@ -47,6 +47,8 @@ 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/funds_split_reversal"
+require_relative "airwallex/resources/connected_account_transfer"
 require_relative "airwallex/resources/charge"
 require_relative "airwallex/resources/deposit"
 require_relative "airwallex/resources/issuing_transaction"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airwallex
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -93,11 +93,13 @@ files:
 - lib/airwallex/resources/cardholder.rb
 - lib/airwallex/resources/charge.rb
 - lib/airwallex/resources/connected_account.rb
+- lib/airwallex/resources/connected_account_transfer.rb
 - lib/airwallex/resources/conversion.rb
 - lib/airwallex/resources/customer.rb
 - lib/airwallex/resources/deposit.rb
 - lib/airwallex/resources/dispute.rb
 - lib/airwallex/resources/funds_split.rb
+- lib/airwallex/resources/funds_split_reversal.rb
 - lib/airwallex/resources/global_account.rb
 - lib/airwallex/resources/global_account_alias.rb
 - lib/airwallex/resources/global_account_mandate.rb
@@ -144,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Production-grade Ruby client for the Airwallex API