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 %} -
- 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 €. -
-| 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 € | -
| 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.26 € | -- 5.26 € | -
| End total that is on your bank account | -100.00 € | -