Class: Spree::PaymentMethod

Inherits:
Object
  • Object
show all
Includes:
DisplayOn, Metadata, Metafields, Security::PaymentMethods, StoreScopedResource
Defined in:
app/models/spree/payment_method.rb

Direct Known Subclasses

Gateway, Check, StoreCredit

Defined Under Namespace

Classes: Check, StoreCredit, WebhookSignatureError

Constant Summary

Constants included from DisplayOn

DisplayOn::DISPLAY

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Metadata

#metadata, #metadata=, #public_metadata=

Class Method Details

.find_with_destroyed(*args) ⇒ Object 



148
149
150
 
# File 'app/models/spree/payment_method.rb', line 148

def self.find_with_destroyed(*args)
  unscoped { find(*args) }
end

.providers ⇒ Object 



35
36
37
 
# File 'app/models/spree/payment_method.rb', line 35

def self.providers
  Spree.payment_methods
end

Instance Method Details

#auto_capture? ⇒ Boolean

Returns:



178
179
180
 
# File 'app/models/spree/payment_method.rb', line 178

def auto_capture?
  auto_capture.nil? ? Spree::Config[:auto_capture] : auto_capture
end

#available_for_order?(order) ⇒ Boolean

Custom PaymentMethod/Gateway can redefine this method to check method availability for concrete order.

Returns:



196
197
198
 
# File 'app/models/spree/payment_method.rb', line 196

def available_for_order?(order)
  !order.covered_by_store_credit?
end

#available_for_store?(store) ⇒ Boolean

Returns:



200
201
202
203
204
 
# File 'app/models/spree/payment_method.rb', line 200

def available_for_store?(store)
  return true if store.blank?

  store_ids.include?(store.id)
end

#cancel(_response) ⇒ Object

Raises:

  • (::NotImplementedError) 


186
187
188
 
# File 'app/models/spree/payment_method.rb', line 186

def cancel(_response)
  raise ::NotImplementedError, 'You must implement cancel method for this payment method.'
end

#complete_payment_session(payment_session:, params: {}) ⇒ Object

Completes a payment session via the provider. Override in gateway subclasses to implement provider-specific session completion.

Responsibilities:

  • Verify payment status with the provider

  • Create/update the Spree::Payment record

  • Patch order data from provider (e.g. wallet billing address)

  • Transition payment session to completed/failed

Must NOT complete the order — that is handled by Carts::Complete (called by the frontend or by the webhook handler).

Raises:

  • (::NotImplementedError) 


83
84
85
 
# File 'app/models/spree/payment_method.rb', line 83

def complete_payment_session(payment_session:, params: {})
  raise ::NotImplementedError, 'You must implement complete_payment_session method for this gateway.'
end

#complete_payment_setup_session(setup_session:, params: {}) ⇒ Object

Completes a payment setup session via the provider. Override in gateway subclasses to implement provider-specific setup session completion.

Raises:

  • (::NotImplementedError) 


132
133
134
 
# File 'app/models/spree/payment_method.rb', line 132

def complete_payment_setup_session(setup_session:, params: {})
  raise ::NotImplementedError, "#{self.class.name} does not implement #complete_payment_setup_session"
end

#confirmation_required? ⇒ Boolean

Returns:



152
153
154
 
# File 'app/models/spree/payment_method.rb', line 152

def confirmation_required?
  false
end

#create_payment_session(order:, amount: nil, external_data: {}) ⇒ Object

Creates a payment session via the provider. Override in gateway subclasses to implement provider-specific session creation.

Raises:

  • (::NotImplementedError) 


62
63
64
 
# File 'app/models/spree/payment_method.rb', line 62

def create_payment_session(order:, amount: nil, external_data: {})
  raise ::NotImplementedError, 'You must implement create_payment_session method for this gateway.'
end

#create_payment_setup_session(customer:, external_data: {}) ⇒ Object

Creates a payment setup session via the provider for saving a payment method. Override in gateway subclasses to implement provider-specific setup session creation.

Raises:

  • (::NotImplementedError) 


126
127
128
 
# File 'app/models/spree/payment_method.rb', line 126

def create_payment_setup_session(customer:, external_data: {})
  raise ::NotImplementedError, "#{self.class.name} does not implement #create_payment_setup_session"
end

#default_name ⇒ Object 



140
141
142
 
# File 'app/models/spree/payment_method.rb', line 140

def default_name
  self.class.name.demodulize.titleize.gsub(/Gateway/, '').strip
end

#method_type ⇒ Object 



136
137
138
 
# File 'app/models/spree/payment_method.rb', line 136

def method_type
  type.demodulize.downcase
end

#parse_webhook_event(raw_body, headers) ⇒ Hash?

Parses an incoming webhook payload from the payment provider. Override in gateway subclasses to implement provider-specific webhook parsing.

Parameters:

  • raw_body (String) —

    the raw request body

  • headers (Hash) —

    the request headers

Returns:

  • (Hash, nil) —

    normalized result or nil for unsupported events { action: :captured/:authorized/:failed/:canceled,

    payment_session: <Spree::PaymentSession>,
metadata: {} }

Raises:



97
98
99
 
# File 'app/models/spree/payment_method.rb', line 97

def parse_webhook_event(raw_body, headers)
  raise ::NotImplementedError, 'You must implement parse_webhook_event method for this gateway.'
end

#payment_icon_name ⇒ Object 



144
145
146
 
# File 'app/models/spree/payment_method.rb', line 144

def payment_icon_name
  type.demodulize.gsub(/(^Spree::Gateway::|Gateway$)/, '').downcase.gsub(/\s+/, '').strip
end

#payment_profiles_supported? ⇒ Boolean

Returns:



156
157
158
 
# File 'app/models/spree/payment_method.rb', line 156

def payment_profiles_supported?
  false
end

#payment_session_class ⇒ Object

The class used for payment sessions with this payment method. Override in gateway subclasses to provide a provider-specific session class that inherits from Spree::PaymentSession (STI). nil means the payment method doesn’t support payment sessions.



56
57
58
 
# File 'app/models/spree/payment_method.rb', line 56

def payment_session_class
  nil
end

#payment_setup_session_class ⇒ Object

The class used for payment setup sessions with this payment method. Override in gateway subclasses to provide a provider-specific session class.



120
121
122
 
# File 'app/models/spree/payment_method.rb', line 120

def payment_setup_session_class
  nil
end

#payment_source_class ⇒ Object

The class that will process payments for this payment type, used for @payment.source e.g. CreditCard in the case of a the Gateway payment type nil means the payment method doesn’t require a source e.g. check

Raises:

  • (::NotImplementedError) 


46
47
48
49
50
 
# File 'app/models/spree/payment_method.rb', line 46

def payment_source_class
  return unless source_required?

  raise ::NotImplementedError, 'You must implement payment_source_class method for this gateway.'
end

#provider_class ⇒ Object

Raises:

  • (::NotImplementedError) 


39
40
41
 
# File 'app/models/spree/payment_method.rb', line 39

def provider_class
  raise ::NotImplementedError, 'You must implement provider_class method for this gateway.'
end

#public_preferences ⇒ Object 



206
207
208
209
210
 
# File 'app/models/spree/payment_method.rb', line 206

def public_preferences
  public_preference_keys.each_with_object({}) do |key, hash|
    hash[key] = preferences[key]
  end
end

#reusable_sources(_order) ⇒ Object

Custom gateways should redefine this method. See Gateway implementation as an example



174
175
176
 
# File 'app/models/spree/payment_method.rb', line 174

def reusable_sources(_order)
  []
end

#session_required? ⇒ Boolean

Returns:



164
165
166
 
# File 'app/models/spree/payment_method.rb', line 164

def session_required?
  false
end

#setup_session_supported? ⇒ Boolean

Whether this payment method supports setup sessions (saving payment methods for future use). Override in gateway subclasses that support tokenization without a payment.

Returns:



114
115
116
 
# File 'app/models/spree/payment_method.rb', line 114

def setup_session_supported?
  false
end

#show_in_admin? ⇒ Boolean

Returns:



168
169
170
 
# File 'app/models/spree/payment_method.rb', line 168

def show_in_admin?
  true
end

#source_required? ⇒ Boolean

Returns:



160
161
162
 
# File 'app/models/spree/payment_method.rb', line 160

def source_required?
  true
end

#store_credit? ⇒ Boolean

Returns:



190
191
192
 
# File 'app/models/spree/payment_method.rb', line 190

def store_credit?
  self.class == Spree::PaymentMethod::StoreCredit
end

#supports?(_source) ⇒ Boolean

Returns:



182
183
184
 
# File 'app/models/spree/payment_method.rb', line 182

def supports?(_source)
  true
end

#update_payment_session(payment_session:, amount: nil, external_data: {}) ⇒ Object

Updates an existing payment session via the provider. Override in gateway subclasses to implement provider-specific session updates.

Raises:

  • (::NotImplementedError) 


68
69
70
 
# File 'app/models/spree/payment_method.rb', line 68

def update_payment_session(payment_session:, amount: nil, external_data: {})
  raise ::NotImplementedError, 'You must implement update_payment_session method for this gateway.'
end

#webhook_url ⇒ String?

Returns the webhook URL for this payment method.

Returns:

  • (String, nil) 


103
104
105
106
107
108
 
# File 'app/models/spree/payment_method.rb', line 103

def webhook_url
  store = stores.first
  return nil unless store

  "#{store.url_or_custom_domain}/api/v3/webhooks/payments/#{prefixed_id}"
end