diff --git a/doc/conf.py b/doc/conf.py index 6362eb49c5..e7dea7c479 100644 --- a/doc/conf.py +++ b/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. diff --git a/doc/development/implementation/models.rst b/doc/development/implementation/models.rst index bda59b9cb8..e914f123d1 100644 --- a/doc/development/implementation/models.rst +++ b/doc/development/implementation/models.rst @@ -92,5 +92,3 @@ Vouchers .. autoclass:: pretix.base.models.Voucher :members: - -.. _cleanerversion: https://github.com/swisscom/cleanerversion diff --git a/doc/index.rst b/doc/index.rst index d33932818a..aecab08637 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,6 +6,7 @@ Contents: .. toctree:: :maxdepth: 2 + user/index admin/index development/index plugins/index diff --git a/doc/user/index.rst b/doc/user/index.rst new file mode 100644 index 0000000000..2280b87949 --- /dev/null +++ b/doc/user/index.rst @@ -0,0 +1,9 @@ +User Guide +========== + +Contents: + +.. toctree:: + :maxdepth: 2 + + payments/index diff --git a/doc/user/payments/banktransfer.rst b/doc/user/payments/banktransfer.rst new file mode 100644 index 0000000000..46bdd5a11d --- /dev/null +++ b/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. diff --git a/doc/user/payments/fees.rst b/doc/user/payments/fees.rst new file mode 100644 index 0000000000..8c9cc4ca5a --- /dev/null +++ b/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. diff --git a/doc/user/payments/img/bank1.png b/doc/user/payments/img/bank1.png new file mode 100644 index 0000000000..97c45a6739 Binary files /dev/null and b/doc/user/payments/img/bank1.png differ diff --git a/doc/user/payments/img/bank2.png b/doc/user/payments/img/bank2.png new file mode 100644 index 0000000000..68f004278e Binary files /dev/null and b/doc/user/payments/img/bank2.png differ diff --git a/doc/user/payments/img/paypal1.png b/doc/user/payments/img/paypal1.png new file mode 100644 index 0000000000..3f8135478b Binary files /dev/null and b/doc/user/payments/img/paypal1.png differ diff --git a/doc/user/payments/img/paypal2.png b/doc/user/payments/img/paypal2.png new file mode 100644 index 0000000000..30d607078f Binary files /dev/null and b/doc/user/payments/img/paypal2.png differ diff --git a/doc/user/payments/img/paypal3.png b/doc/user/payments/img/paypal3.png new file mode 100644 index 0000000000..33c29ad6ac Binary files /dev/null and b/doc/user/payments/img/paypal3.png differ diff --git a/doc/user/payments/img/paypal4.png b/doc/user/payments/img/paypal4.png new file mode 100644 index 0000000000..b8e806fbc4 Binary files /dev/null and b/doc/user/payments/img/paypal4.png differ diff --git a/doc/user/payments/img/paypal5.png b/doc/user/payments/img/paypal5.png new file mode 100644 index 0000000000..7333668452 Binary files /dev/null and b/doc/user/payments/img/paypal5.png differ diff --git a/doc/user/payments/img/paypal6.png b/doc/user/payments/img/paypal6.png new file mode 100644 index 0000000000..f20bbd1138 Binary files /dev/null and b/doc/user/payments/img/paypal6.png differ diff --git a/doc/user/payments/img/paypal7.png b/doc/user/payments/img/paypal7.png new file mode 100644 index 0000000000..a7caf2f612 Binary files /dev/null and b/doc/user/payments/img/paypal7.png differ diff --git a/doc/user/payments/img/paypal8.png b/doc/user/payments/img/paypal8.png new file mode 100644 index 0000000000..4e4b7d1dde Binary files /dev/null and b/doc/user/payments/img/paypal8.png differ diff --git a/doc/user/payments/img/paypal_pretix.png b/doc/user/payments/img/paypal_pretix.png new file mode 100644 index 0000000000..9421473c70 Binary files /dev/null and b/doc/user/payments/img/paypal_pretix.png differ diff --git a/doc/user/payments/img/stripe1.png b/doc/user/payments/img/stripe1.png new file mode 100644 index 0000000000..1f86cc6904 Binary files /dev/null and b/doc/user/payments/img/stripe1.png differ diff --git a/doc/user/payments/img/stripe2.png b/doc/user/payments/img/stripe2.png new file mode 100644 index 0000000000..ac073e5387 Binary files /dev/null and b/doc/user/payments/img/stripe2.png differ diff --git a/doc/user/payments/index.rst b/doc/user/payments/index.rst new file mode 100644 index 0000000000..6293be4c38 --- /dev/null +++ b/doc/user/payments/index.rst @@ -0,0 +1,14 @@ +Accepting payments +================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview + fees + paypal + stripe + banktransfer + diff --git a/doc/user/payments/overview.rst b/doc/user/payments/overview.rst new file mode 100644 index 0000000000..409d358c2c --- /dev/null +++ b/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. + + diff --git a/doc/user/payments/paypal.rst b/doc/user/payments/paypal.rst new file mode 100644 index 0000000000..742bc4c858 --- /dev/null +++ b/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/ diff --git a/doc/user/payments/stripe.rst b/doc/user/payments/stripe.rst new file mode 100644 index 0000000000..fc09005a74 --- /dev/null +++ b/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 diff --git a/src/pretix/base/payment.py b/src/pretix/base/payment.py index fdd0af1195..eedd7bdc51 100644 --- a/src/pretix/base/payment.py +++ b/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. Click here ' + 'payment provider. Click here ' 'for detailled information on what this does. 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', diff --git a/src/pretix/control/templates/pretixcontrol/help/base.html b/src/pretix/control/templates/pretixcontrol/help/base.html deleted file mode 100644 index d328414dab..0000000000 --- a/src/pretix/control/templates/pretixcontrol/help/base.html +++ /dev/null @@ -1,7 +0,0 @@ -{% extends "pretixcontrol/base.html" %} -{% load i18n %} -{% block content %} -

{% trans "Help center" %}

- {% block inner %} - {% endblock %} -{% endblock %} \ No newline at end of file diff --git a/src/pretix/control/templates/pretixcontrol/help/payment/fee_reverse.html b/src/pretix/control/templates/pretixcontrol/help/payment/fee_reverse.html deleted file mode 100644 index b982483064..0000000000 --- a/src/pretix/control/templates/pretixcontrol/help/payment/fee_reverse.html +++ /dev/null @@ -1,68 +0,0 @@ -{% extends "pretixcontrol/help/base.html" %} -{% block title %}Payment fee calculation{% endblock %} -{% block inner %} -

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 €. -

- -{% endblock %} \ No newline at end of file diff --git a/src/pretix/control/urls.py b/src/pretix/control/urls.py index 0061cf7440..40485f0893 100644 --- a/src/pretix/control/urls.py +++ b/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[a-zA-Z0-9_/]+)$', help.HelpView.as_view(), name='help'), ] diff --git a/src/pretix/control/views/help.py b/src/pretix/control/views/help.py deleted file mode 100644 index 9645a0fcd8..0000000000 --- a/src/pretix/control/views/help.py +++ /dev/null @@ -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('') diff --git a/src/pretix/locale/de/LC_MESSAGES/django.po b/src/pretix/locale/de/LC_MESSAGES/django.po index b678490e9d..f46830e924 100644 --- a/src/pretix/locale/de/LC_MESSAGES/django.po +++ b/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 \n" "Language-Team: Raphael Michel \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. Click here for detailled information on what this does. Don't forget to set the correct fees above!" +"fees of your payment provider. Click here for detailled information on what this does. 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. Weitere " -"Informationen." +"\"{docs_url}\" target=\"_blank\">Weitere Informationen." #: 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" diff --git a/src/pretix/locale/de/LC_MESSAGES/djangojs.po b/src/pretix/locale/de/LC_MESSAGES/djangojs.po index fe313696a9..95d8679c62 100644 --- a/src/pretix/locale/de/LC_MESSAGES/djangojs.po +++ b/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 \n" "Language-Team: \n" diff --git a/src/pretix/locale/de_Informal/LC_MESSAGES/django.po b/src/pretix/locale/de_Informal/LC_MESSAGES/django.po index feeee5ec3b..c9c868ec96 100644 --- a/src/pretix/locale/de_Informal/LC_MESSAGES/django.po +++ b/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 \n" "Language-Team: Raphael Michel \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. Click here for detailled information on what this does. Don't forget to set the correct fees above!" +"fees of your payment provider. Click here for detailled information on what this does. 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. Weitere Informationen." +"die richtigen Gebührensätze des Zahlungsanbieters einzustellen. Weitere Informationen." #: 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" diff --git a/src/pretix/locale/de_Informal/LC_MESSAGES/djangojs.po b/src/pretix/locale/de_Informal/LC_MESSAGES/djangojs.po index 5930acbb8c..e1dad1e936 100644 --- a/src/pretix/locale/de_Informal/LC_MESSAGES/djangojs.po +++ b/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 \n" "Language-Team: \n"