Проведение оплаты с автоматическими списаниями

Проведение с инициированием списаний при регистрации платежа

В базовом случае, когда при регистрации повторяемой оплаты передаётся параметр scheduled_payment_id, для проведения повторяемой оплаты с автоматическими списаниями необходимо:

1. Зарегистрировать повторяемую оплату.
2. Принять от платёжной платформы оповещение о результате списания.
3. Продолжать принимать оповещения о результате каждого списания в рамках платежа.

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

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

Проведение с отдельным инициированием списаний

В случае, если при регистрации повторяемой оплаты не передаётся параметр scheduled_payment_id, для проведения повторяемой оплаты с автоматическими списаниями необходимо:

1. Зарегистрировать повторяемую оплату.
2. Передать запрос на проведение повторяемой оплаты с идентификатором записи о серии списаний.
3. Принять от платёжной платформы оповещение о результате списания.
4. Продолжать принимать оповещения о результате каждого списания в рамках платежа.

Проведение с повторными попытками списаний

В случае, если для проекта подключены повторные попытки списаний, необходимо:

1. Зарегистрировать повторяемую оплату.
2. Если при регистрации оплаты не был передан параметр scheduled_payment_id, передать запрос на проведение повторяемой оплаты с идентификатором записи о серии списаний (recurring.id).
3. Принять от платёжной платформы оповещения о результате списания (одно или несколько, в зависимости от количества выполненных повторных попыток).
4. Продолжать принимать оповещения о результате каждого планового списания и повторных попытках его выполнения (при их наличии) в рамках платежа. И при необходимости отменять выполнение повторных попыток для конкретных списаний (через Gate или Dashboard).

   Стоит учитывать, что при отменах повторных попыток списаний оповещения о таких отменах не отправляются.

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

Запрос на инициирование повторяемой оплаты

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/card/recurring.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта и имеющий то же значение, которое было использовано при регистрации данной повторяемой оплаты;,
       Внимание: Использование разных идентификаторов пользователя для операций в рамках одной повторяемой оплаты не допускается
     • ip_address — IP-адрес пользователя, актуальный для инициируемой операции;,
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • recurring — объект, содержащий сведения повторяемой оплате:
     • id — идентификатор записи о серии списаний, полученный в оповещении после регистрации повторяемой оплаты или заданный при переносе информации об этой оплате от стороннего эквайера.
3. С учётом региональных особенностей и специфики провайдеров, участвующих в проведении платежей, могут быть обязательны и некоторые другие параметры. Информацию о таких особенностях и требованиях провайдеров можно уточнять у курирующего менеджера ecommpay.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"K5D/aZAMdeR+YyilUwS=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079
  }
}

Запрос на отмену повторных попыток списания

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

1. Для инициирования каждой отмены должен использоваться отдельный POST-запрос к конечной точке /v2/recurring/retry_stop.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор записи о серии списаний, полученный в оповещении после регистрации повторяемой оплаты или заданный при переносе информации об этой оплате от стороннего эквайера;,
   • trigger_operation_id — идентификатор списания, для которого необходимо отменить выполнение повторных попыток.

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

{ 
  "general":{ 
    "project_id":42,
    "signature":"K5D/anjn7fv+YyilUwS=="
  },
  "recurring":{
    "id":1079
   },
  "trigger_operation_id":092384
}