Payment methods

In Solidus, each Spree::PaymentMethod represents one way that your store chooses to accept payments. For example, you may want to set up separate payment methods for PayPal payments and credit card payments.

You can inherit the Spree::PaymentMethod base class when you build your own integration for a payment service provider. For more information about Solidus and payment service providers, see the Payment service providers article.

Spree::PaymentMethod objects have the following attributes:

• type: The subclass of Spree::PaymentMethod that this payment method represents.
• name: The display name for this payment method.
• description: The description for this payment method.
• auto_capture: Determines whether a payment should be captured (true) or only authorized (false) during payment processing. For more information, see Auto-capture .
• preferences: A hash of preferences and their current settings for the current payment method. The available preferences can be changed by setting a different preference_source.
• preference_source: Sets the source for the preferences hash content. Your payment method may require additional preferences for interfacing with a payment service provider. See Preferences for more information.
• active: Sets whether the payment method is active. Set this to false to hide the payment method from customers.
• available_to_users: Determines if the payment method is visible to users.
• available_to_admin: Determines if the payment method is visible to administrators.
• type_before_removal: Contains the previous real payment type, in case type has been removed after switching Payment Service Provider. Defaults to nil. For more information, see the Payment service providers article.

Preferences

Each payment method has a preferences attribute that stores settings as a hash. The preference values get passed to the payment service provider, so your payment method may require additional preferences (like public and private API keys).

The base Spree::PaymentMethod class has just two preferences:

• :server: The name of your server. This defaults to "test".
• :test_mode: Sets whether the payment method can be used for test payments.

Auto-capture

Auto-capture refers to whether the current payment method should attempt to auto-capture the payment immediately. Auto-capture can be enabled or disabled with the boolean attribute #auto_capture on the Spree::PaymentMethod.

When a customer's payment has successfully been processed , and your store has received the payment, the relevant Spree::Payment object's #state should be "captured".

Behaviour when enabled

When auto-capture is enabled, Solidus executes its payment capture flow as soon as the order is completed.

Behaviour when disabled

When disabled, the payment remains uncaptured until a Solidus administrator (or your custom payment method code) manually executes the payment capture flow after some other condition is met. For example, it is conventional to only capture a payment after an order's shipment has been marked as "shipped".

Application-wide auto-capture default

If you have not set the auto_capture attribute for a payment method, it defaults to the value of your store's Spree::Config[:auto_capture] preference.

Set a payment source class

The Spree::PaymentMethod base class has a method: #payment_source_class. It sets the payment source that should be associated with your payment method. When you are creating your own payment method, you need to define a payment_source_class (even if it is nil).

Solidus provides payment sources such as Spree::CreditCard and Spree::StoreCredit. However, payment methods included in Solidus extensions (like solidus_paypal_braintree ) could use a completely custom payment source. (For example, the solidus_paypal_braintree gem uses SolidusPaypalBraintree::Source as the payment source for all payments.)

Built-in payment methods

Solidus does not include working payment methods by default. However, it does offer basic payment methods you can use to help you build out your own integration with a payment service provider.

These payment methods are provided by Solidus:

• Spree::PaymentMethod::Check: A class for processing payments from checks (also spelled: cheques).
• Spree::PaymentMethod::StoreCredit: A class for processing payments from a user's existing Spree::StoreCredit.
• Spree::PaymentMethod::CreditCard: A base class for other typical credit card-based payment methods. It uses Spree::CreditCard as a payment source.

Solidus also provides bogus credit card payment methods for testing purposes:

• Spree::PaymentMethod::BogusCreditCard
• Spree::PaymentMethod::SimpleBogusCreditCard

You can view the source code for all of Solidus's provided payment methods in the /core/app/models/spree/payment_method/ .

The simple bogus credit card method does not support payment profiles.¹