# Регистрация повторяемой оплаты {#ru_gate_payment_recurring_registration} статья о порядке регистрации через Gate оплат с сериями повторяемых списаний ## Общая информация {#section_qx5_hhm_dlb .section} Для регистрации повторяемой оплаты на стороне платёжной платформы необходимо предварительно сохранить данные платёжного инструмента пользователя. Это можно сделать разными способами, в том числе при проведении платежей через Gate, Payment Page \([подробнее](ru_pp_recurring.md)\), Dashboard \([подробнее](ru_dbl_payments.md#)\)и при переносе информации о повторяемых оплатах от стороннего эквайера \([подробнее](ru_gate_data_migration.md#)\). При регистрации повторяемой оплаты через Gate необходимо отправить запрос на проведение разовой оплаты, оплаты по ссылке или на проверку действительности платёжного инструмента с параметрами, указывающими на необходимость сохранения данных. Каждая повторяемая оплата регистрируется на заданный срок, при этом если какие-либо параметры, определяющие срок действия, не задаются со стороны мерчанта, в платформе устанавливаются значения, соответствующие сроку действия используемой платёжной карты или сроку в 10 лет с месяца регистрации этой оплаты \(подробнее [далее](ru_gate_payment_recurring_registration.md#section_vdl_vqb_cjb)\). После истечения срока действия повторяемой оплаты к веб-сервису мерчанта направляется оповещение, а выполнение списаний в рамках этой оплаты становится недоступным: запросы на списания отклоняются и к веб-сервису направляются оповещения с кодом ошибки `3184` \(или `3301`\). Регистрация повторяемых оплат может быть запрещена в рамках проекта мерчанта или для провайдера, участвующего в проведении платежа. В таком случае запрос на проведение оплаты с регистрацией повторяемой оплаты может быть отклонён. Чтобы избежать отклонения платежа можно настроить игнорирование параметров, указывающих на необходимость зарегистрировать повторяемую оплату, при наличии таких запретов. Для этого необходимо обратиться к специалистам службы технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com). При изменениях в настройках системы провайдера может требоваться новая регистрация повторяемых оплат. В таких случаях от службы технической поддержки Ecommpay мерчанту направляется письмо со списком идентификаторов повторяемых оплат, по которым следует выполнить регистрацию заново. Для этой регистрации необходимо уведомить пользователей о прекращении прежних списаний и необходимости инициирования новых, предварительно отвязав сохранённую карту, после чего инициировать регистрацию в платформе. Каждая вновь зарегистрированная повторяемая оплата получает новый идентификатор, который отправляется мерчанту в оповещении об успешной регистрации. ## Схема выполнения {#section_p3r_frb_cjb .section} Для регистрации повторяемой оплаты необходимо отправить запрос на инициирование одной из операций: `sale`, `auth`, `account verification` или `invoice`. В таком запросе необходимо передать не только параметры, обязательные для инициирования операции, но и параметры, необходимые для регистрации повторяемой оплаты. После получения запроса на инициирование одной из перечисленных операций в платёжной платформе выполняется стандартное выполнение такой операции, которое может включать в том числе выполнение вспомогательных процедур. В случае хранения данных на стороне платёжной платформы при успешном завершении операции на стороне платёжной системы или провайдера \(то есть при получении статуса операции `success`\) на стороне платёжной платформы создаётся запись о серии списаний. Этой записи присваиваются следующие атрибуты: - *Идентификатор*. После создания записи о серии списаний этот идентификатор передаётся к веб-сервису в параметре `id` объекта `recurring` оповещения о результате операции и должен использоваться в запросах на проведение повторяемой оплаты и для управления ей. - *Статус*. Как правило, при создании записи о серии списаний ей присваивается статус `active`. Этот статус может измениться на статус `canceled`, если повторяемая оплата отменена по запросу мерчанта или пользователя, а также в некоторых других случаях. В случае хранения данных на стороне веб-сервиса запись о серии списаний не создаётся. Далее от платёжной платформы к веб-сервису направляется оповещение о результате операции, в котором содержится присвоенный записи о серии списаний идентификатор, если эта запись была создана. Такое оповещение свидетельствует об успешной регистрации повторяемой оплаты. ## Регистрация с хранением данных на стороне веб-сервиса {#section_smg_vqb_cjb .section} При формировании запросов на регистрацию повторяемой оплаты с хранением платёжных данных пользователя на стороне веб-сервиса необходимо учитывать следующее: 1. Должен использоваться POST-запрос к одной из следующих конечных точек: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale), - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth), - [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification), - [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token). 2. В запросе должны использоваться обязательные для этого запроса объекты и параметры. 3. Помимо обязательных объектов и параметров в запросе должен использоваться параметр `stored_card_type` с одним из следующих значений: - `3` — для автооплаты, - `5` — для регулярной оплаты \(кроме запросов к конечной точке [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)\). Таким образом, помимо обязательных параметров корректный запрос должен содержать признак регистрации определённой категории повторяемой оплаты. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNeR+CqGrNxYyilUwSm...==" }, "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JUDY DOE", "cvv": "123", "stored_card_type": 3 // Регистрация автооплаты }, "customer": { "id": "customer_12", "ip_address": "202.144.196.0" }, "payment": { "amount": 400, "currency": "USD" } } ``` Информация о регистрации повторяемой оплаты передаётся от платёжной платформы к веб-сервису в составе оповещения о результате операции. Для этого оповещения используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). ```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_12" }, "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":"8c53d11-1160d2c", "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":"v7KN5D/aZAdeR+CqGrNxYyilUwSm...==" } ``` ## Регистрация с хранением данных на стороне платёжной платформы {#section_vdl_vqb_cjb .section} При формировании запросов на регистрацию повторяемой оплаты с хранением платёжных данных пользователя на стороне платёжной платформы необходимо учитывать следующее: 1. Должен использоваться POST-запрос к одной из следующих конечных точек: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) — при проведении разовой оплаты в одну стадию, - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth) — при проведении разовой оплаты в две стадии, - [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification) — при проверке платёжного инструмента, - [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create) — при проведении оплаты по ссылке, - [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create) — при проведении оплаты по ссылке с использованием токена. 2. В запросе должны использоваться обязательные для этого запроса объекты и параметры. 3. Помимо обязательных объектов и параметров в запросе должен использоваться объект `recurring`, содержащий параметры с информацией о регистрируемой оплате: - `register` — указатель необходимости зарегистрировать повторяемую оплату; - `type` — категория регистрируемой повторяемой оплаты, с одним из следующих значений: - `C` — для экспресс-оплаты; - `U` — для автооплаты; - `R` — для регулярной оплаты; - `period` — указатель базового периода списаний \(для регулярной оплаты\), с одним из следующих значений: - `D` — ежедневно; - `W` — еженедельно; - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\); - `Q` — ежеквартально; - `Y` — ежегодно; - `time` — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`. 4. Для регистрации регулярной оплаты также могут использоваться и другие параметры в объекте `recurring`: - `amount` — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты; - `interval` — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`, например чтобы списания выполнялись раз в три недели, в параметре `period` надо задать значение `W`, а в параметре `interval` значение `3`; - `start_date` — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`; - `expiry_day` — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\); - `expiry_month` — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\); - `expiry_year` — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\); **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. - `scheduled_payment_id` — идентификатор платежа, в рамках которого следует выполнять списания, должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта \(также не стоит путать его с идентификатором серии списаний, передаваемым в параметре `id` объекта `recurring` оповещения о регистрации повторяемой оплаты\). **Внимание:** Если идентификаторы платежа, который необходимо присвоить повторяемой оплате \(`scheduled_payment_id`\), и платежа, в рамках которого эта оплата регистрируется \(`payment_id`\), совпадают, запрос на регистрацию отклоняется. Таким образом, помимо обязательных параметров корректный запрос должен содержать признак регистрации повторяемой оплаты и её категорию, а также, при регистрации регулярной оплаты, время и периодичность списаний. В зависимости от особенностей провайдеров, участвующих в проведении платежа, набор обязательных параметров может варьироваться. Подробную информацию о требованиях провайдеров можно уточнить у курирующего менеджера Ecommpay. ```language-json { "general": { "project_id": 42, "payment_id": "567890", "signature": "v7KN1ZZ5D/aZAeR+CqGrwSm...==" }, "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JUDY DOE", "cvv": "123" }, "customer": { "id": "customer_12", "ip_address": "202.144.196.0" } "payment": { "amount": 400000, "currency": "USD" }, "recurring": { "type": "R", // Регистрация регулярной оплаты "period": "W", "interval": 3, // Списания каждые 3 недели "expiry_year": 2025, "expiry_month": 5, "expiry_day": 5, // Последнее списание 5-го мая 2025 года "time": "10:00:00", // Выполнение списаний в 10:00:00 "register": true, // Регистрация повторяемой оплаты "scheduled_payment_id": "567891", "start_date": "10-10-2020" } } ``` Информация о регистрации повторяемой оплаты передаётся от платёжной платформы к веб-сервису в составе оповещения о результате операции. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md#).При этом в состав оповещений можно включить идентификаторы соответствующих операций на стороне международной платёжной системы — в параметре `scheme_id`. Для этого необходимо обратиться к специалистам технической поддержки Ecommpay. В примере далее оповещение свидетельствует о том, что повторяемая оплата зарегистрирована и записи о серии списаний присвоен идентификатор `1001648059`. ```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_12" }, "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_Gate__payments_on_saved_data.md)