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

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

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

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
  }
}

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 42 для пользователя customer_12 было выполнено списание в размере 4,00 USD с платёжной карты № 424242******4243 и ожидаются последующие списания.

{  
  "customer":{  
    "id":"customer_12"
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2026"
  },
  "payment":{  
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "method":"card",
    "date":"2023-06-07T06:18:02+0000",
    "status":"scheduled recurring processing",    // Статус платежа
    "type":"recurring",    // Тип платежа
    "id":"456789",
    "description":""
  },
  "project_id":42,
  "recurring":{  
    "valid_thru":"2023-07-31T00:00:00+0000",
    "currency":"USD",
    "id":1079    // Идентификатор серии списаний
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",    // Тип операции
    "status":"success",    // Статус операции
    "date":"2023-06-07T06:18:02+0000",
    "created_date":"2023-06-07T06:18:02+0000",
    "request_id":"5cfa0199c33071",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":6,
      "payment_id":"1192",
      "date":"2023-02-07T08:34:24+0000",
      "auth_code":"5253",
      "endpoint_id":6
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...=="
}

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