Metadata-Version: 2.4
Name: pretix-thepay
Version: 9.1.0
Summary: The Pay payment provider for Pretix
Author-email: KrisIsNew <thepay.pretix@krisisnew.xyz>
Maintainer-email: KrisIsNew <thepay.pretix@krisisnew.xyz>
License-Expression: Apache-2.0
Project-URL: homepage, https://github.com/KrisIsNew/pretix-thepay
Project-URL: repository, https://github.com/KrisIsNew/pretix-thepay
Project-URL: issues, https://github.com/KrisIsNew/pretix-thepay/issues
Keywords: pretix,payment,thepay
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pretix>=2025.1.0
Requires-Dist: requests>=2.32.4
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Requires-Dist: responses; extra == "test"
Dynamic: license-file

pretix-thepay
=============

ThePay payment provider for pretix: card payments, bank transfers and the other ThePay methods,
with automatic refunds.

How it works
------------

1. The customer chooses The Pay. pretix creates a ThePay payment and redirects the customer.
2. The state is always read from ThePay over the authenticated API, never taken from the request. Three
   things trigger that read:

   - the customer returning,
   - ThePay's notifications,
   - a periodic task.

   The periodic task covers notifications ThePay gave up on, since it retries them for only 2 days.
3. A bank transfer can arrive a working day or more later. The payment stays pending and is confirmed by the
   notification. ThePay accepts the payment until the order's payment term plus a configurable number of days.
   After that, ThePay returns a late transfer to the payer automatically.
4. Refunds, including customers cancelling their own orders, are sent to ThePay. pretix shows a refund as
   done only once ThePay reports it as ``returned``. A refund ThePay declines becomes failed and is logged.
   Refunds made in the ThePay administration appear in pretix as external refunds.

Requirements
------------

- pretix 2025.1 or later, Python 3.11 or later
- A ThePay project (merchant ID, project ID, API password)

Installation
------------

::

    pip install pretix-thepay

In production we bake it into the pretix image, see https://github.com/KrisIsNew/hellpretix.
Enable the plugin per event, then configure it under *Settings → Payment → The Pay*.

Configuration
-------------

==============================  ==================================================================
Merchant ID, Project ID,        ThePay administration → Implementation
API password
Fallback gateway language       Used when the order's language is not one ThePay offers (cs, sk, en)
Days payable after the term     Default 3. Match pretix's *Accept late payments* setting.
Let ThePay e-mail the customer  ThePay's own e-mails, e.g. bank details for a transfer
Demo environment                ``demo.api.thepay.cz`` with demo credentials
==============================  ==================================================================

Operational requirements:

- **IP whitelist**: add the public IP of the pretix server in ThePay administration → Implementation.
- **Clock**: ThePay rejects requests whose ``SignatureDate`` is more than 20 s off, so run NTP.
- **Periodic task**: pretix's ``runperiodic`` must run (the standalone image does this). The plugin
  re-checks open payments and refunds at most every 10 minutes.
- **Refund balance**: ThePay pays refunds from your ThePay balance. Without enough balance it waits 10 days
  and then declines the refund.

Cancellations and automatic refunds
-----------------------------------

Event → Settings → Cancellation:

- Allow customers to cancel paid orders.
- Choose to refund automatically to the original payment method.

pretix refunds automatically only when ThePay can. Otherwise it creates a manual refund for you. ThePay
cannot refund automatically:

- card payments older than **6 months**,
- bank transfers whose payer account ThePay does not know (e.g. cash deposits),
- methods without the ``returnable`` tag.

Development
-----------

::

    pip install -e ".[test]"
    pytest
    flake8 pretix_thepay tests && isort --check-only pretix_thepay tests

The tests run against a real pretix (``pretix.testutils.settings``, SQLite) with the ThePay API mocked by
``responses``. Releasing: see ``RELEASING.md``.

References
----------

- ThePay API: https://docs.thepay.eu/
- pretix payment provider API: https://docs.pretix.eu/dev/development/api/payment.html

License
-------

Apache License 2.0
