straddle 0.5.0 → 1.0.0

data/lib/straddle/models/charge.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    class Charge < Straddle::Internal::Type::BaseModel
+      # @!attribute id
+      #   Unique identifier for this charge.
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute amount
+      #   Amount in cents.
+      #
+      #   @return [Integer]
+      required :amount, Integer
+
+      # @!attribute config
+      #   Configuration options for the charge.
+      #
+      #   @return [Straddle::Models::ChargeConfiguration]
+      required :config, -> { Straddle::ChargeConfiguration }
+
+      # @!attribute consent_type
+      #   How the customer authorized the charge. `internet` covers online and mobile
+      #   authorization. `signed` covers written or PDF-signed agreements.
+      #
+      #   @return [Symbol, Straddle::Models::ConsentType]
+      required :consent_type, enum: -> { Straddle::ConsentType }
+
+      # @!attribute created_at
+      #   Timestamp when this charge was created.
+      #
+      #   @return [Time, nil]
+      required :created_at, Time, nil?: true
+
+      # @!attribute currency
+      #   Currency code. Only `USD` is supported.
+      #
+      #   @return [String]
+      required :currency, String
+
+      # @!attribute description
+      #   A human-readable description of the charge.
+      #
+      #   @return [String, nil]
+      required :description, String, nil?: true
+
+      # @!attribute device
+      #   Device used when the customer authorized the charge.
+      #
+      #   @return [Straddle::Models::MaskedPaymentDevice]
+      required :device, -> { Straddle::MaskedPaymentDevice }
+
+      # @!attribute external_id
+      #   Your unique identifier for this charge, used to correlate with your internal
+      #   records.
+      #
+      #   @return [String]
+      required :external_id, String
+
+      # @!attribute funding_ids
+      #   IDs of the funding events that included this charge.
+      #
+      #   @return [Array<String>]
+      required :funding_ids, Straddle::Internal::Type::ArrayOf[String]
+
+      # @!attribute has_refund
+      #   Whether an associated payout has refunded this charge.
+      #
+      #   @return [Boolean]
+      required :has_refund, Straddle::Internal::Type::Boolean
+
+      # @!attribute has_resubmit
+      #   Whether this charge has been resubmitted.
+      #
+      #   @return [Boolean]
+      required :has_resubmit, Straddle::Internal::Type::Boolean
+
+      # @!attribute is_resubmit
+      #   Whether this charge resubmits an original charge.
+      #
+      #   @return [Boolean]
+      required :is_resubmit, Straddle::Internal::Type::Boolean
+
+      # @!attribute paykey
+      #   The masked paykey token used for this charge.
+      #
+      #   @return [String]
+      required :paykey, String
+
+      # @!attribute payment_date
+      #   Date when Straddle submits the charge for processing.
+      #
+      #   @return [Date]
+      required :payment_date, Date
+
+      # @!attribute status
+      #   The current status of the charge.
+      #
+      #   @return [Symbol, Straddle::Models::PaymentStatus]
+      required :status, enum: -> { Straddle::PaymentStatus }
+
+      # @!attribute status_details
+      #   Reason, source, and message for the most recent charge status change.
+      #
+      #   @return [Straddle::Models::PaymentStatusDetails]
+      required :status_details, -> { Straddle::PaymentStatusDetails }
+
+      # @!attribute status_history
+      #   Complete ordered history of all status changes for this charge.
+      #
+      #   @return [Array<Straddle::Models::PaymentStatusHistory>]
+      required :status_history, -> { Straddle::Internal::Type::ArrayOf[Straddle::PaymentStatusHistory] }
+
+      # @!attribute trace_ids
+      #   Trace identifiers from the payment network. Keys depend on the payment rail.
+      #
+      #   @return [Hash{Symbol=>String}]
+      required :trace_ids, Straddle::Internal::Type::HashOf[String]
+
+      # @!attribute updated_at
+      #   Timestamp when this charge was last updated.
+      #
+      #   @return [Time, nil]
+      required :updated_at, Time, nil?: true
+
+      # @!attribute customer_details
+      #   Information about the customer associated with the charge.
+      #
+      #   @return [Straddle::Models::CustomerDetails, nil]
+      optional :customer_details, -> { Straddle::CustomerDetails }
+
+      # @!attribute documents
+      #   Authorization documents for this charge, ordered by upload time.
+      #
+      #   @return [Array<Straddle::Models::PaymentAuthorizationProof>, nil]
+      optional :documents,
+               -> { Straddle::Internal::Type::ArrayOf[Straddle::PaymentAuthorizationProof] },
+               nil?: true
+
+      # @!attribute effective_at
+      #   Timestamp when funds were settled. Null until settlement is confirmed.
+      #
+      #   @return [Time, nil]
+      optional :effective_at, Time, nil?: true
+
+      # @!attribute metadata
+      #   Key-value metadata stored with this charge.
+      #
+      #   @return [Hash{Symbol=>String}, nil]
+      optional :metadata, Straddle::Internal::Type::HashOf[String], nil?: true
+
+      # @!attribute paykey_details
+      #   Information about the paykey used for the charge.
+      #
+      #   @return [Straddle::Models::PaykeyDetails, nil]
+      optional :paykey_details, -> { Straddle::PaykeyDetails }
+
+      # @!attribute payment_rail
+      #   Payment rail used to process the charge.
+      #
+      #   @return [Symbol, Straddle::Models::PaymentRail, nil]
+      optional :payment_rail, enum: -> { Straddle::PaymentRail }
+
+      # @!attribute processed_at
+      #   Timestamp when this charge was submitted to the payment network. Null until
+      #   processed.
+      #
+      #   @return [Time, nil]
+      optional :processed_at, Time, nil?: true
+
+      # @!attribute related_payments
+      #   Related payments and their relationship to this charge.
+      #
+      #   @return [Array<Straddle::Models::RelatedPayment>, nil]
+      optional :related_payments,
+               -> { Straddle::Internal::Type::ArrayOf[Straddle::RelatedPayment] },
+               nil?: true
+
+      # @!method initialize(id:, amount:, config:, consent_type:, created_at:, currency:, description:, device:, external_id:, funding_ids:, has_refund:, has_resubmit:, is_resubmit:, paykey:, payment_date:, status:, status_details:, status_history:, trace_ids:, updated_at:, customer_details: nil, documents: nil, effective_at: nil, metadata: nil, paykey_details: nil, payment_rail: nil, processed_at: nil, related_payments: nil)
+      #   Some parameter documentations has been truncated, see {Straddle::Models::Charge}
+      #   for more details.
+      #
+      #   @param id [String] Unique identifier for this charge.
+      #
+      #   @param amount [Integer] Amount in cents.
+      #
+      #   @param config [Straddle::Models::ChargeConfiguration] Configuration options for the charge.
+      #
+      #   @param consent_type [Symbol, Straddle::Models::ConsentType] How the customer authorized the charge. `internet` covers online and mobile auth
+      #
+      #   @param created_at [Time, nil] Timestamp when this charge was created.
+      #
+      #   @param currency [String] Currency code. Only `USD` is supported.
+      #
+      #   @param description [String, nil] A human-readable description of the charge.
+      #
+      #   @param device [Straddle::Models::MaskedPaymentDevice] Device used when the customer authorized the charge.
+      #
+      #   @param external_id [String] Your unique identifier for this charge, used to correlate with your internal rec
+      #
+      #   @param funding_ids [Array<String>] IDs of the funding events that included this charge.
+      #
+      #   @param has_refund [Boolean] Whether an associated payout has refunded this charge.
+      #
+      #   @param has_resubmit [Boolean] Whether this charge has been resubmitted.
+      #
+      #   @param is_resubmit [Boolean] Whether this charge resubmits an original charge.
+      #
+      #   @param paykey [String] The masked paykey token used for this charge.
+      #
+      #   @param payment_date [Date] Date when Straddle submits the charge for processing.
+      #
+      #   @param status [Symbol, Straddle::Models::PaymentStatus] The current status of the charge.
+      #
+      #   @param status_details [Straddle::Models::PaymentStatusDetails] Reason, source, and message for the most recent charge status change.
+      #
+      #   @param status_history [Array<Straddle::Models::PaymentStatusHistory>] Complete ordered history of all status changes for this charge.
+      #
+      #   @param trace_ids [Hash{Symbol=>String}] Trace identifiers from the payment network. Keys depend on the payment rail.
+      #
+      #   @param updated_at [Time, nil] Timestamp when this charge was last updated.
+      #
+      #   @param customer_details [Straddle::Models::CustomerDetails] Information about the customer associated with the charge.
+      #
+      #   @param documents [Array<Straddle::Models::PaymentAuthorizationProof>, nil] Authorization documents for this charge, ordered by upload time.
+      #
+      #   @param effective_at [Time, nil] Timestamp when funds were settled. Null until settlement is confirmed.
+      #
+      #   @param metadata [Hash{Symbol=>String}, nil] Key-value metadata stored with this charge.
+      #
+      #   @param paykey_details [Straddle::Models::PaykeyDetails] Information about the paykey used for the charge.
+      #
+      #   @param payment_rail [Symbol, Straddle::Models::PaymentRail] Payment rail used to process the charge.
+      #
+      #   @param processed_at [Time, nil] Timestamp when this charge was submitted to the payment network. Null until proc
+      #
+      #   @param related_payments [Array<Straddle::Models::RelatedPayment>, nil] Related payments and their relationship to this charge.
+    end
+  end
+end

data/lib/straddle/models/charge_cancel_params.rb

@@ -13,27 +13,31 @@ module Straddle
       required :id, String
 
       # @!attribute reason
-      #   Details about why the charge status was updated.
+      #   Message explaining the charge status change.
       #
       #   @return [String, nil]
       optional :reason, String, nil?: true
 
       # @!attribute correlation_id
+      #   Optional client-generated identifier for tracing a series of related requests.
       #
       #   @return [String, nil]
       optional :correlation_id, String
 
       # @!attribute idempotency_key
+      #   Optional client-generated key for an idempotent request.
       #
       #   @return [String, nil]
       optional :idempotency_key, String
 
       # @!attribute request_id
+      #   Optional client-generated identifier for tracing one request.
       #
       #   @return [String, nil]
       optional :request_id, String
 
       # @!attribute straddle_account_id
+      #   For platform requests, the embedded account UUID that sets the request scope.
       #
       #   @return [String, nil]
       optional :straddle_account_id, String
@@ -41,15 +45,15 @@ module Straddle
       # @!method initialize(id:, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #   @param id [String]
       #
-      #   @param reason [String, nil] Details about why the charge status was updated.
+      #   @param reason [String, nil] Message explaining the charge status change.
       #
-      #   @param correlation_id [String]
+      #   @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      #   @param idempotency_key [String]
+      #   @param idempotency_key [String] Optional client-generated key for an idempotent request.
       #
-      #   @param request_id [String]
+      #   @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      #   @param straddle_account_id [String]
+      #   @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}]
     end

data/lib/straddle/models/charge_configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    class ChargeConfiguration < Straddle::Internal::Type::BaseModel
+      # @!attribute balance_check
+      #   Balance check mode to use before processing the charge.
+      #
+      #   @return [Symbol, Straddle::Models::BalanceCheckMode]
+      required :balance_check, enum: -> { Straddle::BalanceCheckMode }
+
+      # @!attribute auto_hold
+      #   Whether to place the charge on hold automatically after creation.
+      #
+      #   @return [Boolean, nil]
+      optional :auto_hold, Straddle::Internal::Type::Boolean, nil?: true
+
+      # @!attribute auto_hold_message
+      #   Reason for placing the charge on hold automatically.
+      #
+      #   @return [String, nil]
+      optional :auto_hold_message, String, nil?: true
+
+      # @!attribute sandbox_outcome
+      #   Payment will simulate processing if not Standard.
+      #
+      #   @return [Symbol, Straddle::Models::SimulatedPaymentOutcome, nil]
+      optional :sandbox_outcome, enum: -> { Straddle::SimulatedPaymentOutcome }
+
+      # @!method initialize(balance_check:, auto_hold: nil, auto_hold_message: nil, sandbox_outcome: nil)
+      #   @param balance_check [Symbol, Straddle::Models::BalanceCheckMode] Balance check mode to use before processing the charge.
+      #
+      #   @param auto_hold [Boolean, nil] Whether to place the charge on hold automatically after creation.
+      #
+      #   @param auto_hold_message [String, nil] Reason for placing the charge on hold automatically.
+      #
+      #   @param sandbox_outcome [Symbol, Straddle::Models::SimulatedPaymentOutcome] Payment will simulate processing if not Standard.
+    end
+  end
+end

data/lib/straddle/models/charge_create_params.rb

@@ -8,85 +8,84 @@ module Straddle
       include Straddle::Internal::Type::RequestParameters
 
       # @!attribute amount
-      #   The amount of the charge in cents.
+      #   Amount in cents.
       #
       #   @return [Integer]
       required :amount, Integer
 
       # @!attribute config
       #
-      #   @return [Straddle::Models::ChargeCreateParams::Config]
-      required :config, -> { Straddle::ChargeCreateParams::Config }
+      #   @return [Straddle::Models::ChargeConfiguration]
+      required :config, -> { Straddle::ChargeConfiguration }
 
       # @!attribute consent_type
-      #   The channel or mechanism through which the payment was authorized. Use
-      #   `internet` for payments made online or through a mobile app and `signed` for
-      #   signed agreements where there is a consent form or contract. Use `signed` for
-      #   PDF signatures.
+      #   How the customer authorized the charge. `internet` covers online and mobile
+      #   authorization. `signed` covers written or PDF-signed agreements.
       #
-      #   @return [Symbol, Straddle::Models::ChargeCreateParams::ConsentType]
-      required :consent_type, enum: -> { Straddle::ChargeCreateParams::ConsentType }
+      #   @return [Symbol, Straddle::Models::ConsentType]
+      required :consent_type, enum: -> { Straddle::ConsentType }
 
       # @!attribute currency
-      #   The currency of the charge. Only USD is supported.
+      #   Currency code. Only `USD` is supported.
       #
       #   @return [String]
       required :currency, String
 
       # @!attribute description
-      #   An arbitrary description for the charge.
+      #   Description shown on the customer's bank statement where supported.
       #
       #   @return [String, nil]
       required :description, String, nil?: true
 
       # @!attribute device
       #
-      #   @return [Straddle::Models::DeviceInfoV1]
-      required :device, -> { Straddle::DeviceInfoV1 }
+      #   @return [Straddle::Models::PaymentDevice]
+      required :device, -> { Straddle::PaymentDevice }
 
       # @!attribute external_id
-      #   Unique identifier for the charge in your database. This value must be unique
-      #   across all charges.
+      #   Your unique identifier for the charge. Must be unique across charges.
       #
       #   @return [String]
       required :external_id, String
 
       # @!attribute paykey
-      #   Value of the `paykey` used for the charge.
+      #   The paykey token that identifies the customer's bank account.
       #
       #   @return [String]
       required :paykey, String
 
       # @!attribute payment_date
-      #   The desired date on which the payment should be occur. For charges, this means
-      #   the date you want the customer to be debited on.
+      #   Date when Straddle submits the charge for processing.
       #
       #   @return [Date]
       required :payment_date, Date
 
       # @!attribute metadata
-      #   Up to 20 additional user-defined key-value pairs. Useful for storing additional
-      #   information about the charge in a structured format.
+      #   Up to 20 user-defined string key-value pairs.
       #
       #   @return [Hash{Symbol=>String}, nil]
       optional :metadata, Straddle::Internal::Type::HashOf[String], nil?: true
 
       # @!attribute correlation_id
+      #   Optional client-generated identifier for tracing a series of related requests.
       #
       #   @return [String, nil]
       optional :correlation_id, String
 
       # @!attribute idempotency_key
+      #   Optional client-generated key for an idempotent request.
       #
       #   @return [String, nil]
       optional :idempotency_key, String
 
       # @!attribute request_id
+      #   Optional client-generated identifier for tracing one request.
       #
       #   @return [String, nil]
       optional :request_id, String
 
       # @!attribute straddle_account_id
+      #   For platform requests, the embedded account UUID that sets the request scope.
       #
       #   @return [String, nil]
       optional :straddle_account_id, String
@@ -95,122 +94,35 @@ module Straddle
       #   Some parameter documentations has been truncated, see
       #   {Straddle::Models::ChargeCreateParams} for more details.
       #
-      #   @param amount [Integer] The amount of the charge in cents.
+      #   @param amount [Integer] Amount in cents.
       #
-      #   @param config [Straddle::Models::ChargeCreateParams::Config]
+      #   @param config [Straddle::Models::ChargeConfiguration]
       #
-      #   @param consent_type [Symbol, Straddle::Models::ChargeCreateParams::ConsentType] The channel or mechanism through which the payment was authorized. Use `internet
+      #   @param consent_type [Symbol, Straddle::Models::ConsentType] How the customer authorized the charge. `internet` covers online and mobile auth
       #
-      #   @param currency [String] The currency of the charge. Only USD is supported.
+      #   @param currency [String] Currency code. Only `USD` is supported.
       #
-      #   @param description [String, nil] An arbitrary description for the charge.
+      #   @param description [String, nil] Description shown on the customer's bank statement where supported.
       #
-      #   @param device [Straddle::Models::DeviceInfoV1]
+      #   @param device [Straddle::Models::PaymentDevice]
       #
-      #   @param external_id [String] Unique identifier for the charge in your database. This value must be unique acr
+      #   @param external_id [String] Your unique identifier for the charge. Must be unique across charges.
       #
-      #   @param paykey [String] Value of the `paykey` used for the charge.
+      #   @param paykey [String] The paykey token that identifies the customer's bank account.
       #
-      #   @param payment_date [Date] The desired date on which the payment should be occur. For charges, this means t
+      #   @param payment_date [Date] Date when Straddle submits the charge for processing.
       #
-      #   @param metadata [Hash{Symbol=>String}, nil] Up to 20 additional user-defined key-value pairs. Useful for storing additional
+      #   @param metadata [Hash{Symbol=>String}, nil] Up to 20 user-defined string key-value pairs.
       #
-      #   @param correlation_id [String]
+      #   @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      #   @param idempotency_key [String]
+      #   @param idempotency_key [String] Optional client-generated key for an idempotent request.
       #
-      #   @param request_id [String]
+      #   @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      #   @param straddle_account_id [String]
+      #   @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}]
-
-      class Config < Straddle::Internal::Type::BaseModel
-        # @!attribute balance_check
-        #   Defines whether to check the customer's balance before processing the charge.
-        #
-        #   @return [Symbol, Straddle::Models::ChargeCreateParams::Config::BalanceCheck]
-        required :balance_check, enum: -> { Straddle::ChargeCreateParams::Config::BalanceCheck }
-
-        # @!attribute auto_hold
-        #   Defines whether to automatically place this charge on hold after being created.
-        #
-        #   @return [Boolean, nil]
-        optional :auto_hold, Straddle::Internal::Type::Boolean, nil?: true
-
-        # @!attribute auto_hold_message
-        #   The reason the charge is being automatically held on creation.
-        #
-        #   @return [String, nil]
-        optional :auto_hold_message, String, nil?: true
-
-        # @!attribute sandbox_outcome
-        #   Payment will simulate processing if not Standard.
-        #
-        #   @return [Symbol, Straddle::Models::ChargeCreateParams::Config::SandboxOutcome, nil]
-        optional :sandbox_outcome, enum: -> { Straddle::ChargeCreateParams::Config::SandboxOutcome }
-
-        # @!method initialize(balance_check:, auto_hold: nil, auto_hold_message: nil, sandbox_outcome: nil)
-        #   @param balance_check [Symbol, Straddle::Models::ChargeCreateParams::Config::BalanceCheck] Defines whether to check the customer's balance before processing the charge.
-        #
-        #   @param auto_hold [Boolean, nil] Defines whether to automatically place this charge on hold after being created.
-        #
-        #   @param auto_hold_message [String, nil] The reason the charge is being automatically held on creation.
-        #
-        #   @param sandbox_outcome [Symbol, Straddle::Models::ChargeCreateParams::Config::SandboxOutcome] Payment will simulate processing if not Standard.
-
-        # Defines whether to check the customer's balance before processing the charge.
-        #
-        # @see Straddle::Models::ChargeCreateParams::Config#balance_check
-        module BalanceCheck
-          extend Straddle::Internal::Type::Enum
-
-          REQUIRED = :required
-          ENABLED = :enabled
-          DISABLED = :disabled
-
-          # @!method self.values
-          #   @return [Array<Symbol>]
-        end
-
-        # Payment will simulate processing if not Standard.
-        #
-        # @see Straddle::Models::ChargeCreateParams::Config#sandbox_outcome
-        module SandboxOutcome
-          extend Straddle::Internal::Type::Enum
-
-          STANDARD = :standard
-          PAID = :paid
-          ON_HOLD_DAILY_LIMIT = :on_hold_daily_limit
-          CANCELLED_FOR_FRAUD_RISK = :cancelled_for_fraud_risk
-          CANCELLED_FOR_BALANCE_CHECK = :cancelled_for_balance_check
-          FAILED_INSUFFICIENT_FUNDS = :failed_insufficient_funds
-          REVERSED_INSUFFICIENT_FUNDS = :reversed_insufficient_funds
-          FAILED_CUSTOMER_DISPUTE = :failed_customer_dispute
-          REVERSED_CUSTOMER_DISPUTE = :reversed_customer_dispute
-          FAILED_CLOSED_BANK_ACCOUNT = :failed_closed_bank_account
-          REVERSED_CLOSED_BANK_ACCOUNT = :reversed_closed_bank_account
-          FAILED_NOT_AUTHORIZED = :failed_not_authorized
-          REVERSED_NOT_AUTHORIZED = :reversed_not_authorized
-
-          # @!method self.values
-          #   @return [Array<Symbol>]
-        end
-      end
-
-      # The channel or mechanism through which the payment was authorized. Use
-      # `internet` for payments made online or through a mobile app and `signed` for
-      # signed agreements where there is a consent form or contract. Use `signed` for
-      # PDF signatures.
-      module ConsentType
-        extend Straddle::Internal::Type::Enum
-
-        INTERNET = :internet
-        SIGNED = :signed
-
-        # @!method self.values
-        #   @return [Array<Symbol>]
-      end
     end
   end
 end