Изменения в README.rst

README.rst

@@ -63,34 +63,138 @@ ROBOKASSA (http://robokassa.ru/Doc/Ru/Interface.aspx). Приложение ре
 Форма для приема платежей
 -------------------------
 
-Для того, чтобы упростить конструирование html-форм для отправки пользователей в
+Для того, чтобы упростить отправку и валидацию данных в
 Robokassa, в django-robokassa есть форма RobokassaForm. Она нужна
-для упрощения вывода информации в шаблонах, вычисления контрольной суммы и
-формирования параметров GET-запросов.
+для вычисления контрольной суммы (в том числе, для проверки того,
+что взаимодействие происходит именно с robokassa.ru, а не его подделкой)
+и формирования параметров GET-запросов. Для вывода информации в шаблон и
+обработки запроса пользователя необходимо реализовать свою собственную форму
+для ввода информации о платеже пользователем и view для обработки этой формы.
+При POST запросе из этой формы необходимо во view извлекать ее параметры,
+создавать form=RobokassaForm() с нужными значениями в initial и делать redirect
+на form.get_redirect_url().
 
-Пример::
+Пример view::
 
     # views.py
 
-    from django.shortcuts import get_object_or_404, render
-    from django.contrib.auth.decorators import login_required
-
-    from robokassa.forms import RobokassaForm
-
     @login_required
-    def pay_with_robokassa(request, order_id)
-        order = get_object_or_404(Order, pk = order_id)
-
-        form = RobokassaForm(initial={
-                   'OutSum': order.total,
-                   'InvId': order.id,
-                   'Desc': order.name,
-                   'Email': request.user.email,
-                   # 'IncCurrLabel': '',
-                   # 'Culture': 'ru'
-               })
-
-        return render(request, 'pay_with_robokassa.html', {'form': form})
+    def balance_top_up(request):
+        """
+        Отправка запроса на пополнение баланса на robokassa.ru
+        """
+
+        if request.method == 'POST':
+
+            # Создание экземпляра своей формы после POST запроса
+            top_up_balance_form = TopUpBalanceForm(request.POST)
+
+            # Проверка на валидность полей в своей форме
+            if top_up_balance_form.is_valid():
+
+                # Здесь необходимо сгенерировать уникальный номер операции op_id
+
+                op_id = ...
+
+                # Генерация контрольной суммы с использованием
+                # ROBOKASSA_PASSWORD1 и остальными параметрами.
+                # _get_check_sum() см. ниже
+
+                check_sum = _get_check_sum(
+                    # Логин пользователя
+                    login=settings.ROBOKASSA_LOGIN,
+                    # Сумма, на которую происходит повышение баланса
+                    rebalancing_sum=\
+                        top_up_balance_form.cleaned_data['OutSum'],
+                    # Уникальный счетчик операции
+                    operation_id=op_id,
+                    # Пароль №1
+                    password=settings.ROBOKASSA_PASSWORD1
+                )
+
+                # Отправка запроса на robokassa.ru для инициации процедуры
+                # начисления средств на счет
+
+                form = RobokassaForm(initial={
+                    'MrchLogin': settings.ROBOKASSA_LOGIN,
+                    'OutSum':
+                        top_up_balance_form.cleaned_data['OutSum'],
+                    'InvId': op_id,
+                    'Desc': 'description',
+                    'SignatureValue': check_sum,
+                    'Email': request.user.email,
+                    'Culture': 'ru'
+                })
+
+                # Перенаправление
+                return redirect(form.get_redirect_url())
+            else:
+               # Обработка ошибкок валидации.(Чтобы исключить их наличие
+               # после отправки формы, для каждого из ее полей стоит
+               # использовать HTML5 атрибут "pattern", содержащий регулярное
+               # выражение. Подробнее см. ниже)
+    else:
+        # Создание экземпляра своей формы для взаимодействия с пользователем.
+        # В данном случае форма содержит одно поле - OutSum - сумма перевода.
+
+        form = TopUpBalanceForm()
+
+        # Шаблон см. ниже
+        return render(
+            request,
+            'example.html',
+            { 'form': form }
+        )
+
+Пример функции подсчета контрольной суммы::
+
+    def _get_check_sum(login, rebalancing_sum, operation_id, password):
+        """
+        md5 checksum
+        """
+
+        data = u':'.join([
+            u"%s" % str(login),
+            u"%s" % str(rebalancing_sum),
+            u"%s" % str(operation_id),
+            u"%s" % password
+        ])
+
+        return hashlib.md5(data).hexdigest()
+
+Пример формы::
+
+    # forms.py
+
+    # Неотрицательное целое число
+    _regexp_template = r'^\d+$'
+    _regexp = u'\d+'
+
+    class TopUpBalanceForm(forms.Form):
+        """
+        Пополнение баланса
+        """
+
+        OutSum = forms.CharField(
+            max_length=15,
+            label=_(u"Введите сумму в рублях для изменения баланса"),
+            widget=forms.TextInput(
+                attrs={
+                    'pattern': _regexp,
+                    'maxlength': '7',
+                    'placeholder': u'Сумма перевода',
+                    'required': 'required',
+                    'value': 100500
+                }
+            )
+        )
+
+        def clean(self):
+            cleaned_data = super(TopUpBalanceForm, self).clean()
+            OutSum = cleaned_data['OutSum']
+            if not re.match(_regexp_template, OutSum, re.UNICODE):
+                raise forms.ValidationError(_(u'Неверная сумма перевода'))
+            return cleaned_data
 
 В initial все параметры необязательны. Детальную справку по параметрам
 лучше посмотреть в `документации <http://robokassa.ru/ru/Doc/Ru/Interface.aspx#222>`_
@@ -101,29 +205,18 @@ Robokassa, в django-robokassa есть форма RobokassaForm. Она нуж
 
     {% extends 'base.html' %}
 
+    {% load i18n %}
+
+    {% block title %}{% trans "Пополнение баланса" %}{% endblock %}
+
     {% block content %}
-        <form action="{{ form.target }}" method="POST">
-            <p>{{ form.as_p }}</p>
-            <p><input type="submit" value="Купить"></p>
+        <form action="{% url app_name.views.balance_top_up %}" method="post">
+            {% csrf_token %}
+            {{ form.as_p }}
+            <button type="submit">{% trans "Пополнение баланса" %}</button>
         </form>
     {% endblock %}
 
-Форма выведется в виде набора скрытых input-тегов.
-
-У формы есть атрибут target, содержащий URL, по которому форму следует
-отправлять. В тестовом режиме это будет тестовый URL, в боевом - боевой.
-
-Обратите внимание, {% csrf_token %} в форме не нужен (и более того, добавлять
-его к форме небезопасно), т.к. форма ведет на внешний сайт - сайт робокассы.
-
-Вместо отправки формы можно сформировать GET-запрос. У формы есть
-метод get_redirect_url, который возвращает нужный адрес со всеми параметрами.
-Редирект на этот адрес равносилен отправке формы методом GET.
-
-django-robokassa не включает в себя модели "Покупка" (``Order`` в примере),
-т.к. эта модель будет отличаться от сайта к сайту. Обработку смены статусов
-покупок следует осуществлять в обработчиках сигналов.
-
 
 Получение результатов платежей
 ------------------------------
@@ -138,10 +231,42 @@ django-robokassa не включает в себя модели "Покупка"
 3. Можно запрашивать статус платежа через XML-сервис.
 
 В django-robokassa на данный момент поддерживаются методы 1 и 2 и их совмещение
-(дополнительная проверка, что при переходе на Success URL уже было уведомление
-на Result URL при использовании опции ROBOKASSA_STRICT_CHECK = True).
+(дополнительное подтверждение сначала через ResultURL, а затем переход на
+SuccessURL при использовании опции ROBOKASSA_STRICT_CHECK = True,
+рекомендуется для безопасного обмена данными).
+
+Механизм строгой проверки (подтверждения через ResultURL):
+
+1. robokassa.ru, вызывает ResultURL.
+
+2. Внутри view, связанного с ResultURL, происходит проверка содержащейся в
+запросе md5 подписи через ROBOKASSA_PASSWORD2 - второй пароль, который не
+передается по сети и известен только отправителю и получателю. Он нужен
+для подтверждения того, что запрос был послан именно с robokassa.ru.
+
+3. Через callback, который принимает сигнал из этого view,
+производятся манипуляции внутри сайта (например, начисление средств согласно
+пришедшему запросу). Этот пункт необходим, если не реализуется свой view,
+а используется view, содержащийся в django-robokassa.
+
+4. Затем этот view отправляет на robokassa.ru ответ вида
+HttpResponse("".join(["OK", str(operation_id)]),
+где operation_id - уникальный id текущей операции. Этот ответ необходим в
+том числе для того, чтобы robokassa.ru получила подтверждение того, что все
+необходимые действия произведены.
+
+5. Если robokassa.ru получает этот ответ, она посылает второй запрос уже на
+SuccessURL, для вывода информативного сообщения пользователю об успешном
+прохождении всей операции. То есть, здесь должен быть только вывод оповещения.
+
+6. Либо, в случае, если HttpResponse не соответвтует ожидаемому,
+посылается запрос на FailURL, тогда пользователь видит сообщение о 
+произошедшей ошибке.
+
 Обработчики подключаются через urls.py, рендерят соответствующие
 шаблоны и шлют сигналы в зависимости от успешности платежа.
+Также можно сделать свои views, и подключить их самостоятельно через urls.py,
+а формы робокассы использовать для валидации данных.
 
 
 Сигналы
@@ -182,7 +307,6 @@ ROBOKASSA_EXTRA_PARAMS).
     result_received.connect(payment_received)
 
 
-
 urls.py
 -------