Add a user guide on payments

doc/conf.py

@@ -55,16 +55,17 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'pretix'
-copyright = '2014-2016, Raphael Michel'
+copyright = '2014-2017, Raphael Michel'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.0.0'
+from pretix import __version__
+version = '.'.join(__version__.split('.')[:2])
 # The full version, including alpha/beta/rc tags.
-release = '0.0.0'
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/development/implementation/models.rst

@@ -92,5 +92,3 @@ Vouchers
 
 .. autoclass:: pretix.base.models.Voucher
    :members:
-
-.. _cleanerversion: https://github.com/swisscom/cleanerversion

doc/index.rst

@@ -6,6 +6,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   user/index
    admin/index
    development/index
    plugins/index

doc/user/index.rst

@@ -0,0 +1,9 @@
+User Guide
+==========
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   payments/index

doc/user/payments/banktransfer.rst

@@ -0,0 +1,31 @@
+.. _`banktransfer`:
+
+Bank transfer
+=============
+
+To accept payments with bank transfer, you only need to fill one important field in pretix' settings: In "Bank
+account details" you should specify everything one needs to know to transfer money to you, e.g. your IBAN and BIC,
+the name of your bank and for international transfers, preferably also your address and the bank's address.
+
+pretix will automatically tell the user to include the order code in the payment reference so incoming transfers can
+automatically be matched to payments.
+
+Importing payment data
+----------------------
+
+The easiest way to import payment data is to download a CSV file from your online banking. Most banks provide a CSV
+export of some sort. You can go to "Import bank data" in pretix to upload a new file:
+
+.. image:: img/bank1.png
+
+If you upload a file for the first time, pretix will not know what information is contained in which column as every
+bank builds completely different CSV files. Therefore, pretix will ask you for that information. It will show you the
+data of the file you imported and ask you to define the column's meanings. You can select one column that contains
+the payment date and one that contains the paid amount. You can select multiple columns that contain information
+about the payer or the payment reference. All other columns will be ignored.
+
+Once you continue, pretix will try to match the payments to the respective orders automatically. It will tell you how
+many orders could be processed correctly and how many could not. You can then go back to the upload page to see all
+transfers from your bank statement that are not yet matched to an order. Using the input field and the buttons on the
+left of each transaction, you can manually enter an order code to match it to or just discard it from the list, e.g.
+if the transaction is not related to the event at all.

doc/user/payments/fees.rst

@@ -0,0 +1,52 @@
+Payment method fees
+===================
+
+Most external payment providers like PayPal or Stripe charge substantial fees for your service. In general, you have
+two options to deal with this:
+
+1. Pay the fees yourself
+
+2. Add the fees to your customer's total
+
+The choice totally depends on you and what your customers expect from you. Option two might be appropriate if you
+offer different payment methods and want to encourage your customers to use the ones that come you cheaper, but you
+might also decide to go for option one to make it easier for customers who don't have the option.
+
+If you go for the second option, you can configure pretix to charge the payment method fees to your user. You can
+define both an absolute fee as well as a percental fee based on the order total. If you do so, there are two
+different ways in which pretix can calculate the fee. Normally, it is fine to just go with the default setting, but
+in case you are interested, here are all the details:
+
+Payment fee calculation
+-----------------------
+
+If you configure a fee for a payment method, there are two possible ways for us to calculate this. Let's
+assume that your payment provider, e.g. PayPal, charges you 5 % fees and you want to charge your users the
+same 5 %, such that for a ticket with a list price of 100 € you will get your full 100 €.
+
+**Method A: Calculate the fee from the subtotal and add it to the bill.**
+
+    For a ticket price of 100 €, this will lead to the following calculation:
+
+    ============================================== ============
+    Ticket price                                       100.00 €
+    pretix calculates the fee as 5 % of 100 €           +5.00 €
+    Subtotal that will be paid by the customer         105.00 €
+    PayPal calculates its fee as 5 % of 105 €           -5.25 €
+    End total that is on your bank account          **99.75 €**
+    ============================================== ============
+
+**Method B (default): Calculate the fee from the total value including the fee.**
+
+    For a ticket price of 100 €, this will lead to the following calculation:
+
+    ===================================================== =============
+    Ticket price                                               100.00 €
+    pretix calculates the fee as 100/(100 - 5) % of 100 €       +5.26 €
+    Subtotal that will be paid by the customer                 105.26 €
+    PayPal calculates its fee as 5 % of 105 €                   -5.26 €
+    End total that is on your bank account                 **100.00 €**
+    ===================================================== =============
+
+    Due to the various rounding steps performed by pretix and by the payment provider, the end total on
+    your bank account might stil vary by one cent.

doc/user/payments/index.rst

@@ -0,0 +1,14 @@
+Accepting payments
+==================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   fees
+   paypal
+   stripe
+   banktransfer
+

doc/user/payments/overview.rst

@@ -0,0 +1,34 @@
+Payment method overview
+=======================
+
+pretix allows you to accept payments using a variety of payment methods to fit the needs of very different events.
+This page gives you a short overview over them and links to more detailled descriptions in some cases.
+
+Payment methods are built as pretix plugins. For this reason, you might first need to enable a certain plugin at
+"Settings" → "Plugins" in your event settings. Then, you can configure them in detail at "Settings" -> "Payment".
+
+If you host pretix on your own server, you might need to install a plugin first for some of the payment methods listed
+on this page as well as for additional ones.
+
+:ref:`stripe`
+    Stripe is a US-based company that offers you an easy way to accept credit card payments from all over the world.
+    To accept payments with Stripe, you need to have a Stripe merchant account that is easy to create. Click on the link
+    above to get more details about the Stripe integration into pretix.
+
+:ref:`paypal`
+    If you want to accept online payments via PayPal, you can do so using pretix. You will need a PayPal merchant
+    account and it is a little bit complicated to obtain the required technical details, but we've got you covered.
+    Click on the link above to learn more.
+
+:ref:`banktransfer`
+    Classical IBAN wire transfers are a common payment method in central Europe that has the large benefit that it
+    often does not cause any additional fees. However, it requires you to invest some more effort as you need to
+    check your bank account for incoming payments regularly. We provide some tools to make this easier for you.
+
+SEPA debit
+    In some Europen countries, a very popular online payment method is SEPA direct debit. If you want to offer this
+    option in your pretix ticket shop, we provide a convenient plugin that allows users to enter their SEPA bank
+    account details and issue a SEPA mandate. You will then need to regularly download a SEPA XML file from pretix
+    and upload it to your bank's interface to actually perform the debits.
+
+

doc/user/payments/paypal.rst

@@ -0,0 +1,50 @@
+.. _`paypal`:
+
+PayPal
+======
+
+To integrate PayPal with pretix, you first need to have an active PayPal merchant account. If you do not already have a
+PayPal account, you can create one on `paypal.com`_.
+If you look into pretix' settings, you are required to fill in two keys:
+
+.. image:: img/paypal_pretix.png
+
+Unfortunately, it is not straightforward how to get those keys from PayPal's website. In order to do so, you
+need to go to `developer.paypal.com`_ to link the account to your pretix event.
+Click on "Log In" in the top-right corner and log in with your PayPal account.
+
+.. image:: img/paypal2.png
+
+Then, click on "Dashboard" in the top-right corner.
+
+.. image:: img/paypal3.png
+
+In the dashboard, scroll down until you see the headline "REST API Apps". Click "Create App".
+
+.. image:: img/paypal4.png
+
+Enter any name for the application that helps you to identify it later. Then confirm with "Create App".
+
+.. image:: img/paypal5.png
+
+On the next page, before you do anything else, switch the mode on the right to "Live" to get the correct keys.
+Then, copy the "Client ID" and the "Secret" and enter them into the appropriate fields in the payment settings in
+pretix.
+
+.. image:: img/paypal6.png
+
+Finally, we need to create a webhook. The webhook tells PayPal to notify pretix e.g. if a payment gets cancelled so
+pretix can cancel the ticket as well. If you have multiple events connected to your PayPal account, you need multiple
+webhooks. To create one, scroll a bit down and click "Add Webhook".
+
+.. image:: img/paypal7.png
+
+Then, enter the webhook URL that you find on the pretix settings page. It should look similar to the one in the
+screenshot but contain your event name. Tick the box "All events" and save.
+
+.. image:: img/paypal8.png
+
+That's it, you are ready to go!
+
+.. _paypal.com: https://www.paypal.com/webapps/mpp/account-selection
+.. _developer.paypal.com: https://developer.paypal.com/

doc/user/payments/stripe.rst

@@ -0,0 +1,28 @@
+.. _stripe:
+
+Stripe
+======
+
+To integrate Stripe with pretix, you first need to have an active Stripe merchant account. If you do not already have a
+Stripe account, you can create one on `stripe.com`_. Then, click on "API" in the left navigation of the Stripe
+Dashboard. As you can see in the following screenshot, you will be presented with two sets of API keys, one for test
+and one for live payments. In each set, there is a secret and a publishable keys.
+
+.. image:: img/stripe1.png
+
+Choose one of the two sets and copy the two keys to the appropriate fields in pretix' settings. To perform actual
+payments, you will need to use the live keys, but you can use the test keys to test the payment flow before you go live.
+In test mode, you cannot use your real credit card, but only `test cards`_ like ``4242424242424242`` that you can
+find in Stripe's documentation.
+
+If you want Stripe to notify pretix automatically once a payment gets cancelled, so pretix can cancel the ticket as
+well, you need to create a so-called webhook. To do so, click "Webhooks" on top of the page in the Stripe dashboard
+that you are currently on. Then, click "Add endpoint" and enter the URL that you find directly below the key
+configuration in pretix' settings.
+
+.. image:: img/stripe2.png
+
+Again, you can choose between live mode and test mode here.
+
+.. _stripe.com: https://dashboard.stripe.com/register
+.. _test cards: https://stripe.com/docs/testing#cards

src/pretix/base/payment.py

@@ -150,9 +150,9 @@ class BasePaymentProvider:
              forms.BooleanField(
                  label=_('Calculate the fee from the total value including the fee.'),
                  help_text=_('We recommend you to enable this if you want your users to pay the payment fees of your '
-                             'payment provider. <a href="/control/help/payment/fee_reverse" target="_blank">Click here '
+                             'payment provider. <a href="{docs_url}" target="_blank">Click here '
                              'for detailled information on what this does.</a> Don\'t forget to set the correct fees '
-                             'above!'),
+                             'above!').format(docs_url='https://docs.pretix.eu/en/latest/user/payments/fees.html'),
                  required=False
              )),
             ('_invoice_text',

src/pretix/control/templates/pretixcontrol/help/base.html

@@ -1,7 +0,0 @@
-{% extends "pretixcontrol/base.html" %}
-{% load i18n %}
-{% block content %}
-    <h1>{% trans "Help center" %}</h1>
-    {% block inner %}
-    {% endblock %}
-{% endblock %}

src/pretix/control/templates/pretixcontrol/help/payment/fee_reverse.html

@@ -1,68 +0,0 @@
-{% extends "pretixcontrol/help/base.html" %}
-{% block title %}Payment fee calculation{% endblock %}
-{% block inner %}
-    <h2>Payment fee calculation</h2>
-    <p>
-        If you configure a fee for a payment method, there are two possible ways for us to calculate this. Let's
-        assume that your payment provider, e.g. PayPal, charges you 5 % fees and you want to charge your users the
-        same 5 %, such that for a ticket with a list price of 100 € you will get your full 100 €.
-    </p>
-    <ul>
-        <li>
-            <strong>Method A: Calculate the fee from the subtotal and add it to the bill.</strong> For a ticket price of
-            100 €, this will lead to the following calculation:
-            <table class="table helper-width-auto">
-                <tr>
-                    <td>Ticket price</td>
-                    <td class="text-right">100.00 €</td>
-                </tr>
-                <tr>
-                    <td>pretix calculates the fee as 5% of 100 €</td>
-                    <td class="text-right">+ 5.00 €</td>
-                </tr>
-                <tr>
-                    <td>Subtotal that will be paid by the customer</td>
-                    <td class="text-right">105.00 €</td>
-                </tr>
-                <tr>
-                    <td>PayPal calculates its fee as 5% of 105 €</td>
-                    <td class="text-right">- 5.25 €</td>
-                </tr>
-                <tr>
-                    <td>End total that is on your bank account</td>
-                    <td class="text-right"><strong>99.75 €</strong></td>
-                </tr>
-            </table>
-        </li>
-        <li>
-            <strong>Method B (default): Calculate the fee from the total value including the fee.</strong> For a ticket
-            price of 100 €, this will lead to the following calculation:
-            <table class="table helper-width-auto">
-                <tr>
-                    <td>Ticket price</td>
-                    <td class="text-right">100.00 €</td>
-                </tr>
-                <tr>
-                    <td>pretix calculates the fee as 100/(100 - 5)% of 100 €</td>
-                    <td class="text-right">+ 5.26 €</td>
-                </tr>
-                <tr>
-                    <td>Subtotal that will be paid by the customer</td>
-                    <td class="text-right">105.26 €</td>
-                </tr>
-                <tr>
-                    <td>PayPal calculates its fee as 5% of 105.26 €</td>
-                    <td class="text-right">- 5.26 €</td>
-                </tr>
-                <tr>
-                    <td>End total that is on your bank account</td>
-                    <td class="text-right"><strong>100.00 €</strong></td>
-                </tr>
-            </table>
-            <div class="alert-warning alert">
-                Due to the various rounding steps performed by us and by the payment provider, the end total on
-                your bank account might stil vary by one cent.
-            </div>
-        </li>
-    </ul>
-{% endblock %}

src/pretix/control/urls.py

@@ -1,8 +1,8 @@
 from django.conf.urls import include, url
 
 from pretix.control.views import (
-    auth, dashboards, event, global_settings, help, item, main, orders,
-    organizer, user, vouchers, waitinglist,
+    auth, dashboards, event, global_settings, item, main, orders, organizer,
+    user, vouchers, waitinglist,
 )
 
 urlpatterns = [
@@ -132,5 +132,4 @@ urlpatterns = [
         url(r'^waitinglist/$', waitinglist.WaitingListView.as_view(), name='event.orders.waitinglist'),
         url(r'^waitinglist/auto_assign$', waitinglist.AutoAssign.as_view(), name='event.orders.waitinglist.auto'),
     ])),
-    url(r'^help/(?P<topic>[a-zA-Z0-9_/]+)$', help.HelpView.as_view(), name='help'),
 ]

src/pretix/control/views/help.py

@@ -1,27 +0,0 @@
-from django import template
-from django.http import Http404
-from django.shortcuts import render
-from django.views.generic import View
-
-from pretix.base.models import Organizer
-
-
-class HelpView(View):
-    model = Organizer
-    context_object_name = 'organizers'
-    template_name = 'pretixcontrol/organizers/index.html'
-    paginate_by = 30
-
-    def get(self, request, *args, **kwargs):
-        # In a security review, this came up as a possible path traversal issue. However, the URL regex
-        # does not allow any dots in the argument (which forbids traversing upwards in the directory tree).
-        # Even if it *was* possbile, it'd be loaded through django's template loader and therefore limited
-        # to TEMPLATE_DIR.
-        try:
-            locale = request.LANGUAGE_CODE
-            return render(request, 'pretixcontrol/help/%s.%s.html' % (kwargs.get('topic'), locale), {})
-        except template.TemplateDoesNotExist:
-            try:
-                return render(request, 'pretixcontrol/help/%s.html' % kwargs.get('topic'), {})
-            except template.TemplateDoesNotExist:
-                raise Http404('')

src/pretix/locale/de/LC_MESSAGES/django.po

@@ -4,8 +4,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: 1\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2017-05-02 08:59+0000\n"
-"PO-Revision-Date: 2017-05-02 11:01+0200\n"
+"POT-Creation-Date: 2017-05-02 15:55+0000\n"
+"PO-Revision-Date: 2017-05-02 17:56+0200\n"
 "Last-Translator: Raphael Michel <michel@rami.io>\n"
 "Language-Team: Raphael Michel <michel@rami.io>\n"
 "Language: de\n"
@@ -1287,17 +1287,17 @@ msgid "Calculate the fee from the total value including the fee."
 msgstr "Berechne die Gebühr als Anteil vom Endbetrag."
 
 #: pretix/base/payment.py:152
+#, python-brace-format
 msgid ""
 "We recommend you to enable this if you want your users to pay the payment "
-"fees of your payment provider. <a href=\"/control/help/payment/fee_reverse\" "
-"target=\"_blank\">Click here for detailled information on what this does.</"
-"a> Don't forget to set the correct fees above!"
+"fees of your payment provider. <a href=\"{docs_url}\" target=\"_blank"
+"\">Click here for detailled information on what this does.</a> Don't forget "
+"to set the correct fees above!"
 msgstr ""
 "Wir empfehlen, diese Option zu aktivieren, wenn Sie die Gebühren Ihres "
 "Zahlungsdienstleisters an Ihre Kunden weitergeben wollen. Denken Sie daran, "
 "oben die richtigen Gebührensätze des Zahlungsanbieters einzustellen. <a href="
-"\"/control/help/payment/fee_reverse\" target=\"_blank\">Weitere "
-"Informationen</a>."
+"\"{docs_url}\" target=\"_blank\">Weitere Informationen</a>."
 
 #: pretix/base/payment.py:160
 msgid "Text on invoices"
@@ -4407,10 +4407,6 @@ msgstr "Neuste Version"
 msgid "Update check settings"
 msgstr "Update-Check-Einstellungen"
 
-#: pretix/control/templates/pretixcontrol/help/base.html:4
-msgid "Help center"
-msgstr "Hilfe"
-
 #: pretix/control/templates/pretixcontrol/item/addons.html:7
 msgid ""
 "With add-ons, you can specify products that can be bought as an addition to "
@@ -8412,6 +8408,9 @@ msgstr "Deutsch"
 msgid "German (informal)"
 msgstr "Deutsch (Du)"
 
+#~ msgid "Help center"
+#~ msgstr "Hilfe"
+
 #~ msgid "Team"
 #~ msgstr "Team"
 

src/pretix/locale/de/LC_MESSAGES/djangojs.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2017-05-02 08:59+0000\n"
+"POT-Creation-Date: 2017-05-02 15:55+0000\n"
 "PO-Revision-Date: 2017-04-17 17:10+0200\n"
 "Last-Translator: Raphael Michel <michel@rami.io>\n"
 "Language-Team: \n"

src/pretix/locale/de_Informal/LC_MESSAGES/django.po

@@ -7,8 +7,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: 1\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2017-05-02 08:59+0000\n"
-"PO-Revision-Date: 2017-05-02 11:01+0200\n"
+"POT-Creation-Date: 2017-05-02 15:55+0000\n"
+"PO-Revision-Date: 2017-05-02 17:56+0200\n"
 "Last-Translator: Raphael Michel <michel@rami.io>\n"
 "Language-Team: Raphael Michel <michel@rami.io>\n"
 "Language: de\n"
@@ -1287,17 +1287,17 @@ msgid "Calculate the fee from the total value including the fee."
 msgstr "Berechne die Gebühr als Anteil vom Endbetrag."
 
 #: pretix/base/payment.py:152
+#, python-brace-format
 msgid ""
 "We recommend you to enable this if you want your users to pay the payment "
-"fees of your payment provider. <a href=\"/control/help/payment/fee_reverse\" "
-"target=\"_blank\">Click here for detailled information on what this does.</"
-"a> Don't forget to set the correct fees above!"
+"fees of your payment provider. <a href=\"{docs_url}\" target=\"_blank"
+"\">Click here for detailled information on what this does.</a> Don't forget "
+"to set the correct fees above!"
 msgstr ""
 "Wir empfehlen, diese Option zu aktivieren, wenn du die Gebühren deines "
 "Zahlungsdienstleisters an deine Kunden weitergeben willst. Denke daran, oben "
-"die richtigen Gebührensätze des Zahlungsanbieters einzustellen. <a href=\"/"
-"control/help/payment/fee_reverse\" target=\"_blank\">Weitere Informationen</"
-"a>."
+"die richtigen Gebührensätze des Zahlungsanbieters einzustellen. <a href="
+"\"{docs_url}\" target=\"_blank\">Weitere Informationen</a>."
 
 #: pretix/base/payment.py:160
 msgid "Text on invoices"
@@ -4396,10 +4396,6 @@ msgstr "Neuste Version"
 msgid "Update check settings"
 msgstr "Update-Check-Einstellungen"
 
-#: pretix/control/templates/pretixcontrol/help/base.html:4
-msgid "Help center"
-msgstr "Hilfe"
-
 #: pretix/control/templates/pretixcontrol/item/addons.html:7
 msgid ""
 "With add-ons, you can specify products that can be bought as an addition to "
@@ -8387,6 +8383,9 @@ msgstr "Deutsch"
 msgid "German (informal)"
 msgstr "Deutsch (Du)"
 
+#~ msgid "Help center"
+#~ msgstr "Hilfe"
+
 #~ msgid "Team"
 #~ msgstr "Team"
 

src/pretix/locale/de_Informal/LC_MESSAGES/djangojs.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2017-05-02 08:59+0000\n"
+"POT-Creation-Date: 2017-05-02 15:55+0000\n"
 "PO-Revision-Date: 2017-04-17 17:09+0200\n"
 "Last-Translator: Raphael Michel <michel@rami.io>\n"
 "Language-Team: \n"