payabli 3.0.1 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36bd2543107fba665cc922c2aabf537bfc21fa08bfc1ad4c508cb46f06273a20
-  data.tar.gz: 96c5e675eced6a18eb20b5da9c4cc1b56b7bae4c8e27632f750e3da5efd8a69d
+  metadata.gz: 030ce6ece0ebf9ee1b7db55aabee60f4f77ddd0e755004597504f6c831bb39f7
+  data.tar.gz: f475de7c086a0699ac89a0b009ce87e30ff5ea16973a11dc6ad19395724a0350
 SHA512:
-  metadata.gz: bcb5d0a819b41497c6ce92340c29d65adbc72ef70aff938f6aa433f81cf1890b78a1a295f8a4f98a142fbe911653e126189a7a73262ea1be96b14b3c4447b7aa
-  data.tar.gz: 07fc43e8305fd4d5dddf461a25580bec52088648505ce45f8bbada721a6a7782d525fe68fdf818d1e65bc9d188ed9a4ea02cbde78fca8f1c2ae1a944d3678111
+  metadata.gz: 6ae52fe15e466ead4098f19b312144d8a907adcc736d40d2102cd7435dbc1fbca2bbf75aae42642997f706a89ece45b7773b47a37d5b5f49ca888fe14c19b8e5
+  data.tar.gz: 25304386f26b6bbb6f03b5628d270fc0538aa5149f23f637b32c73e7a153cda1b15750995d68b59205543da1d5aebba3d8665a57c04aa69101d7fc6170eea7a7

data/.fern/metadata.json

@@ -1,15 +1,15 @@
 {
-  "cliVersion": "5.7.9",
+  "cliVersion": "5.56.0",
   "generatorName": "fernapi/fern-ruby-sdk",
-  "generatorVersion": "1.12.7",
+  "generatorVersion": "1.15.2",
   "generatorConfig": {
     "enableWireTests": true,
     "rubocopVariableNumberStyle": "snake_case"
   },
-  "originGitCommit": "21b1f70a2e9bfc3b23ab1d28054848d68be85fdc",
+  "originGitCommit": "fbf628bcea22b886022a9bd709dca9daaf0bd3ca",
   "originGitCommitIsDirty": true,
   "invokedBy": "ci",
-  "requestedVersion": "3.0.1",
+  "requestedVersion": "3.0.3",
   "ciProvider": "github",
-  "sdkVersion": "3.0.1"
+  "sdkVersion": "3.0.3"
 }

data/README.md

@@ -71,7 +71,10 @@ Instantiate and use the client with the following:
 ```ruby
 require "payabli"
 
-client = Payabli::Client.new(api_key: "<value>")
+client = Payabli::Client.new(
+  client_id: "<clientId>",
+  client_secret: "<clientSecret>"
+)
 
 client.money_in.getpaidv_2(
   customer_data: {

data/lib/payabli/client.rb

@@ -2,18 +2,42 @@
 
 module Payabli
   class Client
-    # @param api_key [String]
     # @param base_url [String, nil]
+    # @param client_id [String, nil]
+    # @param client_secret [String, nil]
+    # @param api_key [String, nil]
+    # @param max_retries [Integer]
     #
     # @return [void]
-    def initialize(api_key:, base_url: nil)
+    def initialize(base_url: nil, client_id: ENV.fetch("OAUTH_CLIENT_ID", nil), client_secret: ENV.fetch("OAUTH_CLIENT_SECRET", nil), api_key: nil, max_retries: 2)
+      if !client_id.to_s.empty? && !client_secret.to_s.empty?
+        # Create an unauthenticated client for the auth endpoint
+        auth_raw_client = Payabli::Internal::Http::RawClient.new(
+          base_url: base_url || Payabli::Environment::SANDBOX,
+          headers: {
+            "X-Fern-Language" => "Ruby"
+          }
+        )
+
+        # Create the auth client for token retrieval
+        auth_client = Payabli::Token::Client.new(client: auth_raw_client)
+
+        # Create the OAuth provider with the auth client and credentials
+        @auth_provider = Payabli::Internal::OAuthProvider.new(
+          auth_client: auth_client,
+          options: { base_url: base_url, client_id: client_id, client_secret: client_secret }
+        )
+      end
+
       @raw_client = Payabli::Internal::Http::RawClient.new(
         base_url: base_url || Payabli::Environment::SANDBOX,
         headers: {
-          "User-Agent" => "payabli/3.0.1",
+          "User-Agent" => "payabli/3.0.3",
           "X-Fern-Language" => "Ruby",
           requestToken: api_key.to_s
-        }
+        },
+        auth_provider: @auth_provider,
+        max_retries: max_retries
       )
     end
 
@@ -37,6 +61,11 @@ module Payabli
       @money_in ||= Payabli::MoneyIn::Client.new(client: @raw_client)
     end
 
+    # @return [Payabli::Token::Client]
+    def token
+      @token ||= Payabli::Token::Client.new(client: @raw_client)
+    end
+
     # @return [Payabli::Subscription::Client]
     def subscription
       @subscription ||= Payabli::Subscription::Client.new(client: @raw_client)
@@ -157,6 +186,11 @@ module Payabli
       @money_out ||= Payabli::MoneyOut::Client.new(client: @raw_client)
     end
 
+    # @return [Payabli::Funding::Client]
+    def funding
+      @funding ||= Payabli::Funding::Client.new(client: @raw_client)
+    end
+
     # @return [Payabli::Wallet::Client]
     def wallet
       @wallet ||= Payabli::Wallet::Client.new(client: @raw_client)

data/lib/payabli/customer/client.rb

@@ -11,7 +11,7 @@ module Payabli
       end
 
       # Creates a customer in an entrypoint. An identifier is required to create customer records. Change your
-      # identifier settings in Settings > Custom Fields in PartnerHub.
+      # identifier settings in Settings > Custom Fields in the Payabli Portal.
       # If you don't include an identifier, the record is rejected.
       #
       # @param request_options [Hash]

data/lib/payabli/funding/client.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Payabli
+  module Funding
+    class Client
+      # @param client [Payabli::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Deposits funds into a paypoint's available payout balance. Deposited funds enter a pending state and aren't
+      # available for instant payouts until confirmed through FBO reconciliation.
+      #
+      # @param request_options [Hash]
+      # @param params [Payabli::Funding::Types::DepositFundsRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Payabli::Types::DepositFundsResponse]
+      def deposit_funds(request_options: {}, **params)
+        params = Payabli::Internal::Types::Utils.normalize_keys(params)
+        request = Payabli::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "Funding/depositFunds",
+          body: Payabli::Funding::Types::DepositFundsRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Payabli::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Payabli::Types::DepositFundsResponse.load(response.body)
+        else
+          error_class = Payabli::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/payabli/funding/types/deposit_funds_request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Payabli
+  module Funding
+    module Types
+      class DepositFundsRequest < Internal::Types::Model
+        field :amount, -> { Integer }, optional: false, nullable: false
+
+        field :entrypoint, -> { String }, optional: false, nullable: false
+
+        field :account_id, -> { String }, optional: false, nullable: false, api_name: "accountId"
+
+        field :paypoint_id, -> { Integer }, optional: true, nullable: false, api_name: "paypointId"
+
+        field :same_day_ach, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "sameDayAch"
+      end
+    end
+  end
+end

data/lib/payabli/internal/http/raw_client.rb

@@ -21,10 +21,14 @@ module Payabli
         # @param max_retries [Integer] The number of times to retry a failed request, defaults to 2.
         # @param timeout [Float] The timeout for the request, defaults to 60.0 seconds.
         # @param headers [Hash] The headers for the request.
-        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {})
+        # @param auth_provider [Object, nil] An optional auth provider responding to
+        #   `auth_headers`. When present its headers are resolved on every request so
+        #   token-based schemes (e.g. OAuth) can refresh an expired token mid-session.
+        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {}, auth_provider: nil)
           @base_url = base_url
           @max_retries = max_retries
           @timeout = timeout
+          @auth_provider = auth_provider
           @default_headers = {
             "X-Fern-Language": "Ruby",
             "X-Fern-SDK-Name": "payabli",
@@ -36,6 +40,9 @@ module Payabli
         # @return [HTTP::Response] The HTTP response.
         def send(request)
           url = build_url(request)
+          # Resolve auth headers once per request (not per retry) so token-based
+          # providers refresh at most once here; static providers are cheap.
+          auth_headers = resolve_auth_headers
           attempt = 0
           response = nil
 
@@ -43,8 +50,9 @@ module Payabli
             http_request = build_http_request(
               url:,
               method: request.method,
-              headers: request.encode_headers(protected_keys: @default_headers.keys),
-              body: request.encode_body
+              headers: request.encode_headers(protected_keys: @default_headers.keys + auth_headers.keys),
+              body: request.encode_body,
+              auth_headers: auth_headers
             )
 
             conn = connect(url)
@@ -157,12 +165,27 @@ module Payabli
                 "HTTP is only allowed for localhost. Use HTTPS or pass a localhost URL."
         end
 
+        # Resolves the auth headers to send with the next request. Delegates to the
+        # configured auth provider (if any) on every call so that token-based
+        # providers (e.g. OAuth client-credentials) can refresh an expired token
+        # before the request is sent. Returns an empty hash when no provider is set,
+        # which keeps the api-key / basic / bearer / no-auth paths unchanged.
+        # @return [Hash] The auth headers for the current request.
+        def resolve_auth_headers
+          return {} if @auth_provider.nil?
+
+          @auth_provider.auth_headers
+        end
+
         # @param url [URI::Generic] The url to the resource.
         # @param method [String] The HTTP method to use.
         # @param headers [Hash] The headers for the request.
         # @param body [String, nil] The body for the request.
+        # @param auth_headers [Hash] The auth headers resolved for this request. These
+        #   take precedence over the static default headers but not over per-request
+        #   headers, mirroring the previous baked-header precedence.
         # @return [HTTP::Request] The HTTP request.
-        def build_http_request(url:, method:, headers: {}, body: nil)
+        def build_http_request(url:, method:, headers: {}, body: nil, auth_headers: {})
           request = Net::HTTPGenericRequest.new(
             method,
             !body.nil?,
@@ -170,7 +193,7 @@ module Payabli
             url
           )
 
-          request_headers = @default_headers.merge(headers)
+          request_headers = @default_headers.merge(auth_headers).merge(headers)
           request_headers.each { |name, value| request[name] = value }
           request.body = body if body
 

data/lib/payabli/internal/oauth_provider.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Payabli
+  module Internal
+    class OAuthProvider
+      BUFFER_IN_SECONDS = 120 # 2 minutes
+
+      # @param auth_client [untyped]
+      # @param options [Hash[String, untyped]]
+      #
+      # @return [void]
+      def initialize(auth_client:, options:)
+        @auth_client = auth_client
+        @options = options
+        @access_token = nil
+        @expires_at = nil
+      end
+
+      # Returns a cached access token, refreshing if necessary.
+      # Refreshes the token if it's nil, or if we're within the buffer period before expiration.
+      #
+      # @return [String]
+      def token
+        return refresh if @access_token.nil? || token_needs_refresh?
+
+        @access_token
+      end
+
+      # Returns the authentication headers to be included in requests.
+      #
+      # @return [Hash[String, String]]
+      def auth_headers
+        access_token = token
+        {
+          Authorization: "Bearer #{access_token}"
+        }
+      end
+
+      # Checks if the token needs to be refreshed.
+      # Returns true if the token will expire within the buffer period.
+      #
+      # @return [Boolean]
+      private def token_needs_refresh?
+        return true if @expires_at.nil?
+
+        Time.now >= (@expires_at - BUFFER_IN_SECONDS)
+      end
+
+      # Refreshes the access token by calling the token endpoint.
+      #
+      # @return [String]
+      private def refresh
+        request_params = {
+          client_id: @options[:client_id],
+          client_secret: @options[:client_secret]
+        }
+
+        token_response = @auth_client.create_server_side_token(**request_params)
+
+        @access_token = token_response.access_token
+        @expires_at = Time.now + token_response.expires_in
+
+        @access_token
+      end
+    end
+  end
+end

data/lib/payabli/money_in/client.rb

@@ -10,14 +10,19 @@ module Payabli
         @client = client
       end
 
+      # <Warning>
+      # This endpoint is deprecated. New integrations should use the [Authorize
+      # endpoint](/developers/api-reference/moneyinV2/authorize-a-transaction), then capture, void, or refund the
+      # resulting transaction with the corresponding endpoints. Transactions created with this legacy endpoint must be
+      # managed with the legacy lifecycle endpoints — they aren't interchangeable with the current ones.
+      # </Warning>
+      #
+      #
       # Authorize a card transaction. This returns an authorization code and reserves funds for the merchant. Authorized
       # transactions aren't flagged for settlement until
       # [captured](/developers/api-reference/moneyin/capture-an-authorized-transaction).
+      #
       # Only card transactions can be authorized. This endpoint can't be used for ACH transactions.
-      # <Tip>
-      # Consider migrating to the [v2 Authorize endpoint](/developers/api-reference/moneyinV2/authorize-a-transaction)
-      # to take advantage of unified response codes and improved response consistency.
-      # </Tip>
       #
       # @param request_options [Hash]
       # @param params [Payabli::Types::TransRequestBody]
@@ -64,8 +69,9 @@ module Payabli
       end
 
       # <Warning>
-      # This endpoint is deprecated and will be sunset on November 24, 2025. Migrate to [POST
-      # `/capture/{transId}`](/developers/api-reference/moneyin/capture-an-authorized-transaction)`.
+      # This endpoint is deprecated. Use [POST
+      # `/capture/{transId}`](/developers/api-reference/moneyin/capture-an-authorized-transaction) instead, which
+      # supports partial captures and service fee adjustments.
       # </Warning>
       #
       #   Capture an [authorized
@@ -105,6 +111,14 @@ module Payabli
         end
       end
 
+      # <Warning>
+      # This endpoint is deprecated. Use it only to capture transactions originally authorized with the legacy
+      # [Authorize endpoint](/developers/api-reference/moneyin/authorize-a-transaction). New integrations should use the
+      # [Capture endpoint](/developers/api-reference/moneyinV2/capture-an-authorized-transaction), which only works on
+      # transactions authorized with the current [Authorize
+      # endpoint](/developers/api-reference/moneyinV2/authorize-a-transaction).
+      # </Warning>
+      #
       # Capture an [authorized transaction](/developers/api-reference/moneyin/authorize-a-transaction) to complete the
       # transaction and move funds from the customer to merchant account.
       #
@@ -112,12 +126,6 @@ module Payabli
       # [Capture an authorized transaction](/developers/developer-guides/pay-in-auth-and-capture) for more information
       # about this endpoint.
       #
-      # <Tip>
-      # Consider migrating to the [v2 Capture
-      # endpoint](/developers/api-reference/moneyinV2/capture-an-authorized-transaction) to take advantage of unified
-      # response codes and improved response consistency.
-      # </Tip>
-      #
       # @param request_options [Hash]
       # @param params [Payabli::Types::CaptureRequest]
       # @option request_options [String] :base_url
@@ -237,13 +245,14 @@ module Payabli
         end
       end
 
-      # Make a single transaction. This method authorizes and captures a payment in one step.
+      # <Warning>
+      # This endpoint is deprecated. New integrations should use the [Make a transaction
+      # endpoint](/developers/api-reference/moneyinV2/make-a-transaction) and manage the resulting transaction with the
+      # corresponding void or refund endpoints. Transactions created with this legacy endpoint must be managed with the
+      # legacy lifecycle endpoints — they aren't interchangeable with the current ones.
+      # </Warning>
       #
-      #   <Tip>
-      # Consider migrating to the [v2 Make a transaction
-      # endpoint](/developers/api-reference/moneyinV2/make-a-transaction) to take advantage of unified response codes
-      # and improved response consistency.
-      #   </Tip>
+      # Make a single transaction. This method authorizes and captures a payment in one step.
       #
       # @param request_options [Hash]
       # @param params [Payabli::Types::TransRequestBody]
@@ -295,11 +304,20 @@ module Payabli
         end
       end
 
+      # <Warning>
+      # This endpoint is deprecated and only works on transactions created with the legacy endpoints. There's no
+      # equivalent in the current endpoints. For transactions created with [Make a
+      # transaction](/developers/api-reference/moneyinV2/make-a-transaction) or
+      # [Authorize](/developers/api-reference/moneyinV2/authorize-a-transaction), check the transaction's settlement
+      # status and call [Void](/developers/api-reference/moneyinV2/void-a-transaction) or
+      # [Refund](/developers/api-reference/moneyinV2/refund-a-settled-transaction) based on the result.
+      # </Warning>
+      #
       # A reversal either refunds or voids a transaction independent of the transaction's settlement status. Send a
       # reversal request for a transaction, and Payabli automatically determines whether it's a refund or void. You
       # don't need to know whether the transaction is settled or not. This endpoint only works on transactions made with
-      # the v1 API. For v2 transactions, check the transaction's settlement status and call v2 void or v2 refund based
-      # on the result.
+      # the legacy endpoints. For transactions made with the current endpoints, check the transaction's settlement
+      # status and call void or refund based on the result.
       #
       # @param request_options [Hash]
       # @param params [Hash]
@@ -334,14 +352,17 @@ module Payabli
         end
       end
 
+      # <Warning>
+      # This endpoint is deprecated. Use it only to refund transactions originally created with the legacy endpoints.
+      # New integrations should use the [Refund
+      # endpoint](/developers/api-reference/moneyinV2/refund-a-settled-transaction), which only works on transactions
+      # created with [Make a transaction](/developers/api-reference/moneyinV2/make-a-transaction) or
+      # [Authorize](/developers/api-reference/moneyinV2/authorize-a-transaction).
+      # </Warning>
+      #
       # Refund a transaction that has settled and send money back to the account holder. If a transaction hasn't been
       # settled, void it instead.
       #
-      #   <Tip>
-      # Consider migrating to the [v2 Refund endpoint](/developers/api-reference/moneyinV2/refund-a-settled-transaction)
-      # to take advantage of unified response codes and improved response consistency.
-      #   </Tip>
-      #
       # @param request_options [Hash]
       # @param params [Hash]
       # @option request_options [String] :base_url
@@ -375,6 +396,15 @@ module Payabli
         end
       end
 
+      # <Warning>
+      # This endpoint is deprecated. Use it only to refund transactions originally created with the legacy endpoints. To
+      # refund a split-funded transaction created with [Make a
+      # transaction](/developers/api-reference/moneyinV2/make-a-transaction) or
+      # [Authorize](/developers/api-reference/moneyinV2/authorize-a-transaction), use the [Refund
+      # endpoint](/developers/api-reference/moneyinV2/refund-a-settled-transaction) with split instructions in the
+      # request body.
+      # </Warning>
+      #
       # Refunds a settled transaction with split instructions.
       #
       # @param request_options [Hash]
@@ -536,14 +566,16 @@ module Payabli
         end
       end
 
+      # <Warning>
+      # This endpoint is deprecated. Use it only to void transactions originally created with the legacy endpoints. New
+      # integrations should use the [Void endpoint](/developers/api-reference/moneyinV2/void-a-transaction), which only
+      # works on transactions created with [Make a transaction](/developers/api-reference/moneyinV2/make-a-transaction)
+      # or [Authorize](/developers/api-reference/moneyinV2/authorize-a-transaction).
+      # </Warning>
+      #
       # Cancel a transaction that hasn't been settled yet. Voiding non-captured authorizations prevents future captures.
       # If a transaction has been settled, refund it instead.
       #
-      #   <Tip>
-      # Consider migrating to the [v2 Void endpoint](/developers/api-reference/moneyinV2/void-a-transaction) to take
-      # advantage of unified response codes and improved response consistency.
-      #   </Tip>
-      #
       # @param request_options [Hash]
       # @param params [Hash]
       # @option request_options [String] :base_url
@@ -719,13 +751,18 @@ module Payabli
 
       # Give a full refund for a transaction that has settled and send money back to the account holder. To perform a
       # partial refund, see [Partially refund a
-      # transaction](developers/api-reference/moneyinV2/partial-refund-a-settled-transaction).
+      # transaction](/developers/api-reference/moneyinV2/partial-refund-a-settled-transaction).
       #
       # This is the v2 version of the refund endpoint, and returns the unified response format. See [Pay In unified
       # response codes reference](/guides/pay-in-unified-response-codes-reference) for more information.
       #
+      # <Note>
+      # To refund a split-funded transaction, include split instructions in the request body. Omit the body for a
+      # standard refund.
+      # </Note>
+      #
       # @param request_options [Hash]
-      # @param params [Hash]
+      # @param params [Payabli::Types::RefundV2Request]
       # @option request_options [String] :base_url
       # @option request_options [Hash{String => Object}] :additional_headers
       # @option request_options [Hash{String => Object}] :additional_query_parameters
@@ -740,6 +777,7 @@ module Payabli
           base_url: request_options[:base_url],
           method: "POST",
           path: "v2/MoneyIn/refund/#{URI.encode_uri_component(params[:trans_id].to_s)}",
+          body: Payabli::Types::RefundV2Request.new(params).to_h,
           request_options: request_options
         )
         begin
@@ -756,14 +794,19 @@ module Payabli
         end
       end
 
-      # Refund a transaction that has settled and send money back to the account holder. If `amount` is omitted or set
-      # to 0, performs a full refund. When a non-zero `amount` is provided, this endpoint performs a partial refund.
+      # Refund a transaction that has settled and send money back to the account holder. If `amount` is set to 0,
+      # performs a full refund. When a non-zero `amount` is provided, this endpoint performs a partial refund.
       #
       # This is the v2 version of the refund endpoint, and returns the unified response format. See [Pay In unified
       # response codes reference](/guides/pay-in-unified-response-codes-reference) for more information.
       #
+      # <Note>
+      # To refund a split-funded transaction, include split instructions in the request body. Omit the body for a
+      # standard refund.
+      # </Note>
+      #
       # @param request_options [Hash]
-      # @param params [Hash]
+      # @param params [Payabli::Types::RefundV2Request]
       # @option request_options [String] :base_url
       # @option request_options [Hash{String => Object}] :additional_headers
       # @option request_options [Hash{String => Object}] :additional_query_parameters
@@ -779,6 +822,7 @@ module Payabli
           base_url: request_options[:base_url],
           method: "POST",
           path: "v2/MoneyIn/refund/#{URI.encode_uri_component(params[:trans_id].to_s)}/#{URI.encode_uri_component(params[:amount].to_s)}",
+          body: Payabli::Types::RefundV2Request.new(params).to_h,
           request_options: request_options
         )
         begin

data/lib/payabli/money_out/client.rb

@@ -18,8 +18,17 @@ module Payabli
       # When `autoCapture` is `true`, Payabli captures the transaction asynchronously after authorization. The response
       # confirms only that the transaction was authorized; it doesn't confirm that capture succeeded. To confirm
       # capture, listen for the
-      # [`payout_transaction_approvedcaptured`](/developers/webhooks/payout-transaction-approved-captured) webhook
-      # event.
+      # [`payout_transaction_approvedcaptured`](/developers/api-reference/webhooks-overview/payout-transaction-approved-captured)
+      # webhook event.
+      #
+      # If a velocity fraud alert is triggered, the endpoint returns a `202` response with `responseCode` `9051`, and
+      # the authorization is held for risk review rather than rejected. If a risk policy blocks the transaction, the
+      # endpoint returns a `422` response with `responseCode` `9005`, a terminal rejection.
+      #
+      # For check payouts, Payabli validates the remit (mailing) address at authorization. If the address fails
+      # deliverability validation, the endpoint returns a `422` response and doesn't charge the paypoint. Correct the
+      # address and re-authorize. Other payout rails (ACH, RTP, virtual card, wire, and managed payables) aren't
+      # affected.
       #
       # @param request_options [Hash]
       # @param params [Payabli::MoneyOut::Types::RequestOutAuthorize]
@@ -214,7 +223,11 @@ module Payabli
       end
 
       # Captures a single authorized payout transaction by ID. If the transaction was authorized with `autoCapture` set
-      # to `true`,  you don't need to call this endpoint to capture the transaction for processing.
+      # to `true`, you don't need to call this endpoint to capture the transaction for processing.
+      #
+      # If a velocity fraud alert is triggered, the endpoint returns a `202` response with `responseCode` `9051`, and
+      # the capture is held for risk review rather than rejected. If a risk policy blocks the transaction, the endpoint
+      # returns a `422` response with `responseCode` `9005`, a terminal rejection.
       #
       # @param request_options [Hash]
       # @param params [Hash]
@@ -321,6 +334,53 @@ module Payabli
         end
       end
 
+      # Renews an expired or expiring virtual card by extending its expiration date to a future month.
+      #
+      # The card must be a virtual card that hasn't been fully used. The new expiration date must be in `MM-YYYY` or
+      # `MM/YYYY` format and no more than 2 years and 363 days in the future. The card expires on the last day of the
+      # month you specify.
+      #
+      # On success, `referenceId` holds the renewed card's token (the card processor may issue a new token). The
+      # response reuses the standard payout result object, so the payment-transaction fields it carries don't apply to
+      # renewal and always return `null`.
+      #
+      # @param request_options [Hash]
+      # @param params [Payabli::MoneyOut::Types::RenewVCardRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :card_token
+      #
+      # @return [Payabli::Types::RenewVCardResponse]
+      def renew_v_card(request_options: {}, **params)
+        params = Payabli::Internal::Types::Utils.normalize_keys(params)
+        request_data = Payabli::MoneyOut::Types::RenewVCardRequest.new(params).to_h
+        non_body_param_names = %w[cardToken]
+        body = request_data.except(*non_body_param_names)
+
+        request = Payabli::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PUT",
+          path: "MoneyOutCard/vcard/#{URI.encode_uri_component(params[:card_token].to_s)}/renew",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Payabli::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Payabli::Types::RenewVCardResponse.load(response.body)
+        else
+          error_class = Payabli::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
       # Sends a virtual card link via email to the vendor associated with the `transId`.
       #
       # @param request_options [Hash]

data/lib/payabli/money_out/types/renew_v_card_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Payabli
+  module MoneyOut
+    module Types
+      class RenewVCardRequest < Internal::Types::Model
+        field :card_token, -> { String }, optional: false, nullable: false, api_name: "cardToken"
+
+        field :expiration_date, -> { String }, optional: false, nullable: false, api_name: "expirationDate"
+      end
+    end
+  end
+end