straddle 0.5.0 → 1.0.0

data/lib/straddle/models/payment_status_reason.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    module PaymentStatusReason
+      extend Straddle::Internal::Type::Enum
+
+      INSUFFICIENT_FUNDS = :insufficient_funds
+      CLOSED_BANK_ACCOUNT = :closed_bank_account
+      INVALID_BANK_ACCOUNT = :invalid_bank_account
+      INVALID_ROUTING = :invalid_routing
+      DISPUTED = :disputed
+      PAYMENT_STOPPED = :payment_stopped
+      OWNER_DECEASED = :owner_deceased
+      FROZEN_BANK_ACCOUNT = :frozen_bank_account
+      RISK_REVIEW = :risk_review
+      FRAUDULENT = :fraudulent
+      DUPLICATE_ENTRY = :duplicate_entry
+      INVALID_PAYKEY = :invalid_paykey
+      PAYMENT_BLOCKED = :payment_blocked
+      AMOUNT_TOO_LARGE = :amount_too_large
+      TOO_MANY_ATTEMPTS = :too_many_attempts
+      INTERNAL_SYSTEM_ERROR = :internal_system_error
+      USER_REQUEST = :user_request
+      OK = :ok
+      OTHER_NETWORK_RETURN = :other_network_return
+      PAYOUT_REFUSED = :payout_refused
+      CANCEL_REQUEST = :cancel_request
+      FAILED_VERIFICATION = :failed_verification
+      REQUIRE_REVIEW = :require_review
+      BLOCKED_BY_SYSTEM = :blocked_by_system
+      WATCHTOWER_REVIEW = :watchtower_review
+      VALIDATING = :validating
+      AUTO_HOLD = :auto_hold
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/straddle/models/payment_status_source.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    module PaymentStatusSource
+      extend Straddle::Internal::Type::Enum
+
+      WATCHTOWER = :watchtower
+      BANK_DECLINE = :bank_decline
+      CUSTOMER_DISPUTE = :customer_dispute
+      USER_ACTION = :user_action
+      SYSTEM = :system
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/straddle/models/payment_summary.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    class PaymentSummary < Straddle::Internal::Type::BaseModel
+      # @!attribute id
+      #   Unique identifier for this charge or payout.
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute amount
+      #   Amount in cents.
+      #
+      #   @return [Integer]
+      required :amount, Integer
+
+      # @!attribute created_at
+      #   Timestamp when the charge or payout was created.
+      #
+      #   @return [Time]
+      required :created_at, Time
+
+      # @!attribute currency
+      #   Currency code. Only `USD` is supported.
+      #
+      #   @return [String]
+      required :currency, String
+
+      # @!attribute description
+      #   Human-readable description of the payment.
+      #
+      #   @return [String, nil]
+      required :description, String, nil?: true
+
+      # @!attribute external_id
+      #   Your unique identifier for the charge or payout.
+      #
+      #   @return [String]
+      required :external_id, String
+
+      # @!attribute funding_ids
+      #   IDs of the funding events that included this payment.
+      #
+      #   @return [Array<String>]
+      required :funding_ids, Straddle::Internal::Type::ArrayOf[String]
+
+      # @!attribute has_refund
+      #   Whether this payment is a charge refunded by an associated payout.
+      #
+      #   @return [Boolean]
+      required :has_refund, Straddle::Internal::Type::Boolean
+
+      # @!attribute has_resubmit
+      #   Whether this payment has been resubmitted.
+      #
+      #   @return [Boolean]
+      required :has_resubmit, Straddle::Internal::Type::Boolean
+
+      # @!attribute is_refund
+      #   Whether this payment is a payout that refunds an original charge.
+      #
+      #   @return [Boolean]
+      required :is_refund, Straddle::Internal::Type::Boolean
+
+      # @!attribute is_resubmit
+      #   Whether this payment resubmits an original payment.
+      #
+      #   @return [Boolean]
+      required :is_resubmit, Straddle::Internal::Type::Boolean
+
+      # @!attribute paykey
+      #   Masked paykey token used for the charge or payout.
+      #
+      #   @return [String]
+      required :paykey, String
+
+      # @!attribute payment_date
+      #   Date when Straddle submits the payment for processing.
+      #
+      #   @return [Date]
+      required :payment_date, Date
+
+      # @!attribute payment_type
+      #   Whether this payment is a charge or payout.
+      #
+      #   @return [Symbol, Straddle::Models::PaymentType]
+      required :payment_type, enum: -> { Straddle::PaymentType }
+
+      # @!attribute status
+      #   Current status of the charge or payout.
+      #
+      #   @return [Symbol, Straddle::Models::PaymentStatus]
+      required :status, enum: -> { Straddle::PaymentStatus }
+
+      # @!attribute status_details
+      #   Reason, source, and message for the most recent status change.
+      #
+      #   @return [Straddle::Models::PaymentStatusDetails]
+      required :status_details, -> { Straddle::PaymentStatusDetails }
+
+      # @!attribute trace_ids
+      #   Network-level trace identifiers assigned during processing. Keys vary by payment
+      #   rail.
+      #
+      #   @return [Hash{Symbol=>String}]
+      required :trace_ids, Straddle::Internal::Type::HashOf[String]
+
+      # @!attribute updated_at
+      #   Timestamp when the charge or payout was last updated.
+      #
+      #   @return [Time]
+      required :updated_at, Time
+
+      # @!attribute customer_details
+      #   Information about the customer associated with the charge or payout.
+      #
+      #   @return [Straddle::Models::CustomerDetails, nil]
+      optional :customer_details, -> { Straddle::CustomerDetails }
+
+      # @!attribute effective_at
+      #   Timestamp when funds settled. Null until settlement is confirmed.
+      #
+      #   @return [Time, nil]
+      optional :effective_at, Time, nil?: true
+
+      # @!attribute funding_id
+      #   Unique identifier for the funding event associated with the `charge` or
+      #   `payout`.
+      #
+      #   @return [String, nil]
+      optional :funding_id, String, nil?: true
+
+      # @!attribute metadata
+      #   Key-value metadata for the payment. Included only when `include_metadata` is
+      #   true.
+      #
+      #   @return [Hash{Symbol=>String}, nil]
+      optional :metadata, Straddle::Internal::Type::HashOf[String], nil?: true
+
+      # @!attribute paykey_details
+      #   Details of the paykey used for the charge or payout.
+      #
+      #   @return [Straddle::Models::PaykeyDetails, nil]
+      optional :paykey_details, -> { Straddle::PaykeyDetails }
+
+      # @!attribute related_payments
+      #   Related payments and their relationship to this charge or payout.
+      #
+      #   @return [Array<Straddle::Models::RelatedPayment>, nil]
+      optional :related_payments,
+               -> { Straddle::Internal::Type::ArrayOf[Straddle::RelatedPayment] },
+               nil?: true
+
+      # @!method initialize(id:, amount:, created_at:, currency:, description:, external_id:, funding_ids:, has_refund:, has_resubmit:, is_refund:, is_resubmit:, paykey:, payment_date:, payment_type:, status:, status_details:, trace_ids:, updated_at:, customer_details: nil, effective_at: nil, funding_id: nil, metadata: nil, paykey_details: nil, related_payments: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Straddle::Models::PaymentSummary} for more details.
+      #
+      #   @param id [String] Unique identifier for this charge or payout.
+      #
+      #   @param amount [Integer] Amount in cents.
+      #
+      #   @param created_at [Time] Timestamp when the charge or payout was created.
+      #
+      #   @param currency [String] Currency code. Only `USD` is supported.
+      #
+      #   @param description [String, nil] Human-readable description of the payment.
+      #
+      #   @param external_id [String] Your unique identifier for the charge or payout.
+      #
+      #   @param funding_ids [Array<String>] IDs of the funding events that included this payment.
+      #
+      #   @param has_refund [Boolean] Whether this payment is a charge refunded by an associated payout.
+      #
+      #   @param has_resubmit [Boolean] Whether this payment has been resubmitted.
+      #
+      #   @param is_refund [Boolean] Whether this payment is a payout that refunds an original charge.
+      #
+      #   @param is_resubmit [Boolean] Whether this payment resubmits an original payment.
+      #
+      #   @param paykey [String] Masked paykey token used for the charge or payout.
+      #
+      #   @param payment_date [Date] Date when Straddle submits the payment for processing.
+      #
+      #   @param payment_type [Symbol, Straddle::Models::PaymentType] Whether this payment is a charge or payout.
+      #
+      #   @param status [Symbol, Straddle::Models::PaymentStatus] Current status of the charge or payout.
+      #
+      #   @param status_details [Straddle::Models::PaymentStatusDetails] Reason, source, and message for the most recent status change.
+      #
+      #   @param trace_ids [Hash{Symbol=>String}] Network-level trace identifiers assigned during processing. Keys vary by payment
+      #
+      #   @param updated_at [Time] Timestamp when the charge or payout was last updated.
+      #
+      #   @param customer_details [Straddle::Models::CustomerDetails] Information about the customer associated with the charge or payout.
+      #
+      #   @param effective_at [Time, nil] Timestamp when funds settled. Null until settlement is confirmed.
+      #
+      #   @param funding_id [String, nil] Unique identifier for the funding event associated with the `charge` or `payout`
+      #
+      #   @param metadata [Hash{Symbol=>String}, nil] Key-value metadata for the payment. Included only when `include_metadata` is tru
+      #
+      #   @param paykey_details [Straddle::Models::PaykeyDetails] Details of the paykey used for the charge or payout.
+      #
+      #   @param related_payments [Array<Straddle::Models::RelatedPayment>, nil] Related payments and their relationship to this charge or payout.
+    end
+  end
+end

data/lib/straddle/models/payment_summary_list.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    # @see Straddle::Resources::Payments#list
+    class PaymentSummaryList < Straddle::Internal::Type::BaseModel
+      # @!attribute data
+      #   Payments returned for this page.
+      #
+      #   @return [Array<Straddle::Models::PaymentSummary>]
+      required :data, -> { Straddle::Internal::Type::ArrayOf[Straddle::PaymentSummary] }
+
+      # @!attribute meta
+      #   Metadata for an API request and a page of results.
+      #
+      #   @return [Straddle::Models::PageMetadata]
+      required :meta, -> { Straddle::PageMetadata }
+
+      # @!attribute response_type
+      #   Shape of the response envelope.
+      #
+      #   - `object` means `data` contains one JSON object.
+      #   - `array` means `data` contains an array of JSON objects.
+      #   - `error` means `error` contains the error details.
+      #   - `none` means the response contains no data.
+      #
+      #   @return [Symbol, Straddle::Models::ResponseType]
+      required :response_type, enum: -> { Straddle::ResponseType }
+
+      # @!method initialize(data:, meta:, response_type:)
+      #   Some parameter documentations has been truncated, see
+      #   {Straddle::Models::PaymentSummaryList} for more details.
+      #
+      #   @param data [Array<Straddle::Models::PaymentSummary>] Payments returned for this page.
+      #
+      #   @param meta [Straddle::Models::PageMetadata] Metadata for an API request and a page of results.
+      #
+      #   @param response_type [Symbol, Straddle::Models::ResponseType] Shape of the response envelope.
+    end
+  end
+end

data/lib/straddle/models/payment_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    # The type of payment.
+    module PaymentType
+      extend Straddle::Internal::Type::Enum
+
+      CHARGE = :charge
+      PAYOUT = :payout
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/straddle/models/payout.rb

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

data/lib/straddle/models/payout_cancel_params.rb

@@ -13,43 +13,47 @@ module Straddle
       required :id, String
 
       # @!attribute reason
-      #   Details about why the payout status was updated.
+      #   Message explaining the payout status change.
       #
-      #   @return [String]
-      required :reason, String
+      #   @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
 
-      # @!method initialize(id:, reason:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @!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] Details about why the payout status was updated.
+      #   @param reason [String, nil] Message explaining the payout 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/payout_configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Models
+    class PayoutConfiguration < Straddle::Internal::Type::BaseModel
+      # @!attribute auto_hold
+      #   Whether to place the payout 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 payout 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(auto_hold: nil, auto_hold_message: nil, sandbox_outcome: nil)
+      #   @param auto_hold [Boolean, nil] Whether to place the payout on hold automatically after creation.
+      #
+      #   @param auto_hold_message [String, nil] Reason for placing the payout on hold automatically.
+      #
+      #   @param sandbox_outcome [Symbol, Straddle::Models::SimulatedPaymentOutcome] Payment will simulate processing if not Standard.
+    end
+  end
+end