Metadata-Version: 2.1
Name: django-getpaid
Version: 1.8.0
Summary: Multi-broker payment processor for Django
Home-page: https://github.com/django-getpaid/django-getpaid
Author: Django-getpaid Team
Author-email: d.kozaczko@sunscrapers.com
License: MIT
Description: =============================
        Welcome to django-getpaid
        =============================
        
        .. image:: https://img.shields.io/pypi/v/django-getpaid.svg
            :target: https://pypi.org/project/django-getpaid/
            :alt: Latest PyPI version
        .. image:: https://img.shields.io/travis/sunscrapers/django-getpaid.svg
            :target: https://travis-ci.org/sunscrapers/django-getpaid
        .. image:: https://img.shields.io/coveralls/github/cypreess/django-getpaid.svg
            :target: https://coveralls.io/github/django-getpaid/django-getpaid?branch=master
        .. image:: https://img.shields.io/pypi/wheel/django-getpaid.svg
            :target: https://pypi.org/project/django-getpaid/
        .. image:: https://img.shields.io/pypi/l/django-getpaid.svg
            :target: https://pypi.org/project/django-getpaid/
        
        
        django-getpaid is a multi-broker payment processor for Django
        
        Documentation
        =============
        
        The full documentation is at https://django-getpaid.readthedocs.io.
        
        Quickstart
        ==========
        
        Install django-getpaid::
        
            pip install django-getpaid
        
        Add it to your `INSTALLED_APPS`:
        
        .. code-block:: python
        
            INSTALLED_APPS = (
                ...
                'getpaid.apps.GetpaidConfig',
                ...
            )
        
        Add django-getpaid's URL patterns:
        
        .. code-block:: python
        
            from getpaid import urls as getpaid_urls
        
        
            urlpatterns = [
                ...
                url(r'^', include(getpaid_urls)),
                ...
            ]
        
        Features
        ========
        
        * **multiple payment brokers support** - allows using simultaneously many payments methods at the same time,
        * **multiple payments currency support** (getpaid will automatically filter available backends list accordingly to the payment currency),
        * **integration flexibility**  -  makes minimal assumption on 3rd party code - requires only an existence of any single django model representing an order,
        * **proper architecture design** - all backends which requires fetching payment confirmation are enforced to use asynchronous celery tasks.
        
        
        Supported backends:
        -------------------
        
        In alphabetical order:
        
        * `Dotpay.pl/Dotpay.eu <http://dotpay.eu>`_
        * `PayU.pl <http://payu.pl>`_
        
        Don't see the payment backend you need? `Writing your own backend <https://django-getpaid.readthedocs.org/en/latest/custom_backends.html>`_ is very simple. Pull requests are welcome.
        
        
        Payment workflow integration
        ============================
        
        With few simple steps you will easily integrate your project with django-getpaid. This module is shipped with
        very well documented django-getpaid test project which can be found with module source code. Please refer to this
        code for implementation details.
        
        Step 1. Prepare your order model
        --------------------------------
        
        **Required**
        
        First of all you need a model that will represent an order in you application. It does not matter how
        complicated the model is or what fields does it provide, be it single item order, or multiple items order.
        Let's take an example from test project::
        
            from django.core.urlresolvers import reverse
            from django.db import models
            import getpaid
        
            class Order(models.Model):
                name = models.CharField(max_length=100)
                total = models.DecimalField(decimal_places=2, max_digits=8, default=0)
                currency = models.CharField(max_length=3, default='EUR')
                status = models.CharField(max_length=1, blank=True, default='W', choices=(('W', 'Waiting for payment'),
                                                                                           ('P', 'Payment complete')))
                def get_absolute_url(self):
                    return reverse('order_detail', kwargs={'pk': self.pk})
        
                def __unicode__(self):
                    return self.name
        
            Payment = getpaid.register_to_payment(Order, unique=False, related_name='payments')
        
        
        and add the following line to your settings:
        
            GETPAID_ORDER_MODEL = 'my_super_app.Order'
        
        
        First of all, class name is not important at all. You register a model with ``register_to_payment`` method.
        
        You can add some `kwargs` that are basically used for ``ForeignKey`` kwargs. In this example whe allow creating multiple payments for one order, and naming One-To-Many relation.
        
        There are two important things on that model. In fact two methods are required to be present in order class.
        The first one is ``__unicode__`` method as this will be used in few places as a fallback for generating
        order description. The second one is ``get_absolute_url`` method which should return an URL of order object.
        It is used again as a fallback for some final redirections after payment success of failure (if you do not provide otherwise).
        
        The second important thing is, that it actually doesn't matter if you store `total` in database or just sum it up from some items.
        You will see why, in further sections.
        
        
        Step 2. Prepare payment form for order
        --------------------------------------
        
        **Required**
        
        Your application - after some custom workflow - just created an order object. That's fine.
        We now want to get paid for that order. So lets take a look on a view for creating a payment for an order::
        
            from django.views.generic.detail import DetailView
            from getpaid.forms import PaymentMethodForm
            from example.orders.models import Order
        
            class OrderView(DetailView):
                model=Order
        
                def get_context_data(self, **kwargs):
                    context = super(OrderView, self).get_context_data(**kwargs)
                    context['payment_form'] = PaymentMethodForm(self.object.currency, initial={'order': self.object})
                    return context
        
        
        Here we get a ``PaymentMethodForm`` object, that is parametrised with currency type.
        This is an important thing, because this form will display you only payments method that are suitable
        for a given order currency.
        
        ``PaymentMethodForm`` provides two fields: HiddenInput with order_id and ChoiceField with backend name. This is how you use it in template::
        
            <form action="{% url 'getpaid:new-payment' currency=object.currency %}" method="post">
                {% csrf_token %}
                {{ payment_form.as_p }}
                <input type="submit" value="Continue">
            </form>
        
        
        Action URL of form should point on named link  `getpaid:new-payment` that requires currency code argument.
        This form will redirect client from order view directly to page of payment broker.
        
        Step 3. Filling necessary payment data
        --------------------------------------
        
        **Required**
        
        Because the idea of whole module is that it should be loosely coupled, there is this convention that it does
        not require any structure of your order model. But still it needs to know some transaction details of your order.
        Django signals are used for that. django-getpaid, while generating gateway redirect url, will emit
        a ``getpaid.signals.new_payment_query`` signal. Here is the signal declaration::
        
            new_payment_query = Signal(providing_args=['order', 'payment'])
            new_payment_query.__doc__ = """
            Sent to ask for filling Payment object with additional data:
                payment.amount:			total amount of an order
                payment.currency:		amount currency
            This data cannot be filled by ``getpaid`` because it is Order structure
            agnostic. After filling values just return. Saving is done outside signal.
            """
        
        Your code should have some signal listeners, that will fill payment object with required information::
        
            from getpaid import signals
        
            def new_payment_query_listener(sender, order=None, payment=None, **kwargs):
                """
                Here we fill only two obligatory fields of payment, and leave signal handler
                """
                payment.amount = order.total
                payment.currency = order.currency
        
            signals.new_payment_query.connect(new_payment_query_listener)
        
        
        So this is a little piece of logic that you need to provide to map your order to payment object.
        As you can see you can do all fancy stuff here to get order total value and currency code.
        
        .. note::
        
            If you don't know where to put your listeners code, we recommend to put it in ``listeners.py`` file
            and then add a line ``import listeners`` to the end of you ``models.py`` file. Both files
            (``listeners.py`` and ``models.py``) should be placed in on of your app (possibly an app related to order model).
        
        Step 4. Handling changes of payment status
        ------------------------------------------
        
        **Required**
        
        Signals are also used to inform you that some particular payment just change status. In this case you will
        use ``getpaid.signals.payment_status_changed`` signal which is defined as::
        
            payment_status_changed = Signal(providing_args=['old_status', 'new_status'])
            payment_status_changed.__doc__ = """Sent when Payment status changes."""
        
        example code that handles status change::
        
            from getpaid import signals
        
            def payment_status_changed_listener(sender, instance, old_status, new_status, **kwargs):
                """
                Here we will actually do something, when payment is accepted.
                E.g. lets change an order status.
                """
                if old_status != 'paid' and new_status == 'paid':
                    # Ensures that we process order only one
                    instance.order.status = 'P'
                    instance.order.save()
        
            signals.payment_status_changed.connect(payment_status_changed_listener)
        
        For example: when payment changes status to 'paid', it means that the necessary amount was verified
        by your payment broker. You can now access ``payment.order`` object and do some stuff here.
        
        Step 5. Handling new payment creation
        -------------------------------------
        
        **Optional**
        
        For some reasons you may want to make some additiona checks before a new
        Payment is created or add some extra validation before the user is redirected
        to gateway url. You can handle this with
        ``getpaid.signals.order_additional_validation`` signal defined as::
        
        	order_additional_validation = Signal(providing_args=['request',
                                                                 'order',
                                                                 'backend'])
        	order_additional_validation.__doc__ = """
        	A hook for additional validation of an order.
        	Sent after PaymentMethodForm is submitted but before
        	Payment is created and before user is redirected to payment gateway.
        	"""
        
        It may also (e.g. for KPI benchmarking) be important for you to how many
        and which payments were made.
        You can handle ``getpaid.signals.new_payment`` signal defined as::
        
            new_payment = Signal(providing_args=['order', 'payment'])
            new_payment.__doc__ = """Sent after creating new payment."""
        
        
        .. note::
        
            This method will enable you to make on-line KPI processing. For batch processing you can as well just query
            the database for Payment model.
        
        Step 6. Setup your payment backends
        -----------------------------------
        
        **Required**
        
        Please be sure to read carefully  `Backends <https://django-getpaid.readthedocs.org/en/latest/backends.html>`_ section for information on how to configure particular backends.
        They will probably not work out of the box without providing some account keys or other credentials.
        
        
        
        Running Tests
        =============
        
        Does the code actually work?
        
        ::
        
            source <YOURVIRTUALENV>/bin/activate
            (myenv) $ pip install tox
            (myenv) $ tox
        
        
        
        Disclaimer
        ==========
        
        This project has nothing in common with `getpaid <http://code.google.com/p/getpaid/>`_ plone project.
        It is mostly based on `mamona <https://github.com/emesik/mamona>`_ project.
        This app was written because there was not a single reliable or simple to use payment processor dedicated to django.
        You can refer to other payment modules which does not meet our needs:
        `Satchmo <http://satchmoproject.sadba.org/docs/dev/>`_,
        `python-payflowpro <https://github.com/bkeating/python-payflowpro/>`_,
        `django-authorizenet <https://github.com/zen4ever/django-authorizenet>`_,
        `mamona <https://github.com/emesik/mamona>`_,
        `django-paypal <https://github.com/johnboxall/django-paypal>`_,
        `django-payme <https://github.com/bradleyayers/django-payme/>`_.
        
        
        
        Credits
        =======
        
        Proudly sponsored by `SUNSCRAPERS <http://sunscrapers.com/>`_
        
        Tools used in rendering this package:
        
        *  Cookiecutter_
        *  `cookiecutter-djangopackage`_
        
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage
        
        
        
        
        History
        =======
        
        (master branch - current development)
        -------------------------------------
        
        
        
        Version 1.8.0 (2018-07-24)
        --------------------------
        
        * Updated project structure thanks to cookiecutter-djangopackage
        * New plugin: pay_rest - New PayU API
        * Updated following plugins:
          * payu - legacy API still works on new URL
        * Dropped support for following plugins:
          * epaydk (API no longer functional)
          * moip (will be moved to separate package)
          * transferuj.pl (API no longer functional)
          * przelewy24.pl (API needs update, but no sandbox available anymore)
        * Dropped support for Django <= 1.10
        * Provide support for Django 2.0
        
        
        Version 1.7.5
        -------------
        * Fixed przelewy24 params (py3 support)
        
        Version 1.7.4
        -------------
        * Added default apps config getpaid.apps.Config
        * Fixed and refactoring for utils.get_domain, build_absolute_uri,
         settings.GETPAID_SITE_DOMAIN
        * Refactored register_to_payment
        * Refactored build_absolute_uri
        * Refactored and fixes in transferuj backend
         - payment.paid_on uses local TIMEZONE now as opposed to UTC
         - changed params
         - add post method to SuccessView and FailureView
        * Added test models factories
        * Dropped support for Django <=1.6
        
        Version 1.7.3
        -------------
        * Refactored Dotpay
        * Moved all existing tests to test_project and added more/refactored
        * Fixed utils.import_module
        * Fixed Payu and tests (py3 support)
        * Updated docs
        
        Version 1.7.2
        -------------
        * Updated coveragerc and travis.yml
        * Added missing mgiration for Payment.status
        
        Version 1.7.1
        -------------
        * Added coveragerc
        * Updated README
        * Added settings.GETPAID_ORDER_MODEL
        * Added epay.dk support
        * Added initial django migration
        
        Version 1.7.0
        -------------
        * Refactoring to support for py3 (3.4)
        * Change imports to be relative - fixes #43
        * Add USD to supported currencies in Paymill backend (thanks lauris)
        * Fix a few typos
        
        Version 1.6.0
        -------------
        * Adding paymill backend
        * PEP 8 improvements
        * Adding support for django 1.5 in test project (+ tests)
        * Fixed issue on `utils.import_name` to allow packages without parents
        * Adding dependency to pytz for przelewy24 backend
        * Refactoring of PayU backend (xml->txt api, better logging) and adding support for non-auto payment accepting
        
        Version 1.5.1
        -------------
        * Fixing packaging that causes errors with package installation
        
        Version 1.5.0
        -------------
        * Adding new backend - Przelewy24.pl (thanks to IssueStand.com funding)
        * Fixing packaging package data (now using only MANIFEST.in)
        
        Version 1.4.0
        -------------
        * Cleaned version 1.3 from minor issues before implementing new backends
        * Brazilian backend moip
        * Updated PL translation
        * Added brazilian portuguese translation
        * Storing payment external id and description in the database (warning: database migration needed!)
        * Transferuj backend can now predefine interface language when redirecting
        * POST method supported on redirect to payment
        
        Version 1.3.0
        -------------
        * Logotypes support in new payment form
        * Fixing packaging
        
        Version 1.2
        -----------
        * Dotpay backend added
        * Hooks for backends to accept email and user name
        * Refactoring
        
        
        Version 1.1
        -----------
        * PayU backend added
        * Lots of documentation
        * Refactoring
        
        Version 1.0
        -----------
        * First stable version
        
Keywords: django-getpaid
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Provides-Extra: payu
