django-zebra

Zebra is a library that makes using Stripe with Django even easier.

Please report errors and omissions at https://github.com/GoodCloud/django-zebra/issues

django-zebra contains two components:

  • zebra which is the core library providing forms, webhook handlers, abstract models, mixins, signals, and template tags that cover most of the Stripe functionality for many implementations.
  • marty which is an example app that integrates django-zebra and provides a test suite.

Installation

Install django-zebra:

pip install django-zebra

Edit your Django settings:

INSTALLED_APPS += ('zebra',)
STRIPE_SECRET = "YOUR-SECRET-API-KEY"
STRIPE_PUBLISHABLE = "YOUR-PUBLISHABLE-API-KEY"

Enable optional settings

See Configuration for settings available.

Enable Webhook URLs

This is optional and only if you wish to use zebra’s webhook signals.

urlpatterns += patterns('',
  url(r'zebra/', include('zebra.urls', namespace="zebra", app_name='zebra')),
)

Quick Start

By default, adding zebra to your installed apps will not provide any functionality beyond the webhooks if you enable the url pattern.

The library was designed to be as flexible as possible so it doesn’t step on your toes or get in your way.

So following along from the installation above you’ll discover that running syncdb has no affect. At this point you have 2 options:

  • Use the mixins and abstract base classes to extend your own models
  • Enable the default application (models & admin)

Customizing your existing application with ABCs and mixins

If you already have an existing model for customers you can still use the default zebra application and simply provide your model class (see the next section).

If you want to forego using the default application you can find all the documentation on this site and in the source code which can be viewed in the GitHub repo.

The easiest way to get started is to extend one of the base classes provided.

Check out zebra.mixins for a list of all the mixins that come with the zebra library. The Tutorial also goes into detail on mixing zebra with an existing application.

Enabling the default application

To enable the default application simply edit your projects settings and include:

ZEBRA_ENABLE_APP = True

Then run syncdb to install the models.

You should now find the zebra application listed in the admin with three default models:

  • Customers
  • Plans
  • Subscriptions

If you already have a model that you want to use for customers simply add the following setting:

ZEBRA_CUSTOMER_MODEL = 'your_app.YourCustomerModel'

Then in your models file simply update your model in inherit from zebra.models.StripeCustomer abstract base class:

from zebra.models import StripeCustomer

class YourCustomerModel(StripeCustomer):
    ...

Now YourCustomerModel will have 2 new attributes, stripe and stripe_customer along with a new field, stripe_customer_id. If you’ve decided to go this route, simply replace zebra.models.Customer with your_app.models.YourCustomerModel in the examples below.

By default ZEBRA_AUTO_CREATE_STRIPE_CUSTOMERS is True so creating new customers is a breeze by simply using the mixed-in helper. Simply instantiate your customer class and access the stripe_customer attribute.

>>> import zebra
>>> c = zebra.models.Customer()
>>> c.stripe_customer_id
>>> c.id
>>> c.stripe_customer
<Customer customer id=cus_A0FULkVQwzwlUz at 0x101b2d7d0> JSON: {
  "account_balance": 0,
  "created": 1329775998,
  "id": "cus_A0FULkVQwzwlUz",
  "livemode": false,
  "object": "customer"
}
>>> c.id
1
>>> c.stripe_customer_id
u'cus_A0FULkVQwzwlUz'

As you can see in the example above, with the default customer model there is only 1 field so once the model is in a savable state (all required fields containing valid values) simply calling c.stripe_customer created a new customer within Stripe, updated the instance with the newly created customer ID and returned the Stripe API customer instance.

Let’s charge our new customer $10.

First we must give our customer a credit card:

>>> card = {
... 'number': '4242424242424242',
... 'exp_month': '03',
... 'exp_year': '2013',
... 'cvc': '123',
... 'name': 'John Doe'
... }
>>> stripe_cust = c.stripe_customer
>>> stripe_cust.card = card
>>> stripe_cust.save()
<Customer customer id=cus_A0FULkVQwzwlUz at 0x101b2d7d0> JSON: {
  "account_balance": 0,
  "active_card": {
    "country": "US",
    "cvc_check": "pass",
    "exp_month": 3,
    "exp_year": 2013,
    "last4": "4242",
    "name": "John Doe",
    "object": "card",
    "type": "Visa"
  },
  "created": 1329775998,
  "id": "cus_A0FULkVQwzwlUz",
  "livemode": false,
  "object": "customer"
}

Now we can charge John $10 for that pizza we split:

>>> stripe.Charge.create(
... amount=1000,
... currency='usd',
... customer=c.stripe_customer_id,
... description='the money you owed me for the pizza'
... )
<Charge charge id=ch_lCSjHD3hAxXcjO at 0x101e0ff10> JSON: {
  "amount": 1000,
  "card": {
    "country": "US",
    "cvc_check": "pass",
    "exp_month": 3,
    "exp_year": 2013,
    "last4": "4242",
    "name": "John Doe",
    "object": "card",
    "type": "Visa"
  },
  "created": 1329776973,
  "currency": "usd",
  "customer": "cus_A0FULkVQwzwlUz",
  "description": "the money you owed me",
  "disputed": false,
  "fee": 59,
  "id": "ch_lCSjHD3hAxXcjO",
  "livemode": false,
  "object": "charge",
  "paid": true,
  "refunded": false
}

Indices and tables