# Регистрация повторяемых оплат {#ru_pp_recurring}

статья о порядке регистрации через Payment Page оплат с сериями повторяемых списаний

**Прим.:** Эта статья посвящена тому, как регистрировать повторяемые оплаты через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт.

Помимо этой статьи для работы с повторяемыми оплатами могут быть полезны:

-   статьи [Повторяемая оплата со списаниями по запросам](ru_platform_recurring_model.md) и [Повторяемая оплата с автоматическими списаниями](ru_platform_sheduled_recurring_model.md) модели проведения платежей с описанием того, как в целом проводятся повторяемые оплаты в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций;
-   статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как регистрировать повторяемые оплаты через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом.

## Общая информация {#section_ibx_bdh_zlb .section}

Платёжная платформа Ecommpay позволяет регистрировать повторяемые оплаты разными способами, в том числе при проведении платежей через интерфейсы Payment Page, Gate \([подробнее](ru_gate_payment_recurring_registration.html)\) и Dashboard \([подробнее](ru_dbl_payments.md#)\), а также при переносе информации о повторяемых оплатах от стороннего эквайера \([подробнее](ru_gate_data_migration.md#)\). В этом разделе представлена информация о регистрации повторяемых оплат с использованием Payment Page в рамках проведения оплат и проверки действительности платёжного инструмента.

*Повторяемая оплата* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется повторяемый перевод денежных средств от пользователя к мерчанту. При этом для проведения платежа используются сохранённые платёжные данные, а подтверждение подлинности платёжного инструмента пользователя \(такое, как ввод кода проверки подлинности карты\) не требуется.

Использование повторяемой оплаты может быть актуальным при выстраивании долгосрочных отношений с пользователями, когда важно предоставлять им возможность удобной оплаты без дополнительных действий с их стороны.

**Прим.:** В случае открытия платёжной формы для регистрации повторяемой оплаты пользователю отображаются только те платёжные методы, для которых поддерживается такая регистрация \([подробнее](ru_pm_about.md)\).

Базовыми действиями пользователя при регистрации повторяемых оплат с использованием Payment Page могут быть выбор платёжного инструмента, указание его реквизитов и ожидание уведомления о результате платежа.

![](images/ecommpay/ru_pp_recurring.svg)

В платёжной платформе поддерживаются следующие категории повторяемых оплат:

-   *Экспресс-оплаты*. Списания в рамках таких оплат инициируются пользователем и выполняются без привязки к расписанию или сумме платежа. Например, пользователь онлайн-кинотеатра может оплатить прокат одного или нескольких фильмов с использованием сохранённых данных карты.
-   *Автооплаты*. Списания в рамках таких оплат инициируются мерчантом и выполняются нерегулярно или на различные суммы. Например, когда остаток средств на счёте пользователя становится ниже заданного, выполняется списание средств с его платёжной карты для пополнения этого счёта.
-   *Регулярные оплаты*. Списания в рамках таких оплат инициируются мерчантом по заданному графику и на фиксированную сумму. График таких списаний может храниться как на стороне веб-сервиса, так и на стороне платёжной платформы. Например, с пользователя онлайн-кинотеатра может ежемесячно списываться фиксированная сумма для оплаты доступа к просмотру всех фильмов кинотеатра.

Для регистрации любой повторяемой оплаты, вне зависимости от категории, необходимо получить согласие пользователя на хранение его платёжных данных и их дальнейшее использование на определённых условиях.

Для регистрации повторяемых оплат используются режимы работы платёжной формы Purchase или Card Verify. Для инициирования проведения повторяемой оплаты, изменения условий её проведения или её отмены, а также для выполнения возврата средств пользователю можно использовать [Gate](ru_Gate__payments_on_saved_data.md) \(для всех типов повторяемых оплат\) и [Dashboard](ru_dbl_payments.md#) \(для регулярных оплат\).

При изменениях в настройках системы провайдера может требоваться новая регистрация повторяемых оплат. В таких случаях от службы технической поддержки Ecommpay мерчанту направляется письмо со списком идентификаторов повторяемых оплат, по которым следует выполнить регистрацию заново. Для этой регистрации необходимо уведомить пользователей о прекращении прежних списаний и необходимости инициирования новых, предварительно отвязав сохранённую карту, после чего инициировать регистрацию в платформе. Каждая вновь зарегистрированная повторяемая оплата получает новый идентификатор, который отправляется мерчанту в оповещении об успешной регистрации.

## Схема работы {#section_erl_5qh_zlb .section}

Для регистрации повторяемых оплат с помощью Payment Page со стороны веб-сервиса необходимо:

1.  Сформировать и отправить в платёжную платформу запрос на открытие Payment Page.
2.  Принять оповещение о результате выполнения запроса со стороны платёжной платформы.

При регистрации повторяемых оплат может потребоваться выполнение вспомогательных процедур:

-   *Аутентификация 3‑D Secure*, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\).
-   *Аутентификация по инициативе мерчанта*, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения.
-   *Дополнение информации о платеже*, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме.

Такие процедуры выполняются без участия веб-сервиса мерчанта, но, как правило, требуют участия пользователя.

Информация о форматах запросов и оповещений для регистрации повторяемых оплат с прямым использованием платёжных карт представлена далее, а о форматах запросов и оповещений с использованием других платёжных методов представлена в разделе [Методы](ru_pm_about.md).

## Формат запросов {#section_fjz_4yy_1mb .section}

Формат запроса на открытие Payment Page для регистрации повторяемой оплаты соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md#). При формировании такого запроса необходимо учитывать следующее:

1.  Должен использоваться базовый минимум параметров, обязательный для любого платежа:
    -   `project_id` — идентификатор проекта, полученный от Ecommpay;
    -   `payment_id` — идентификатор платежа, уникальный в рамках проекта;
    -   `customer_id` — идентификатор пользователя уникальный в рамках проекта;
    -   `payment_amount` — сумма платежа в дробных единицах валюты; для регистрация повторяемой оплаты в рамках проверки действительности платёжного инструмента необходимо передавать значение `0`;
    -   `payment_currency` — код валюты платежа в формате ISO 4217 alpha-3;
    -   `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\).
2.  Для регистрации повторяемой оплаты при проверке действительности платёжного инструмента необходимо дополнительно использовать параметр `mode` — индикатор режима работы Payment Page, для которого необходимо передавать значение `card_verify`.
3.  Для указания свойств повторяемой оплаты необходимо передавать параметр `recurring` — в виде объекта JSON, если для вызова платёжной формы используется JavaScript-библиотека Ecommpay, или в виде строки, полученной в результате кодирования URL-encoding, если платёжная форма вызывается иным способом. Параметр `recurring` должен содержать основные сведения о регистрации повторяемой оплаты:
    -   `register`, boolean — указатель необходимости зарегистрировать повторяемую оплату;
    -   `type`, string — категория регистрируемой повторяемой оплаты, с одним из следующих значений:
        -   `C` — для экспресс-оплаты;
        -   `U` — для автооплаты;
        -   `R` — для регулярной оплаты;
    -   `period`, string — указатель базового периода списаний \(для регулярной оплаты\), с одним из следующих значений:
        -   `D` — ежедневно;
        -   `W` — еженедельно;
        -   `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\);
        -   `Q` — ежеквартально;
        -   `Y` — ежегодно;
    -   `interval`, integer — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`;
    -   `time`, string — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`.
4.  Для указания свойств регулярной оплаты в параметре `recurring` также могут использоваться и другие сведения:
    -   `amount`, integer — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты;
    -   `start_date`, string — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`;
    -   `expiry_day`, integer илиstring — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\);
    -   `expiry_month`, integer илиstring — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\);
    -   `expiry_year`, integer — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\);

        **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения:

        -   для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты;
        -   для других доступных методов — значение соответствующего параметра согласно следующим правилам:
            -   для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\);
            -   для месяца — месяц регистрации повторяемой оплаты;
            -   для года — год, превышающий год регистрации повторяемой оплаты на 10 лет.
        Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год.

    -   `scheduled_payment_id`, string — идентификатор платежа, в рамках которого следует выполнять списания, должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта \(также не стоит путать его с идентификатором серии списаний, передаваемым в параметре `id` объекта `recurring` оповещения о регистрации повторяемой оплаты\).

        **Внимание:** Если идентификаторы платежа, который необходимо присвоить повторяемой оплате \(`scheduled_payment_id`\), и платежа, в рамках которого эта оплата регистрируется \(`payment_id`\), совпадают, запрос на регистрацию отклоняется.

5.  Для указания обязательных сведений о пользователе в случае, если не используется возможность указания таких сведений самим пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\), в запросе дополнительно необходимо использовать по крайней мере один из следующих параметров: `customer_email` и `customer_phone`.
6.  Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\).
7.  Для добавления описания платежа можно использовать параметр `payment_description`, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа.
8.  Дополнительно могут использоваться любые другие параметры, применимые в режимах работы Purchase и Card Verify платёжной формы Payment Page. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md).

Таким образом, запрос на регистрацию повторяемых оплат должен содержать:

-   при проведении проверки действительности платёжного инструмента — параметры запроса на открытие Payment Page для проверки действительности платёжного инструмента и параметр `recurring` с данными о регистрации повторяемых оплат;
-   при проведении оплаты — параметры запроса на открытие Payment Page для проведения оплаты и параметр `recurring` с данными о регистрации повторяемых оплат.

```language-json
{
    "register": true,     //регистрация повторяемой оплаты
    "type": "R",          //регистрация регулярной оплаты
    "amount": 400,
    "expiry_day": 1,
    "expiry_month": 8,
    "expiry_year": 2025,  //последнее списание 1-го августа 2025 года
    "interval": 10,
    "period": "D",        //списания каждые 10 дней
    "time": "10:00:00",   //выполнение списаний в 10:00:00
    "start_date": "14-05-2019",
    "scheduled_payment_id": "A2323"
}
```

```
"recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22
                 expiry_day%22%3A1%2C%22expiry_month%22%3A8%2C%22expiry_year%
                 22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%
                 22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%
                 22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D"
```

```
EPayWidget.run(
    { payment_id: '567890',
      payment_amount: '400',
      customer_id: 'customer1',
      payment_currency: 'USD',
      project_id: 42,
      force_payment_method: 'card',
      recurring: '{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}',
      signature: 'qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...' },
    'post')
```

```language-json
https://paymentpage.ecommpay.com/payment?signature=qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...&payment_id=567890&payment_amount=400&payment_currency=USD&project_id=42&customer_id=customer_1&region_code=GB&language_code=en&force_payment_method=card&recurring=%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry\_day%22%3A1%2C%22expiry\_month%22%3A8%2C%22expiry_year%22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D
```

## Формат оповещений {#section_mbv_cmk_1mb .section}

Формат оповещения о выполнении оплаты или проверке действительности с регистрацией повторяемой оплаты соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md#).

В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_1` зарегистрировано проведение повторяемых оплат с использованием платёжной карты `431422******0056`.

```language-json
{  
  "project_id": 42,
  "payment":{  
    "id": "567890",
    "type": "purchase",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "method": "card",
    "sum":{  
      "amount": 400,
      "currency": "USD"
    },
    "description": ""
  },
  "account":{  
    "number": "431422******0056",
    "token": "d927d3f006008edf5c07661",
    "type": "visa",
    "card_holder": "JUDY DOE",
    "expiry_month": "08",
    "expiry_year": "2025"
  },
  "customer":{  
    "id": "customer_1"
  },
  "recurring":{  
    "id": 1001648059,    // Идентификатор записи о серии списаний
    "currency": "USD",
    "valid_thru": "2019-05-20T00:00:00+0000"
  },
  "scheme\_id":"MCS38A0790706",
  "operation":{  
    "id": 22136002040,
    "type": "sale",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "created_date": "2019-05-14T12:52:42+0000",
    "request_id": "8c77279053d011-1160421d51e11f87d2c",
    "sum_initial":{  
      "amount": 400,
      "currency": "USD"
    },
    "sum_converted":{  
      "amount": 400,
      "currency": "USD"
    },
    "provider":{  
      "id": 414,
      "payment_id": "00200011764",
      "date": "2019-05-14T12:52:55+0000",
      "auth_code": "231567",
      "endpoint_id": 414
    },
    "code": "0",
    "message": "Success",
    "eci": "07"
  },
  "signature": "v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm..."
}
```

**На уровень выше:**[Основные действия](ru_pp_basic_actions.md)