django-zebra 0.4.5

概述
========

Zebra是一个库，它使使用Stripe与Django变得更加容易。

它由以下部分组成

* `zebra`，核心库，包含表单、webhook处理程序、抽象模型、混入、信号和templatetags，涵盖了大多数Stripe实现。
* `marty`，一个示例应用程序，展示了如何集成zebra，也作为其测试套件。

非常欢迎提交拉取请求！


用法
=====

## 安装 ##

1. `pip install django-zebra`

2. 编辑您的 `settings.py:`

```
INSTALLED_APPS += ("zebra",)
STRIPE_SECRET = "YOUR-SECRET-API-KEY"
STRIPE_PUBLISHABLE = "YOUR-PUBLISHABLE-API-KEY"
# 设置任何可选设置（以下）
```

3.（可选）如果您的 `ZEBRA_ENABLE_APP = True`，则运行 `./manage.py syncdb`

4.（可选）添加webhook URL

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

5.享受轻松的计费。


### 可选设置

* `ZEBRA_ENABLE_APP`
默认为`False`。作为Zebra的一部分，启用客户、计划和订阅的Django模型。
* `ZEBRA_CUSTOMER_MODEL`
实现StripeCustomerMixin的模型的应用+模型字符串。例如："myapp.MyCustomer"。如果`ZEBRA_ENABLE_APP`为true，则默认为`"zebra.Customer"`。
* `ZEBRA_AUTO_CREATE_STRIPE_CUSTOMERS`
默认为`True`。在访问stripe_customer时自动创建一个stripe客户对象（如果尚未存在）。


## Webhooks ##

Zebra处理Stripe发送的所有webhooks，并调用一系列您可以连接到您的应用的信号。要使用webhooks

* 包含Zebra的URL
* 将您的Stripe账户更新为指向您的webhook URL（即https://www.mysite.com/zebra/webhooks）
* 连接到您关心的任何webhook信号。

**注意：最初的Stripe webhook系统已被弃用。请参阅下面的描述，了解Zebra对新系统的支持。**

Zebra提供

* `zebra_webhook_recurring_payment_failed`
* `zebra_webhook_invoice_ready`
* `zebra_webhook_recurring_payment_succeeded`
* `zebra_webhook_subscription_trial_ending`
* `zebra_webhook_subscription_final_payment_attempt_failed`

所有webhook提供相同的参数

* `customer` - 如果`ZEBRA_CUSTOMER_MODEL`已设置，则返回与`stripe_customer_id`匹配的实例或`None`。如果没有设置`ZEBRA_CUSTOMER_MODEL`，则返回`None`。
* `full_json` - 完整的json响应，使用simplejson解析。


因此，例如，在成功付款后更新客户的新的账单日期，您可以

（假设您已设置`ZEBRA_CUSTOMER_MODEL`或使用`ZEBRA_ENABLE_APP`）

```
from zebra.signals import zebra_webhook_recurring_payment_succeeded

def update_last_invoice_date(sender, **kwargs)
customer = kwargs.pop("customer", None)
full_json = kwargs.pop("full_json", None)
customer.billing_date = full_json.date
customer.save()

zebra_webhook_recurring_payment_succeeded.connect(update_last_invoice_date)
```

### Webhooks更新 ###

Stripe最近更新了他们的webhook实现（请参阅https://stripe.com/blog/webhooks）。Zebra包括对新系统的实现。

* 包含Zebra的URL
* 将您的Stripe账户更新为指向您的webhook URL（即https://www.mysite.com/zebra/webhooks/v2/）
* 连接到您关心的任何webhook信号。

Zebra提供

* `zebra_webhook_charge_succeeded`
* `zebra_webhook_charge_failed`
* `zebra_webhook_charge_refunded`
* `zebra_webhook_charge_disputed`
* `zebra_webhook_customer_created`
* `zebra_webhook_customer_updated`
* `zebra_webhook_customer_deleted`
* `zebra_webhook_customer_subscription_created`
* `zebra_webhook_customer_subscription_updated`
* `zebra_webhook_customer_subscription_deleted`
* `zebra_webhook_customer_subscription_trial_will_end`
* `zebra_webhook_customer_discount_created`
* `zebra_webhook_customer_discount_updated`
* `zebra_webhook_customer_discount_deleted`
* `zebra_webhook_invoice_created`
* `zebra_webhook_invoice_updated`
* `zebra_webhook_invoice_payment_succeeded`
* `zebra_webhook_invoice_payment_failed`
* `zebra_webhook_invoiceitem_created`
* `zebra_webhook_invoiceitem_updated`
* `zebra_webhook_invoiceitem_deleted`
* `zebra_webhook_plan_created`
* `zebra_webhook_plan_updated`
* `zebra_webhook_plan_deleted`
* `zebra_webhook_coupon_created`
* `zebra_webhook_coupon_updated`
* `zebra_webhook_coupon_deleted`
* `zebra_webhook_transfer_created`
* `zebra_webhook_transfer_failed`
* `zebra_webhook_ping`

Zebra还提供了一个简单的信号映射，作为`zebra.signals.WEBHOOK_MAP`，将事件（`charge_succeeded`）映射到Zebra信号（`zebra_webhook_charge_succeeded`）。例如，要将处理程序分配给Zebra发送的所有信号，您可以遍历映射中的项

for event_key, webhook_signal in WEBHOOK_MAP.iteritems()
webhook_signal.connect(webhook_logger)


## Forms ##

StripePaymentForm设置了一个带有类似于[官方Stripe示例](https://gist.github.com/1204718#file_stripe_tutorial_page.html)的字段表单。

特别是，表单去除了所有信用卡字段的name属性，以防止意外提交。还提供了媒体来设置stripe.js（它假定您有jQuery）。

在视图中使用它如下

```
if request.method == 'POST'
zebra_form = StripePaymentForm(request.POST)
if zebra_form.is_valid()
my_profile = request.user.get_profile()
stripe_customer = stripe.Customer.retrieve(my_profile.stripe_customer_id)
stripe_customer.card = zebra_form.cleaned_data['stripe_token']
stripe_customer.save()

my_profile.last_4_digits = zebra_form.cleaned_data['last_4_digits']
my_profile.stripe_customer_id = stripe_customer.id
my_profile.save()

# 为用户做些好事

else
zebra_form = StripePaymentForm()
```

## 模板标签 ##

有几个模板标签负责设置 Stripe 环境，并渲染基本的信用卡更新表单。请注意，您的 `StripePaymentForm` 应该被命名为 `zebra_form` 或 `form`。

在模板中使用

```
{% extends "base.html" %}{% load zebra_tags %}

{% block head %}{{block.super}}
{% zebra_head_and_stripe_key %}
{% endblock %}

{% block content %}
{% zebra_card_form %}
{% endblock %}

```

就是这样 - 所有 Stripe 令牌的好处都会发生，并且错误会显示给您的用户。

## 模型和混入类 ##

模型和混入类文档即将推出。目前，代码相当直观，并且有较好的内联文档。


## 其他有用的部分 ##

Zebra 随附一个 manage.py 命令，用于清除您帐户中的所有测试客户。要使用它，请运行

```
./manage.py clear_stripe_test_customers
```

它响应 `--verbosity=[0-3]`。


致谢
=======

我没有编写任何 Stripe 相关的内容。只是使用它让我很高兴，并激发我为用户提供更好的 API。

代码致谢在 AUTHORS 文件中。欢迎 pull request！