airwallex 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1288d75bff8a6f00a8c0dfffc318b6df1821cb26c945e062930de6035e83822
-  data.tar.gz: 5452a4a8aed172764129f05043646e9f074c1c9e62df84246ffe6ff575ba0140
+  metadata.gz: 20abbd73aa43d82620559c0f067a6236619d3dad597b778b41b75af6d87fb225
+  data.tar.gz: 6a477ebe40ec72d267d42f9b98669d783dd7db32c9cf9d30ed0b671c07810252
 SHA512:
-  metadata.gz: 02e3eea25661113f96af469d3154ede00aae144c671c42fcdf48d2e08d900c74ff2291b9b901ebc2b2072688b840d07d58f6b7eb21bd14aaf2c75d2e4625e6f2
-  data.tar.gz: 31bb06a6c4a99f4d433c63b5eb9e209e31deeec63dd3d98a516d259801530e874b66b70d4680d386eba0e569589a55e51c59640af3907fbade0e1da9171b6698
+  metadata.gz: ac0aa15ebc45b61bbd7004010bbdfc261c1243d373cbd59b4dbb141e680b0d46ca079ab25f2d4c4e9017f5d4a4730fff4950f632e5415c82de0728cd3e3837b8
+  data.tar.gz: 948df17c305f0ab1c88791b29afe1df2218197c12512cbb52c7f80cb0524c9e1903a7e4b1b25597c2ed447d010fed846df94e48ec988ccdf85019913318fa561

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [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

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
@@ -477,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,
@@ -938,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/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/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.11.0"
+  VERSION = "0.12.0"
 end

data/lib/airwallex.rb

@@ -56,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.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 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
@@ -116,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
@@ -146,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Production-grade Ruby client for the Airwallex API