Rewrite overview of Solidus payments system

This commit reduces the barrier to entry for developers getting started
with Solidus's payments system.

It does this by identifying five essential parts of the payments system
and explaining how they fit together to make payments work.

I realize that there are other parts of the system that are not covered
yet. I can imagine additional articles about payments being linked to
from this overview in future pull requests.

guides/payments/overview.md

@@ -1,38 +1,138 @@
 # Overview
 
-Solidus has a highly flexible payments model which allows multiple payment
-methods to be available during checkout. The logic for processing payments is
-decoupled from orders, making it easy to define custom payment methods with
-their own processing logic.
-
-Payment methods typically represent a payment processor. Payment methods will
-process credit card payments, and may also include non credit card payment
-methods such as Check or StoreCredit, which are provided in Solidus by default.
-
-The `Payment` model in Solidus 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.
-
-An explanation of the different states:
-
-* `checkout`: Checkout has not been completed
-* `processing`: The payment is being processed (temporary – intended to prevent double submission)
-* `pending`: The payment has been processed but is not yet complete (ex. authorized but not captured)
-* `failed`: The payment was rejected (ex. credit card was declined)
-* `void`: The payment should not be counted against the order
-* `completed`: The payment is completed. Only payments in this state count against the order total
-
-The state transition for these is handled by the processing code within Solidus;
-however, you are able to call the event methods yourself to reach these states.
-The event methods are:
-
-* `started_processing`
-* `failure`
-* `pend`
-* `complete`
-* `void`
-* `invalidate`
+Solidus has a flexible payments system that allows multiple payment methods to
+be used during checkout.
+
+The logic for processing payments is decoupled from Solidus's orders system.
+This allows you to easily define your own payment methods with custom
+processing logic.
+
+The payments system has many moving parts. The following lists summarizes the
+essential parts of the payments system:
+
+1. **Payment service providers**. Before your store can have a functional
+   payments system, you need create an account with a payment service provider
+   Braintree or Stripe.
+2. **Payment methods**. A store may have multiple `Spree::PaymentMethod`s
+   configured. Payment methods send payment information to a payment service
+   provider.
+3. **Payments**. After a customer submits their payment details for an order, a
+   new `Spree::Payment` object is created.
+4. **Payment sources**. `Spree::Payment`s can have a payment source. The source
+   depends on the payment method that is used. For example, the payment source
+   could be a `Spree::CreditCard`, `Spree::StoreCredit`, or a non-`Spree` model
+   provided by your payment service provider integration.
+5. **Payment processing**. Once an order is complete, a payment can be
+   processed. At this point, the `Spree::Payment::Processing` class calls on
+   `Spree::PaymentMethod` and attempts to capture the payment.
+
+The complexity of your store's payments system depends on the payment gateways
+that you use and the amount of payment methods that you need to support.
+
+The rest of this article summarizes these parts of the system.
+
+## Payment service providers (PSPs)
+
+In order for you to successfully process payments, your  `Spree::PaymentMethod`s
+need to send information to a [payment service provider][psp] (PSP).
+
+The Solidus community has created a number of Solidus extensions to connect you
+popular PSPs like Braintree, Adyen, Affirm, and Paybright.
+
+Typically, PSP integrations use the `Spree::PaymentMethod` base class to build
+out to the PSP's specifications and API.
+
+Solidus is not built to process payments by itself, and it does not include any
+integrations for popular PSPs. You must install an extension or create your own
+integration.
+
+<!-- TODO:
+  # Once an article about payment service providers is merged, uncomment this
+  link.
+
+  For more information about payment service providers in Solidus, see the
+  [Payment service providers][payment-service-providers] article.
+
+  [payment-service-providers]: payment-service-providers.md
+-->
+
+[psp]: https://en.wikipedia.org/wiki/Payment_service_provider
+
+## Payment methods
+
+In Solidus, each `Spree::PaymentMethod` represents a 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.
+
+Solidus does not include working payment methods by default. Typically, you need
+to integrate your payment method with a [payment service
+provider](#payment-service-providers-psps).
+
+Solidus includes bogus credit card methods for testing, a basic
+`Spree::PaymentMethod::CreditCard` class that you can use for modeling your own
+credit card payment methods, and some other basic payment methods.
+
+For more information, see the [Payment methods][payment-methods] article.
+
+[payment-methods]: payment_method.md
+
+## Payments
+
+The `Spree::Payment` model in Solidus tracks payments. A new payment is created
+once the customer has submitted their payment details during checkout.
+
+Payments relate to a specific `Spree::Order`, as well as one of your available
+`Spree::PaymentMethod`s and a payment source (which could be a
+`Spree::CreditCard`, a `Spree::StoreCredit` or some other non-`Spree` model).
+
+Note that a payment being created does not mean that a payment has been made
+successfully. The `Spree::Payment` model has a state machine that tracks the
+status of a payment. Once the payment is processed by your payment service
+provider, the state could become `complete`, `failed`, `void`, and so on.
+
+
+<!-- TODO:
+  # Once a Spree::Payments article is merged, uncomment this link.
+
+  For more information about payments, see the [Payments][payments] article.
+-->
+
+[payments]: payments.md
+
+## Payment sources
+
+Each `Spree::Payment` tracks a payment source. The payment source depends on the
+types of payments you accept for each payment method.
+
+For example, if you use Solidus's built-in `Spree::PaymentMethod::CreditCart`
+payment method, the payment source class should always be set to
+`Spree::CreditCard`.
+
+Your payment methods may have more complex payment source classes. For example,
+if you use the [`solidus_paypal_braintree`][solidus-paypal-braintree] gem,
+payments made using your Braintree payment methods have the payment source
+`SolidusPaypalBraintree::Source`. However, the `SolidusPaypalBraintree::Source`
+class has a `payment_type` method that could have a value of `ApplePay`,
+`CreditCard` or `PayPalAccount`.
+
+<!-- TODO:
+  # Once an article about payment sources is merged, uncomment this link.
+
+  For more information about payment sources, see the [Payment
+  methods][payment-sources] article.
+-->
+
+[payment-sources]: payment-sources.md
+[solidus-paypal-braintree]: https://github.com/solidusio/solidus_paypal_braintree
+
+## Payment processing
+
+The `Spree::Payment::Processing` class's `process!` method can can operate on
+completed orders. It attempts to capture orders, invoking the customer's
+selected `Spree::PaymentMethod` and sending payment details to the payment
+service provider.
+
+For more information about processing payments, see the [Payment
+processing][payment-processing] article.
+
+[payment-processing]: payment_processing.md