Rewrite payment processing documentation; add Spree::Order#payment_states documentation #2624

benjaminwil · 2018-03-09T22:10:13Z

I have rewrote the payments/payment_processing.md article and removed/moved some of the content from it.

The new article goes more into detail about the authorize! and purchase! methods used for payment processing.
It moves information about payment states (on Spree::Orders) to a new article in the future orders/ section of the documentation.
It removes information about logging. Later, I will reintroduce documetation about logging in a new section.
I made more linear descriptions of what is involved in Solidus's processing process.

This is a pretty dense article. Payment processing is confusing. In the future, I'd like to take this article in a more tutorialized direction set up a payment method that uses a real payment service provider like Stripe.

This is part a larger project to improve Solidus's documentation. See this gist with the high-level table of contents. Where and how this documentation will exist is still up for discussion.

gmacdougall · 2018-04-17T15:29:09Z

guides/orders/payment-states.html.markdown

+  in the future.
+-->
+
+You can check the state of the `Spree::Payment` associated with any order:


There are two ways that the state of payments are represented. There is the state of the payment status for the order, which is what is described below and the state of an individual payment.

As an example:

An order for $100 has a single payment of $50 that is complete. The status of the one payment is complete, but the order is in a payment state of balance_due.

If the order has multiple payments:

$80 - failed

$80 - completed

$80 - completed

The order will be in a payment_state of credit owed.

Refunds play in to this as well as those can bring the payment state back in to a state of pair if the customer overpaid in the above case. This is complicated enough that it needs an explanation of what the difference between order payment_state and payment's state is.

I am going to include an example like this, thank you.

gmacdougall · 2018-04-18T16:24:52Z

guides/orders/payment-states.md

+- `credit_owed`: This state indicates that the order has been paid for in excess
+  of its total.
+- `paid`: This state indicates that the order has been paid for in full. All of
+  the `Spree::Payment`s on the order have been satisfied.


An order can also be in the state void

gmacdougall · 2018-04-18T16:25:06Z

guides/orders/payment-states.md

+## Completed payments
+
+The `Spree::Order`'s `payment_state` can only be `paid` if each `Spree::Payment`
+has a state of `completed`.


This is not true.

DanielePalombo

Great work. I leave a comment about the Spree::PaymentMethod#gateway.

DanielePalombo · 2018-04-20T15:04:14Z

guides/orders/payment-states.md

+
+The `payment_state` method can be very useful if you have built out your own
+integrations with a payment service provider. For example, a sudden increase in
+orders with with `payment_state` of `failed` may indicate a problem with your


with is repeated two times

DanielePalombo · 2018-04-20T16:23:16Z

guides/payments/payment-processing.md

+  `purchase!` is called, meaning the payment is authorized and captured. This
+occurs even if the payment's state is already `completed`.
+- If the `Spree::PaymentMethod`'s `auto_capture` attribute is set to `false`,
+  then the payment is authorized but not captured. This occurs even if if the


if repeted twice

DanielePalombo · 2018-04-20T16:23:19Z

guides/payments/payment-processing.md

+
+- `Spree::PaymentMethod` has a similar interface to API provided by
+  [active_merchant][active-merchant].
+- The `Spree::PaymentMethod#gateway` method uses the


Maybe I'm wrong, but seems like gateway method

solidus/core/app/models/spree/payment_method.rb

Lines 130 to 137 in f2a921e

def gateway

gateway_options = options

gateway_options.delete :login if gateway_options.key?(:login) && gateway_options[:login].nil?

if gateway_options[:server]

ActiveMerchant::Billing::Base.mode = gateway_options[:server].to_sym

end

@gateway ||= gateway_class.new(gateway_options)

end

returns an instance of this payment method. Gateway_options is the variable provided to the gateway class.

Thank you for making a note of this. While the options value is created by the Spree::Payment::Processing#gateway_options the way that I wrote this didn't really make sense.

I'm going to simplify it shortly and leave explanations to the "Gateway options" section below.

Currently, the payment_processing.md article has a list of payment states. While it is useful in that context, this is related more to orders than to payments. I'm stripping it out of the article and putting it in the orders section of documentation as a new stub article.

- Add `void` to list of order payment states - Create better explanations and examples for payment states in the docs.

kennyadsl added the documentation label Mar 10, 2018

gmacdougall requested changes Apr 17, 2018

View reviewed changes

benjaminwil force-pushed the payment_processing_documentation branch from 53f77c4 to 2d17116 Compare April 18, 2018 01:43

benjaminwil changed the title ~~Rewrite payment processing documentation~~ Rewrite payment processing documentation; add Spree::Order#payment_states documentation Apr 18, 2018

gmacdougall requested changes Apr 18, 2018

View reviewed changes

DanielePalombo reviewed Apr 20, 2018

View reviewed changes

benjaminwil force-pushed the payment_processing_documentation branch from 3132a7d to a15066b Compare April 20, 2018 20:46

benjaminwil and others added 9 commits April 20, 2018 14:33

Rewrite payment processing article

4e78b5a

Rename payment processing article

37a3936

Reintroduce gateway options into article

a553780

Rename payment states article

5cfeac5

Further document Spree::Order payment states

0b436a8

Add Spree::Order#payment_states and refunds-related docs

50d9256

Improve docs for Spree::Order#payment_states

654c755

- Add `void` to list of order payment states - Create better explanations and examples for payment states in the docs.

Improve payment processing docs; fix typos

58cce89

benjaminwil force-pushed the payment_processing_documentation branch from a15066b to 58cce89 Compare April 20, 2018 21:33

gmacdougall approved these changes Apr 25, 2018

View reviewed changes

gmacdougall merged commit c518327 into solidusio:master Apr 25, 2018

benjaminwil deleted the payment_processing_documentation branch April 30, 2018 18:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite payment processing documentation; add Spree::Order#payment_states documentation #2624

Rewrite payment processing documentation; add Spree::Order#payment_states documentation #2624

benjaminwil commented Mar 9, 2018 •

edited

Loading

gmacdougall Apr 17, 2018

benjaminwil Apr 18, 2018

gmacdougall Apr 18, 2018

gmacdougall Apr 18, 2018

DanielePalombo left a comment

DanielePalombo Apr 20, 2018

DanielePalombo Apr 20, 2018

DanielePalombo Apr 20, 2018 •

edited

Loading

benjaminwil Apr 20, 2018

	def gateway
	gateway_options = options
	gateway_options.delete :login if gateway_options.key?(:login) && gateway_options[:login].nil?
	if gateway_options[:server]
	ActiveMerchant::Billing::Base.mode = gateway_options[:server].to_sym
	end
	@gateway \|\|= gateway_class.new(gateway_options)
	end

Rewrite payment processing documentation; add Spree::Order#payment_states documentation #2624

Rewrite payment processing documentation; add Spree::Order#payment_states documentation #2624

Conversation

benjaminwil commented Mar 9, 2018 • edited Loading

gmacdougall Apr 17, 2018

Choose a reason for hiding this comment

benjaminwil Apr 18, 2018

Choose a reason for hiding this comment

gmacdougall Apr 18, 2018

Choose a reason for hiding this comment

gmacdougall Apr 18, 2018

Choose a reason for hiding this comment

DanielePalombo left a comment

Choose a reason for hiding this comment

DanielePalombo Apr 20, 2018

Choose a reason for hiding this comment

DanielePalombo Apr 20, 2018

Choose a reason for hiding this comment

DanielePalombo Apr 20, 2018 • edited Loading

Choose a reason for hiding this comment

benjaminwil Apr 20, 2018

Choose a reason for hiding this comment

benjaminwil commented Mar 9, 2018 •

edited

Loading

DanielePalombo Apr 20, 2018 •

edited

Loading