django-abo 0.1.4

django-abo
==========

Recurring Payment / Subscription Handling for Django, supporting different payment gateways


**Currently django-abo is in alpha/beta phase, please use with caution!**

## Contribute

If you have a good idea or a specific problem, let us know! We'd love to get some feedback and we need more backends.

If you see a bug or want to contribute code in any way, please create a pull request on GitHub.

If you want to discuss changes (without comitting code), please create an issue on GitHub.

## Supported Backends

* [Paymill](https://www.paymill.com/)


## Installation

```bash
pip install django-abo
```

## Definitions

* *Plan* = something a customer can subscribe to, for example: "Premium Plan, 10$/month"
* *Subscription* = an actual subscription from a customer to a plan

## Usage

### 1. Setup settings

Add `abo` to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = (
# ...
'abo',
)
```

Add these lines to your settings:

```python
ABO_BACKENDS = ('abo.backends.paymill', )
INSTALLED_APPS += ABO_BACKENDS

ABO_DEFAULT_BACKEND = 'abo.backends.paymill'

ABO_BACKENDS_SETTINGS = {
'abo.backends.paymill': {
'PAYMILL_PUBLIC_KEY': 'your public key',
'PAYMILL_PRIVATE_KEY': 'your private key',
'PAYMILL_WEBHOOK_HOST': '' # hint: use ngrok.com for testing
}
}
```

### 2. Setup URLs

Include the payment URLs in your `urls.py`:

```python
urlpatterns = patterns('',
# ...
url(r'payment/^', include('abo.urls')),
)
```

Now, open http://localhost:8000/payment/subscribe/

### 3. Optional: Custom templates

*django-abo* comes with it's own templates so you don't have to start from scratch.

You can override backend specific templates and generic templates.

1. Just create a `abo` subdirectory in your own templates directory and put your own templates there.
1. Make sure they have the same filename as the original ones.

For example, start with [subscription_success.html](https://github.com/ubergrape/django-abo/blob/master/abo/templates/subscription_success.html)

### 4. Optional: Create your own plan and subscription models

*django-abo* has two models you can easily extend. If you have ever swapped Django's default user model for your own, you'll see that the technique is very similar.

#### Example custom Subscription model

Let's say you have an `Organization` model in your `accounts` app and you want every `Subscription` object to belong to an organization.

1. Create an app, if you don't have one already, that should contain your own `Subscription` model. For example `payment`

1. Put your custom `Subscription` model in your `models.py`, subclassing `AbstractSubscription`.

```python
from django.db import models

from accounts.models import Organization
from abo.models import AbstractSubscription

class Organization(models.Model):
name

class Subscription(AbstractSubscription):
organization = models.ForeignKey(Organization, null=True)
```

1. Put this in your settings:

```python
SUBSCRIPTION_MODEL = 'payment.Subscription'
```

1. Create your own View for Paymill:

```python
from abo.backends.paymill.views import PaymillView

class CustomPaymillView(PaymillView):
def form_valid(self, form):
r = super(CustomPaymillView, self).form_valid(form)

# Let's assume you have a middleware that puts the organization in request.
self.subscription.organization = self.request.organization
self.subscription.save()

return r
```

1. Put it in your urls.py

```python
urlpatterns = patterns('',
# ...
url(r'^paymill/subscribe/$', CustomPaymillView.as_view(), name='abo-paymill-authorization'),
url(r'^', include('abo.urls')),
)

#### Custom Plan model

The same works for the `Plan` model. If you created your custom `Plan` model, let *django-abo* know where it is:

```python
PLAN_MODEL = 'payment.Plan'
```

## Inspirations

*django-abo* uses ideas from:

* [Django user model](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#substituting-a-custom-user-model) - same techniques are used to make my Plan and Subscription model swappable
* [django-getpaid](https://github.com/cypreess/django-getpaid) - abstraction with backends etc.
* [django-paymill](https://github.com/ulfur/django-paymill/) - mainly event/webhook handling
* [django-stripe-payments](https://github.com/eldarion/django-stripe-payments) - some architecture details

Thanks to all contributers of theses projects