Payment
model in Spree tracks payments against Orders. Payments relate to a source
which indicates how the payment was made, and a PaymentMethod
, indicating the processor used for this payment.
When a payment is created, it is given a unique, 8-character identifier. This is used when sending the payment details to the payment processor. Without this identifier, some payment gateways mistakenly reported duplicate payments.
checkout
processing
pending
failed
void
completed
Spree::Payment
model:
Attribute | Description | Example Value |
---|---|---|
number | A unique identifier for the payment. | P123456789 |
source_type | The type of source used for the payment. | Spree::CreditCard |
source_id | The ID of the source used for the payment. | 1 |
amount | The amount of the payment. | 99.99 |
payment_method_id | The ID of the payment method used. | 2 |
state | The current state of the payment (e.g., processing, completed, failed). | completed |
response_code | The response code returned by the payment processor. | AUTH_123456 |
avs_response | The address verification system response code. | D |
PaymentMethod
can have the following attributes:
Attribute | Description | Example |
---|---|---|
type | The subclass of Spree::PaymentMethod this payment method represents. Uses rails single table inheritance feature. | Spree::PaymentMethod::Check |
name | The visible name for this payment method | Check |
description | The description for this payment method | Pay by check. |
active | Whether or not this payment method is active. Set it false to hide it in frontend. | true |
display_on | Determines where the payment method can be visible. Values can be front (Storefr) for Storefront, back for Admin Panel only or both for both. | both |
position | The position of the payment method in lists. Lower numbers appear first. | 1 |
Gateway Option | Description |
---|---|
email and customer | The email address related to the order |
ip | The last IP address for the order |
order_id | The Order’s number attribute, plus the identifier for each payment, generated when the payment is first created |
shipping | The total shipping cost for the order, in cents |
tax | The total tax cost for the order, in cents |
subtotal | The item total for the order, in cents |
currency | The 3-character currency code for the order |
discount | The promotional discount applied to the order |
billing_address | A hash containing billing address information |
shipping_address | A hash containing shipping address information |
Attribute | Description |
---|---|
name | The combined first_name and last_name from the address |
address1 | The first line of the address information |
address2 | The second line of address information |
city | The city of the address |
state | An abbreviated version of the state name or, failing that, the state name itself, from the related State object. If that fails, the state_name attribute from the address. |
country | The ISO name for the country. For example, United States of America is “US”, Australia is “AU”. |
phone | The phone number associated with the address |
Spree::CreditClass
record with the following attributes:
Attribute | Description | Example Value |
---|---|---|
month | The month the credit card expires. Stored as an integer (1-12). | 6 |
year | The year the credit card expires. Stored as a four-digit integer (e.g., 2024). | 2024 |
cc_type | The type of credit card (e.g., Visa, MasterCard). | Visa |
last_digits | The last four digits of the credit card number. | 1234 |
name | The name of the credit card holder as it appears on the card. | John Doe |
gateway_customer_profile_id | The customer profile identifier from the payment gateway. Useful for recurring transactions. | cust_123456789 |
gateway_payment_profile_id | The payment profile identifier from the payment gateway. | paym_987654321 |
gateway_customer_profile_id
and gateway_payment_profile_id
.Payment
object associated with the order has the process!
method called on it (unless payment_required?
for the order returns false
), in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (eg. Spree::CreditCard
), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.
If the PaymentMethod
object is configured to auto-capture payments, then the Payment#purchase!
method will be called, which will call PaymentMethod#purchase
like this:
Payment#authorize!
method will be called, with the same arguments as the purchase
method above:
PaymentMethod
sub-class’ implementation of the purchase
and authorize
methods.
The returned object from both the purchase
and authorize
methods on the payment method objects must be an ActiveMerchant::Billing::Response object. This response object is then stored (in YAML) in the spree_log_entries
table. Log entries can be retrieved with a call to the log_entries
association on any Payment
object, eg.
purchase!
route is taken and is successful, the payment is marked as completed
. If it fails, it is marked as failed
. If the authorize
method is successful, the payment is transitioned to the pending
state so that it can be manually captured later by calling the capture!
method. If it is unsuccessful, it is also transitioned to the failed
state.
Once a payment has been saved, it also updates the order. This may trigger the `payment_state` to change, which would reflect the current payment state of the order. The possible states are: * `balance_due`: Indicates that payment is required for this order * `failed`: Indicates that the last payment for the order failed * `credit_owed`: This order has been paid for in excess of its total * `paid`: This order has been paid for in full.
You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase in the number of such orders could indicate a problem with your credit card gateway and most likely indicates a serious problem affecting customer satisfaction. You should check the latest `log_entries` for the most recent payments in the store if this is happening.
log_entries
on any Spree::Payment
object. To get the Active::Merchant::Billing::Response
out of these Spree::LogEntry
objects, call the details
method, eg.
spree_gateway
gem included in your application’s Gemfile
, these gateways will be selectable in the admin backend for payment methods.
Spree::PaymentMethod
in your app/models
directory:
config/initializers/spree.rb
:
PaymentMethod
can have a display_on
attribute. This attribute can have the following values: front
, back
, or both
. For more granular control which Payment Methods should be available in which Store, you can override the available_for_store?
method in your PaymentMethod
subclass.
available_for_order?
method to control Payment Method visibility for specific Order, eg.