Работа с повторными попытками автоматических списаний

Введение

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

В случаях, когда возможность повторных попыток автоматических списаний не применяется, при отклонении любого из очередных списаний в платформе ожидается следующее (согласно графику; подробнее) и со стороны мерчанта должны приниматься решения относительно необходимости дополнительного внеочередного списания или завершения серии списаний в целом.

Особенности

При работе с повторными попытками автоматических списаний стоит учитывать следующие особенности:

• для каждого проекта может использоваться свой график выполнения повторных попыток — базовый от ecommpay или индивидуально заданный со стороны мерчанта;
• повторные попытки применимы для ограниченного числа глобальных платёжных методов — классических карточных платежей, и альтернативных методов Apple Pay и Google Pay;
• повторные попытки применимы только для регулярных оплат с хранением графика списаний на стороне платёжной платформы (с типом R);
• повторные попытки могут выполняться только в тех случаях, когда предшествующие попытки списаний были отклонены при отклонении предшествующих попыток списаний на стороне платёжной системы или эмитента;
• применение повторных попыток не гарантирует итогового списания средств — если допустимое число попыток не приводит к списанию, такое списание считается отклонённым (со статусом операции decline) и целевая оплата проводится в платформе дальше согласно её графику.

Варианты применения

Способы применения повторных попыток списаний можно рассмотреть на частных примерах.

Если в рамках повторяемой оплаты плановые списания инициируются по понедельникам в 12:00 и по графику должны быть выполнены 02, 09, 16 и 23 ноября, но 09 и 16 ноября плановых списаний средств не происходит, то реагирование на такую ситуацию может обеспечиваться следующим образом:

1. Если повторные попытки для такой оплаты недоступны, то независимо от того, было ли выполнено или отклонено очередное списание, за ним вслед за каждым отклонённым списанием планируется и выполняется следующее.
2. Если для повторных попыток используется базовый график от ecommpay, то вслед за отклонением исходной попытки любого из очередных списаний для него обеспечивается актуальное число повторных попыток: две первые с интервалом в 12 часов и последующие с интервалом в 24 часа и остановкой не менее чем за 24,5 часа до очередного списания в понедельник.
3. Если для повторных попыток используется базовый график от ecommpay и со стороны веб-сервиса отменяются дальнейшие повторные попытки после трёх подряд отклонённых, то вслед за отклонением исходной попытки любого из очередных списаний для него обеспечивается актуальное число повторных попыток, но не более трёх подряд.
4. Если для повторных попыток используется индивидуальный график от мерчанта, то вслед за отклонением исходной попытки любого из очередных списаний для него обеспечивается актуальное число повторных попыток: с интервалами, кратными 24 часам, и остановкой не менее чем за 24,5 часа до очередного списания в понедельник.

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

Общая информация

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

Основные свойства этих графиков можно сопоставить следующим образом.

• В базовом случае для каждого очередного списания допускается не более 7 повторных попыток, которые могут быть выполнены в течение 6 суток.

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

• В случае с индивидуальным графиком для каждого очередного списания допускается от 1 до 10 повторных попыток, которые могут быть выполнены в течение 10 суток.

  При этом интервал перед выполнением любой повторной попытки может быть произвольным, но должен быть кратным 24 часам и с ограничением, что до следующего планового списания (согласно графику списаний) остаётся не менее 24,5 часов. Например, для ежемесячных списаний четыре попытки повторных списаний могут быть выстроены с увеличивающимися интервалами в 24, 48, 72 и 96 часов (на 1, 3, 6 и 10 сутки, с соблюдением ограничений на общий период в 10 суток и на время до очередного списания не менее 24,5 часов).

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

Также при работе с Gate API следует учитывать, что для выполнения запросов по работе с графиком повторных попыток списаний используется синхронная схема взаимодействия между веб-сервисом и платёжной платформой. В рамках этой схемы каждый запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа (200) и запрошенная информация без указания статуса запроса. В случаях, когда запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса error и описание причины обнаруженной ошибки. Описание типового формата ответа представлено в отдельной статье.

Также следует учитывать, что для выполнения запросов по работе с графиком повторных попыток списаний используется синхронная схема взаимодействия между веб-сервисом и платёжной платформой, когда каждый запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса с предоставлением актуального ответа (подробнее).

Настройка индивидуального графика

Чтобы настроить через Gate API индивидуальный график повторных попыток для автоматических списаний в рамках конкретного проекта, следует:

1. Отправить POST-запрос к конечной точке /v2/recurring/retry-custom-schedule/save.
2. Принять синхронный ответ об изменении графика в платформе.

При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным); (подробнее),
• interval_days — массив с порядковыми номерами дней для выполнения повторных попыток, отсчитываемых от того дня, в который была отклонена исходная попытка целевого списания, и указываемых в виде последовательности возрастающих чисел в диапазоне от 1 до 10, последовательно по возрастанию и через запятую в качестве разделителя (например: [1,5,9]).

Таким образом, корректный запрос должен содержать идентификатор проекта, подпись и массив interval_days. В следующем примере повторные попытки списаний должны быть запланированы на 1, 5 и 9 сутки с момента отклонения исходной попытки списания.

{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}

{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}

При выполнении такого запроса на настройку индивидуального графика от платёжной платформы к веб-сервису передаётся ответ с кодом 200 OK, а при отклонении — с указанием статуса обработки запроса error и поясняющего описания, например Recurring retry not enabled.

Проверка графика

Чтобы проверить через Gate API график повторных попыток для автоматических списаний, используемый в рамках конкретного проекта, следует:

1. Отправить POST-запрос к конечной точке /v2/recurring/retry-custom-schedule/info.
2. Принять синхронный ответ с информацией о графике.

При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным) (подробнее).

Таким образом, корректный запрос должен содержать идентификатор проекта и подпись.

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}

При выполнении такого запроса на получение сведений об используемом графике от платёжной платформы к веб-сервису передаётся ответ с кодом 200 OK и с актуальной информацией, а при отклонении — с указанием статуса обработки запроса error и поясняющего описания. В теле ответа со сведениями о графике указываются идентификатор проекта и объект schedule.

Если для целевого проекта в платформе задан индивидуальный график повторных попыток, в объект schedule включаются следующие параметры:

• interval_days — массив с порядковыми номерами дней для выполнения повторных попыток, отсчитываемых от того дня, в который была отклонена исходная попытка целевого списания, и указываемых в виде последовательности возрастающих чисел в диапазоне от 1 до 10, последовательно по возрастанию и через запятую в качестве разделителя (например: [1,5,9]).
• status — указатель использования индивидуального графика (со значением active, подтверждающим, что для целевого проекта был задан и не деактивирован индивидуальный график).

Если для целевого проекта используется базовый график от ecommpay, объект schedule передаётся с пустым значением.

В следующем примере содержится информация о том, что для проекта 42 используется индивидуальный график, в рамках которого предусмотрены повторные попытки списаний на 1, 5 и 9 сутки с момента отклонения исходной попытки списания.

{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}

{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}

В следующем примере отсутствуют сведения об индивидуальном графике, что свидетельствует об использовании для проекта 42 базового графика повторных попыток.

{
  "project_id": 42,
  "schedule": {}
}

{
  "project_id": 42,
  "schedule": {}
}

Сброс графика к базовым значениям

Чтобы вернуть к базовым значениям график повторных попыток для автоматических списаний в рамках конкретного проекта, используя Gate API, следует:

1. Отправить POST-запрос к конечной точке /v2/recurring/retry-custom-schedule/disable.
2. Принять синхронный ответ о выполнении запроса.

При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным) (подробнее).

Таким образом, корректный запрос должен содержать идентификатор проекта и подпись.

{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}

{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}

При выполнении такого запроса на сброс графика к базовым значениям от платёжной платформы к веб-сервису передаётся ответ с кодом 200 OK, а при отклонении — с указанием статуса обработки запроса error и поясняющего описания.