airwallex 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '018417ed2b3091ca1c5eafdf99df79c1a81be1d13ddda2524a917d2bc9a2c3ff'
-  data.tar.gz: 0abdb483ebe91136353cc77efb5023cb1d0a05b3fd986c8c3ba59750dfeccfdd
+  metadata.gz: 20abbd73aa43d82620559c0f067a6236619d3dad597b778b41b75af6d87fb225
+  data.tar.gz: 6a477ebe40ec72d267d42f9b98669d783dd7db32c9cf9d30ed0b671c07810252
 SHA512:
-  metadata.gz: 1b48a815ca9ca948b4695cfa28b12e70c5dc21a7c6ff37781d20fe0b2f219b12daf205ec997eaaf51eca19bce49d3ffd0fbb890773cd99f5573c4733680e1ec6
-  data.tar.gz: ff66015473fee32cd8ec4bd7cdbb03072b340111d1c354db181c07e0722c936d7b14565210eabd6583f8cd223be9f4c96889b1e329a79b41709ed4626b474427
+  metadata.gz: ac0aa15ebc45b61bbd7004010bbdfc261c1243d373cbd59b4dbb141e680b0d46ca079ab25f2d4c4e9017f5d4a4730fff4950f632e5415c82de0728cd3e3837b8
+  data.tar.gz: 948df17c305f0ab1c88791b29afe1df2218197c12512cbb52c7f80cb0524c9e1903a7e4b1b25597c2ed447d010fed846df94e48ec988ccdf85019913318fa561

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-06
+
+### Added
+
+- `RFI.respond(rfi_id, params, opts)` and `RFI#respond(params, opts)` for
+  `POST /api/v1/rfis/{id}/respond`. Params are sent as-is
+  (`questions: [{ id:, answer: { type:, ... } }]`) and take `headers:` for
+  `x-on-behalf-of`. No `request_id` is added to this body, because the
+  endpoint doesn't document one
+- `UploadedFile.upload(io, filename:, content_type:, notes: nil, opts: {})` for
+  `POST /api/v1/files/upload` on the files host (`config.files_url`). It sends
+  multipart/form-data with `file` and optional `notes` form fields, and
+  returns an `UploadedFile` with `#file_id` (`#id` mirrors it)
+- `Client#files_connection` and `Client#upload`: a separate connection to the
+  files host with no JSON Content-Type default, no JSON encoding, no
+  Idempotency middleware, and no logging of request bodies
+
+### Fixed
+
+- `AuthRefresh` now re-sends the original request body when it retries after
+  a 401. It previously re-sent the parsed 401 response body, so any POST that
+  hit an expired token was retried with the wrong body. Multipart stream
+  bodies are rewound before the retry
+- With `config.logger` set, the logger no longer writes credentials: the
+  `x-api-key` header, the `Authorization` bearer token, and the `token` in the
+  login response are logged as `[FILTERED]`. They were previously logged in
+  plain text
+
+## [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

@@ -16,7 +16,7 @@ This gem provides a Ruby interface to Airwallex's payment infrastructure, design
 - **Billing**: Products, prices, billing customers, and subscriptions for recurring/instalment billing
 - **Recurring Payments**: Payment consents and payment sources for merchant-initiated (off-session) charges
 - **Scale**: Connected accounts, funds splits, and charges for platforms onboarding sub-merchants
-- **Compliance**: Retrieve and list Requests for Information (RFIs), including for connected accounts
+- **Compliance**: Retrieve, list and respond to Requests for Information (RFIs), and upload supporting documents, including for connected accounts
 - **Sandbox Simulations**: Deposits, issuing transactions, disputes, transfer status, Direct Debit mandates, connected account/offboarding review outcomes, RFIs, and POS terminals — see [Sandbox Simulations](#sandbox-simulations)
 - **Idempotency**: Automatic request deduplication for safe retries
 - **Pagination**: Unified interface over cursor-based and offset-based pagination
@@ -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
+)
+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
 )
-split.release
+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
@@ -438,6 +477,50 @@ Airwallex::RFI.list({ statuses: 'ACTION_REQUIRED', types: 'KYC,KYC_ONGOING' }, h
               .auto_paging_each { |r| puts r.id }
 ```
 
+#### Responding to an RFI
+
+Upload any documents first, then answer every question in `active_request`
+in one call. Files go to the separate files host (`files-demo.airwallex.com`
+in sandbox, `files.airwallex.com` in production), up to 20MB each, and the
+returned `file_id` is what the answer references.
+
+```ruby
+passport = Airwallex::UploadedFile.upload(
+  File.open('passport.jpg', 'rb'),
+  filename: 'passport.jpg',
+  content_type: 'image/jpeg',
+  notes: 'passport-front',
+  opts: { headers: headers }
+)
+
+rfi = Airwallex::RFI.retrieve('rfi_123', headers: headers)
+rfi.respond(
+  {
+    questions: [
+      { id: 'q1', answer: { type: 'TEXT', text: 'We only operate in Australia' } },
+      { id: 'q2', answer: { type: 'ATTACHMENT', attachments: [{ file_id: passport.file_id }] } },
+      { id: 'q3', answer: { type: 'CONFIRMATION', confirmed: true } }
+    ]
+  },
+  headers: headers
+)
+rfi.status # => "ANSWERED"
+```
+
+Answer types are `TEXT` (`text:`), `ATTACHMENT` (`attachments: [{ file_id: }]`),
+`CONFIRMATION` (`confirmed:`), `ADDRESS` (`address: { address_line1:, ... }`),
+`IDENTITY_DOCUMENT` (`identity_document: { type:, number:, issuing_country:,
+front_file_id:, back_file_id: }`) and `LIVENESS`. A `LIVENESS` question is
+completed at its `liveness[:url]` rather than answered here, so do that first.
+The status then goes `ACTION_REQUIRED` → `ANSWERED` → `CLOSED`.
+
+Errors: `BadRequestError` with code `invalid_state_for_operation` (the RFI
+isn't `ACTION_REQUIRED`) or `invalid_argument` (a question is unanswered or
+has the wrong answer shape), and `PermissionError` with
+`account_not_authorised_for_operation`. You also get that last one when
+answering RFIs for connected accounts through the API hasn't been enabled
+for your platform; ask your Airwallex Account Manager to turn it on.
+
 ### Sandbox Simulations
 
 Sandbox-only endpoints (`/api/v1/simulation/...`) that stand in for the bank,
@@ -555,8 +638,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 +839,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 +946,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 +973,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)
@@ -883,7 +982,8 @@ end
 - **In-Person Payments** (sandbox Simulation only):
   - POSTerminal (simulate_turn_on, simulate_turn_off, simulate_generate_activation_code, simulate_confirm_payment_intent, simulate_payment_scenarios)
 - **Compliance**:
-  - RFI (retrieve, list, plus sandbox simulate_create, simulate_close, simulate_follow_up)
+  - RFI (retrieve, list, respond, plus sandbox simulate_create, simulate_close, simulate_follow_up)
+  - UploadedFile (upload, to the files host)
 - **Webhooks**: Event handling, HMAC-SHA256 signature verification
 
 ### Coming in Future Versions

data/lib/airwallex/client/file_uploads.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Client
+    # Multipart uploads to the files host (config.files_url), which is
+    # separate from the main API host
+    module FileUploads
+      # Separate connection for the files host (config.files_url). It sends
+      # multipart bodies, so it deliberately has no JSON Content-Type default,
+      # no :json request encoding, and no Idempotency middleware (which would
+      # add a stray request_id form field). No :retry either: faraday-retry
+      # only retries GET/DELETE here, and uploads are POSTs.
+      def files_connection
+        @files_connection ||= Faraday.new(url: config.files_url) do |conn|
+          conn.request :multipart
+          conn.use Airwallex::Middleware::AuthRefresh, self
+          conn.response :json, content_type: /\bjson$/
+          # Never log bodies here: they're the uploaded file's bytes
+          configure_logger(conn, bodies: false)
+
+          conn.headers["User-Agent"] = user_agent
+          conn.headers["x-api-version"] = config.api_version if config.api_version
+
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # POST a multipart upload to the files host
+      #
+      # @param path [String] e.g. "/api/v1/files/upload"
+      # @param file_part [Faraday::Multipart::FilePart] sent as the "file" field
+      # @param params [Hash] extra form fields (e.g. notes:)
+      # @param headers [Hash] e.g. { "x-on-behalf-of" => account_id }
+      # @return [Hash] parsed response body
+      def upload(path, file_part, params = {}, headers = {})
+        response = files_connection.post(path) do |req|
+          req.headers.merge!(headers)
+          req.body = { file: file_part }.merge(params)
+        end
+
+        handle_response_errors(response)
+        response.body
+      end
+    end
+  end
+end

data/lib/airwallex/client/logging.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Client
+    module Logging
+      private
+
+      # Log requests/responses with credentials masked: the API key header,
+      # the bearer token, and the token in the login response body
+      def configure_logger(conn, bodies:)
+        return unless config.logger
+
+        conn.response :logger, config.logger, { headers: true, bodies: bodies } do |logger|
+          logger.filter(/(x-api-key: )"[^"]*"/i, '\1"[FILTERED]"')
+          logger.filter(/(Authorization: )"Bearer [^"]*"/i, '\1"Bearer [FILTERED]"')
+          logger.filter(/("token":\s*)"[^"]*"/, '\1"[FILTERED]"')
+        end
+      end
+    end
+  end
+end

data/lib/airwallex/client.rb

@@ -4,9 +4,14 @@ require "faraday"
 require "faraday/multipart"
 require "faraday/retry"
 require "json"
+require_relative "client/file_uploads"
+require_relative "client/logging"
 
 module Airwallex
   class Client
+    include FileUploads
+    include Logging
+
     LOGIN_PATH = "/api/v1/authentication/login"
 
     attr_reader :config, :access_token, :token_expires_at
@@ -105,7 +110,7 @@ module Airwallex
       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
+      configure_logger(conn, bodies: true)
     end
 
     def handle_response_errors(response)

data/lib/airwallex/middleware/auth_refresh.rb

@@ -16,12 +16,19 @@ module Airwallex
         @client.ensure_authenticated! unless authentication_request?(env)
         authorize!(env)
 
+        # Once a response arrives, env[:body] holds the response body, so
+        # keep the request body to re-send it (same as faraday-retry)
+        request_body = env[:body]
         response = @app.call(env)
 
         # If we get a 401, try refreshing the token and retrying once
         if response.status == 401
           @client.authenticate!
           authorize!(env)
+          env[:body] = request_body
+          # A multipart upload body is a stream the first attempt already
+          # read; rewind it so the retry sends the file again
+          request_body.rewind if request_body.respond_to?(:rewind)
           response = @app.call(env)
         end
 

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

@@ -5,7 +5,7 @@ module Airwallex
   # Airwallex raises against your account (KYC, an ongoing KYC review, a
   # cardholder, a transaction, payment enablement, or merchant risk).
   #
-  # Supports retrieving and listing real RFIs, plus the sandbox Simulation
+  # Supports retrieving, listing and responding to real RFIs, plus the sandbox Simulation
   # endpoints for raising, closing and following up on them (there is no
   # live create — real RFIs originate from Airwallex's own compliance
   # review, same as Dispute). See
@@ -30,6 +30,41 @@ module Airwallex
   #     headers: { "x-on-behalf-of" => "acct_123" }
   #   ).auto_paging_each { |rfi| puts rfi.id }
   #
+  # @example Respond to an RFI (upload any documents first, see UploadedFile)
+  #   # Every question in active_request must be answered. Answer types:
+  #   # TEXT, ATTACHMENT, IDENTITY_DOCUMENT, CONFIRMATION, LIVENESS, ADDRESS.
+  #   # Any answer can also carry a comment:. LIVENESS has no answer body:
+  #   # complete the liveness check at question[:liveness][:url] first (an
+  #   # RFI whose only question is LIVENESS resolves itself), then respond
+  #   # to the rest.
+  #   rfi.respond(
+  #     {
+  #       questions: [
+  #         { id: "q1", answer: { type: "TEXT", text: "..." } },
+  #         { id: "q2", answer: { type: "ATTACHMENT", attachments: [{ file_id: file.file_id }] } },
+  #         { id: "q3", answer: { type: "CONFIRMATION", confirmed: true } },
+  #         { id: "q4", answer: { type: "ADDRESS", address: { address_line1: "...", address_line2: "...",
+  #                                                           suburb: "...", state: "...", postcode: "...",
+  #                                                           country_code: "AU" } } },
+  #         { id: "q5", answer: { type: "IDENTITY_DOCUMENT",
+  #                               identity_document: { type: "PASSPORT", number: "...", issuing_country: "AU",
+  #                                                    front_file_id: "...", back_file_id: "..." } } }
+  #       ]
+  #     },
+  #     headers: { "x-on-behalf-of" => "acct_123" }
+  #   )
+  #   rfi.status # => "ANSWERED"
+  #
+  # Responding: the lifecycle is ACTION_REQUIRED -> ANSWERED -> CLOSED
+  # (an RFI also moves to CLOSED when active_request.expires_at passes).
+  # Responding needs the risk.rfi:write scope. Errors:
+  # - invalid_state_for_operation (400): the RFI isn't ACTION_REQUIRED
+  # - invalid_argument (400): a question is unanswered, or an answer has
+  #   the wrong shape (e.g. TEXT vs ATTACHMENT)
+  # - account_not_authorised_for_operation (403): the RFI isn't linked to
+  #   the account, or answering RFIs for connected accounts through the
+  #   Native API hasn't been enabled (ask your Airwallex Account Manager)
+  #
   # @example Raise a KYC RFI, then close it
   #   rfi = Airwallex::RFI.simulate_create(
   #     type: "KYC",
@@ -75,6 +110,31 @@ module Airwallex
       )
     end
 
+    # Respond to an RFI. params are sent as-is (see the class docs for the
+    # body shape). Unlike other POSTs, no request_id is added: the endpoint
+    # doesn't document one.
+    #
+    # @param rfi_id [String]
+    # @param params [Hash] questions: (required) array of { id:, answer: { type:, ... } }
+    # @param opts [Hash] headers: (e.g. { "x-on-behalf-of" => account_id })
+    # @return [RFI]
+    def self.respond(rfi_id, params = {}, opts = {})
+      response = Airwallex.client.post("#{resource_path}/#{rfi_id}/respond", without_request_id(params),
+                                       opts[:headers] || {})
+      new(response)
+    end
+
+    # Pre-encode the body as JSON: the Idempotency middleware only adds
+    # request_id to Hash bodies, and the JSON middleware passes strings on
+    # unchanged
+    #
+    # @param params [Hash]
+    # @return [String]
+    def self.without_request_id(params)
+      JSON.generate(params)
+    end
+    private_class_method :without_request_id
+
     # Simulate Airwallex raising an RFI
     #
     # @param params [Hash] type: (required, one of "KYC", "KYC_ONGOING",
@@ -111,6 +171,16 @@ module Airwallex
       new(response)
     end
 
+    # Respond to this RFI. See .respond
+    #
+    # @param params [Hash] questions: (required)
+    # @param opts [Hash] headers: (e.g. { "x-on-behalf-of" => account_id })
+    # @return [RFI] self
+    def respond(params = {}, opts = {})
+      refresh_from(self.class.respond(id, params, opts).to_hash)
+      self
+    end
+
     # Simulate closing this RFI
     #
     # @param opts [Hash] headers: (e.g. { "x-on-behalf-of" => account_id })

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/resources/uploaded_file.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a file uploaded to Airwallex's files host (config.files_url,
+  # not the main API host) — e.g. a KYC document. The returned file_id is
+  # what other endpoints reference, such as RFI answers
+  # (attachments[].file_id, identity_document front_file_id/back_file_id).
+  # See https://www.airwallex.com/docs/api/supporting_services/file_service/upload_files
+  #
+  # Limits: 20MB per file; filename and notes up to 50 characters each.
+  # The response has file_id, filename, notes, size (bytes), object_type
+  # and created (epoch seconds, not created_at).
+  #
+  # Named UploadedFile rather than File so that bare File.open/File.read
+  # inside the Airwallex module still resolve to ::File.
+  #
+  # @example Upload a PDF on behalf of a connected account
+  #   file = Airwallex::UploadedFile.upload(
+  #     File.open("smo_declaration.pdf", "rb"),
+  #     filename: "smo_declaration.pdf",
+  #     content_type: "application/pdf",
+  #     notes: "SMO declaration",
+  #     opts: { headers: { "x-on-behalf-of" => "acct_123" } }
+  #   )
+  #   file.file_id # => "..."
+  class UploadedFile < APIResource
+    # @return [String] API path for file uploads, on the files host
+    def self.resource_path
+      "/api/v1/files/upload"
+    end
+
+    # Upload a file as multipart/form-data (form field "file")
+    #
+    # @param io [IO, StringIO, String] an IO, or a local file path
+    # @param filename [String]
+    # @param content_type [String] e.g. "application/pdf", "image/jpeg"
+    # @param notes [String, nil] a label, sent as the notes form field
+    # @param opts [Hash] headers: (e.g. { "x-on-behalf-of" => account_id })
+    # @return [UploadedFile]
+    def self.upload(io, filename:, content_type:, notes: nil, opts: {})
+      file_part = Faraday::Multipart::FilePart.new(io, content_type, filename)
+      params = notes.nil? ? {} : { notes: notes }
+      response = Airwallex.client.upload(resource_path, file_part, params, opts[:headers] || {})
+      new(response)
+    end
+
+    # The upload response identifies the file by file_id, not id, so id
+    # mirrors file_id to behave like other resources
+    def initialize(attributes = {})
+      super
+      @id ||= @attributes[:file_id]
+    end
+
+    def refresh_from(data)
+      super
+      @id ||= @attributes[:file_id]
+      self
+    end
+
+    # @return [String, nil]
+    def file_id
+      @attributes[:file_id]
+    end
+  end
+end

data/lib/airwallex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Airwallex
-  VERSION = "0.10.0"
+  VERSION = "0.12.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"
@@ -54,6 +56,7 @@ require_relative "airwallex/resources/cardholder"
 require_relative "airwallex/resources/linked_account"
 require_relative "airwallex/resources/account_offboarding"
 require_relative "airwallex/resources/rfi"
+require_relative "airwallex/resources/uploaded_file"
 require_relative "airwallex/resources/pos_terminal"
 
 module Airwallex

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airwallex
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -75,6 +75,8 @@ files:
 - lib/airwallex/api_operations/update.rb
 - lib/airwallex/api_resource.rb
 - lib/airwallex/client.rb
+- lib/airwallex/client/file_uploads.rb
+- lib/airwallex/client/logging.rb
 - lib/airwallex/configuration.rb
 - lib/airwallex/errors.rb
 - lib/airwallex/list_object.rb
@@ -93,11 +95,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
@@ -114,6 +118,7 @@ files:
 - lib/airwallex/resources/refund.rb
 - lib/airwallex/resources/rfi.rb
 - lib/airwallex/resources/transfer.rb
+- lib/airwallex/resources/uploaded_file.rb
 - lib/airwallex/util.rb
 - lib/airwallex/version.rb
 - lib/airwallex/webhook.rb