Integrate new UserCancelled exception

This adds documentation and basic handling for it.

docs/source/howto/how_to_integrate_payment.rst

@@ -62,6 +62,11 @@ common exceptions which can occur:
   problems such as invalid bankcard number, not enough funds in account - that kind
   of thing.
 
+* ``oscar.apps.payment.exceptions.UserCancelled`` During many payment flows,
+  the user is able to cancel the process. This should often be treated
+  differently from a payment error, e.g. it might not be appropriate to offer
+  to retry the payment.
+
 * ``oscar.apps.payment.exceptions.PaymentError``  For *unanticipated* payment
   errors such as the payment gateway not responding or being badly configured.
 

docs/source/releases/v0.8.rst

@@ -211,6 +211,9 @@ Minor changes
   expected. There's currently no frontend or dashboard support for it, as there
   is no good default behaviour.
 
+* Payment extensions can now raise a ``UserCancelled`` payment exception to
+  differentiate between the intended user action and any other errors.
+
 * Oscar has a new dependency, django-tables2_. It's a handy library that helps
   when displaying tabular data, allowing sorting, etc. It also makes it easier
   to adapt e.g. the product list view in the dashboard to additional fields.

oscar/apps/checkout/views.py

@@ -19,9 +19,10 @@
 UserAddressForm = get_class('address.forms', 'UserAddressForm')
 Repository = get_class('shipping.repository', 'Repository')
 AccountAuthView = get_class('customer.views', 'AccountAuthView')
-RedirectRequired, UnableToTakePayment, PaymentError \
+RedirectRequired, UnableToTakePayment, UserCancelled, PaymentError \
     = get_classes('payment.exceptions', ['RedirectRequired',
                                          'UnableToTakePayment',
+                                         'UserCancelled',
                                          'PaymentError'])
 UnableToPlaceOrder = get_class('order.exceptions', 'UnableToPlaceOrder')
 OrderPlacementMixin = get_class('checkout.mixins', 'OrderPlacementMixin')
@@ -569,6 +570,17 @@ def submit(self, user, basket, shipping_address, shipping_method,  # noqa (too c
             # Redirect required (eg PayPal, 3DS)
             logger.info("Order #%s: redirecting to %s", order_number, e.url)
             return http.HttpResponseRedirect(e.url)
+        except UserCancelled as e:
+            # The user willingly cancelled the payment flow. This type of
+            # exception is supposed to set a friendly error
+            # message that makes sense to the customer.
+            msg = six.text_type(e)
+            logger.info(
+                "Order #%s: user cancelled the payment process (%s).",
+                order_number, msg)
+            self.restore_frozen_basket()
+            return self.render_preview(
+                self.request, error=msg, **payment_kwargs)
         except UnableToTakePayment as e:
             # Something went wrong with payment but in an anticipated way.  Eg
             # their bankcard has expired, wrong card number - that kind of