straddle 0.5.0 → 1.0.0

data/lib/straddle/resources/charges.rb

@@ -2,67 +2,96 @@
 
 module Straddle
   module Resources
-    # Charges represent attempts to debit money from a customer's bank account using a
-    # Paykey. Each charge includes automatic balance verification, real-time fraud
-    # screening, and multi-rail optimization and detailed status tracking throughout
-    # the payment lifecycle. Use charges to accept bank payments with confidence
-    # knowing every transaction is protected.
+    # Charges debit a customer's bank account through a paykey.
     class Charges
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::ChargeCreateParams} for more details.
       #
-      # Use charges to collect money from a customer for the sale of goods or services.
+      # Creates a charge against a customer's paykey. Straddle submits the charge for
+      # processing on `payment_date` unless the charge is on hold.
       #
       # @overload create(amount:, config:, consent_type:, currency:, description:, device:, external_id:, paykey:, payment_date:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param amount [Integer] Body param: The amount of the charge in cents.
+      # @param amount [Integer] Body param: Amount in cents.
       #
-      # @param config [Straddle::Models::ChargeCreateParams::Config] Body param
+      # @param config [Straddle::Models::ChargeConfiguration] Body param
       #
-      # @param consent_type [Symbol, Straddle::Models::ChargeCreateParams::ConsentType] Body param: The channel or mechanism through which the payment was authorized. U
+      # @param consent_type [Symbol, Straddle::Models::ConsentType] Body param: How the customer authorized the charge. `internet` covers online and
       #
-      # @param currency [String] Body param: The currency of the charge. Only USD is supported.
+      # @param currency [String] Body param: Currency code. Only `USD` is supported.
       #
-      # @param description [String, nil] Body param: An arbitrary description for the charge.
+      # @param description [String, nil] Body param: Description shown on the customer's bank statement where supported.
       #
-      # @param device [Straddle::Models::DeviceInfoV1] Body param
+      # @param device [Straddle::Models::PaymentDevice] Body param
       #
-      # @param external_id [String] Body param: Unique identifier for the charge in your database. This value must b
+      # @param external_id [String] Body param: Your unique identifier for the charge. Must be unique across charges
       #
-      # @param paykey [String] Body param: Value of the `paykey` used for the charge.
+      # @param paykey [String] Body param: The paykey token that identifies the customer's bank account.
       #
-      # @param payment_date [Date] Body param: The desired date on which the payment should be occur. For charges,
+      # @param payment_date [Date] Body param: Date when Straddle submits the charge for processing.
       #
-      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 user-defined string key-value pairs.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @return [Straddle::Models::ChargeResponse]
       #
       # @see Straddle::Models::ChargeCreateParams
       def create(params)
         parsed, options = Straddle::ChargeCreateParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :post,
           path: "v1/charges",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::ChargeV1,
+          model: Straddle::ChargeResponse,
+          options: options
+        )
+      end
+
+      # Returns a charge by its unique identifier.
+      #
+      # @overload retrieve(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the charge.
+      #
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
+      #
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::ChargeResponse]
+      #
+      # @see Straddle::Models::ChargeRetrieveParams
+      def retrieve(id, params = {})
+        parsed, options = Straddle::ChargeRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/charges/%1$s", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::ChargeResponse,
           options: options
         )
       end
@@ -70,49 +99,48 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::ChargeUpdateParams} for more details.
       #
-      # Change the values of parameters associated with a charge prior to processing.
-      # The status of the charge must be `created`, `scheduled`, or `on_hold`.
+      # Updates the description, amount, `payment_date`, or metadata. The charge must
+      # have a status of `created` or `on_hold`.
       #
       # @overload update(id, amount:, description:, payment_date:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the charge.
       #
-      # @param amount [Integer] Body param: The amount of the charge in cents.
+      # @param amount [Integer] Body param: Amount in cents.
       #
-      # @param description [String, nil] Body param: An arbitrary description for the charge.
+      # @param description [String, nil] Body param: Updated description for the charge.
       #
-      # @param payment_date [Date] Body param: The desired date on which the payment should be occur. For charges,
+      # @param payment_date [Date] Body param: New date for Straddle to submit the charge for processing.
       #
-      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: Replacement metadata for the charge. Up to 20 user-defined string ke
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @return [Straddle::Models::ChargeResponse]
       #
       # @see Straddle::Models::ChargeUpdateParams
       def update(id, params)
         parsed, options = Straddle::ChargeUpdateParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :put,
           path: ["v1/charges/%1$s", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::ChargeV1,
+          model: Straddle::ChargeResponse,
           options: options
         )
       end
@@ -120,120 +148,170 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::ChargeCancelParams} for more details.
       #
-      # Cancel a charge to prevent it from being originated for processing. The status
-      # of the charge must be `created`, `scheduled`, or `on_hold`.
+      # Cancels a charge. The charge must have a status of `created`, `scheduled`, or
+      # `on_hold`.
       #
       # @overload cancel(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the charge.
       #
-      # @param reason [String, nil] Body param: Details about why the charge status was updated.
+      # @param reason [String, nil] Body param: Message explaining the charge status change.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @return [Straddle::Models::ChargeResponse]
       #
       # @see Straddle::Models::ChargeCancelParams
       def cancel(id, params = {})
         parsed, options = Straddle::ChargeCancelParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :put,
           path: ["v1/charges/%1$s/cancel", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::ChargeV1,
+          model: Straddle::ChargeResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::ChargeHoldParams} for more details.
+      #
+      # Places a charge on hold to prevent submission for processing. The charge must
+      # have a status of `created` or `scheduled`.
+      #
+      # @overload hold(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Path param: Unique identifier for the charge.
+      #
+      # @param reason [String, nil] Body param: Message explaining the charge status change.
+      #
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
+      #
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::ChargeResponse]
+      #
+      # @see Straddle::Models::ChargeHoldParams
+      def hold(id, params = {})
+        parsed, options = Straddle::ChargeHoldParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
+        @client.request(
+          method: :put,
+          path: ["v1/charges/%1$s/hold", id],
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::ChargeResponse,
           options: options
         )
       end
 
-      # Retrieves the details of an existing charge. Supply the unique charge `id`, and
-      # Straddle will return the corresponding charge information.
+      # Return a charge with its sensitive fields unmasked.
       #
-      # @overload get(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload list_unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String]
+      # @param id [String] Unique identifier for the charge.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @return [Straddle::Models::UnmaskedChargeResponse]
       #
-      # @see Straddle::Models::ChargeGetParams
-      def get(id, params = {})
-        parsed, options = Straddle::ChargeGetParams.dump_request(params)
+      # @see Straddle::Models::ChargeListUnmaskedParams
+      def list_unmasked(id, params = {})
+        parsed, options = Straddle::ChargeListUnmaskedParams.dump_request(params)
         @client.request(
           method: :get,
-          path: ["v1/charges/%1$s", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::ChargeV1,
+          path: ["v1/charges/%1$s/unmask", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::UnmaskedChargeResponse,
           options: options
         )
       end
 
       # Some parameter documentations has been truncated, see
-      # {Straddle::Models::ChargeHoldParams} for more details.
+      # {Straddle::Models::ChargeRefundParams} for more details.
       #
-      # Place a charge on hold to prevent it from being originated for processing. The
-      # status of the charge must be `created` or `scheduled`.
+      # Creates a payout to return funds from a paid charge to the customer's bank
+      # account. The payout is linked to the charge through `related_payments`. A charge
+      # can be refunded once, either fully or partially.
       #
-      # @overload hold(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload refund(id, amount: nil, description: nil, external_id: nil, metadata: nil, payment_date: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the charge.
       #
-      # @param reason [String, nil] Body param: Details about why the charge status was updated.
+      # @param amount [Integer, nil] Body param: Refund amount in cents. `null` refunds the full original amount. A v
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param description [String, nil] Body param: Description for the refund payout. Defaults to a description that id
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param external_id [String, nil] Body param: Your unique identifier for the refund. Defaults to a new value if om
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: User-defined string key-value pairs for the refund payout.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param payment_date [Date, nil] Body param: Date when Straddle submits the refund payout for processing. Default
       #
-      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @see Straddle::Models::ChargeHoldParams
-      def hold(id, params = {})
-        parsed, options = Straddle::ChargeHoldParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::PayoutResponse]
+      #
+      # @see Straddle::Models::ChargeRefundParams
+      def refund(id, params = {})
+        parsed, options = Straddle::ChargeRefundParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
-          method: :put,
-          path: ["v1/charges/%1$s/hold", id],
+          method: :post,
+          path: ["v1/charges/%1$s/refund", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::ChargeV1,
+          model: Straddle::PayoutResponse,
           options: options
         )
       end
@@ -241,75 +319,133 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::ChargeReleaseParams} for more details.
       #
-      # Release a charge from an `on_hold` status to allow it to be rescheduled for
-      # processing.
+      # Releases a charge from `on_hold` and returns it to `created` for submission on
+      # `payment_date`.
       #
       # @overload release(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the charge.
       #
-      # @param reason [String, nil] Body param: Details about why the charge status was updated.
+      # @param reason [String, nil] Body param: Message explaining the charge status change.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeV1]
+      # @return [Straddle::Models::ChargeResponse]
       #
       # @see Straddle::Models::ChargeReleaseParams
       def release(id, params = {})
         parsed, options = Straddle::ChargeReleaseParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :put,
           path: ["v1/charges/%1$s/release", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::ChargeV1,
+          model: Straddle::ChargeResponse,
           options: options
         )
       end
 
-      # Get a charge by id.
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::ChargeResubmitParams} for more details.
+      #
+      # Creates a new charge from a failed, reversed, or cancelled charge. The request
+      # can override `description`, `external_id`, and `payment_date`. Other payment
+      # details come from the original charge.
+      #
+      # @overload resubmit(id, description: nil, external_id: nil, payment_date: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @overload unmask(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @param id [String] Path param: Unique identifier for the charge.
       #
-      # @param id [String]
+      # @param description [String, nil] Body param: Description for the resubmitted charge. Defaults to the original des
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param external_id [String, nil] Body param: Your unique identifier for the resubmitted charge. Defaults to a new
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param payment_date [Date, nil] Body param: Date when Straddle submits the resubmitted charge for processing. De
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
+      #
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::ChargeUnmaskResponse]
+      # @return [Straddle::Models::ChargeResponse]
+      #
+      # @see Straddle::Models::ChargeResubmitParams
+      def resubmit(id, params = {})
+        parsed, options = Straddle::ChargeResubmitParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
+        @client.request(
+          method: :post,
+          path: ["v1/charges/%1$s/resubmit", id],
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::ChargeResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::ChargeUploadAuthorizationProofParams} for more details.
+      #
+      # Uploads a proof-of-authorization document for a charge. A later upload adds
+      # another document and does not replace an existing one.
+      #
+      # @overload upload_authorization_proof(id, file:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Path param: Unique identifier for the charge.
+      #
+      # @param file [Pathname, StringIO, IO, String, Straddle::FilePart] Body param: The document file to upload as proof of authorization for this charg
       #
-      # @see Straddle::Models::ChargeUnmaskParams
-      def unmask(id, params = {})
-        parsed, options = Straddle::ChargeUnmaskParams.dump_request(params)
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
+      #
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::ChargeResponse]
+      #
+      # @see Straddle::Models::ChargeUploadAuthorizationProofParams
+      def upload_authorization_proof(id, params)
+        parsed, options = Straddle::ChargeUploadAuthorizationProofParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
-          method: :get,
-          path: ["v1/charges/%1$s/unmask", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::Models::ChargeUnmaskResponse,
+          method: :post,
+          path: ["v1/charges/%1$s/authorization", id],
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::ChargeResponse,
           options: options
         )
       end