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

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

При работе с Payment Page можно регистрировать повторяемые оплаты. В этом разделе представлена информация о регистрации повторяемых оплат с использованием Payment Page в рамках проведения оплат и проверки действительности платёжного инструмента. Эта информация дополняет сведения из модели проведения платежей Модель проведения платежей.

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

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

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



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

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

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

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

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

Схема работы

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

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

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

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

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

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

Формат запросов

Формат запроса на открытие Payment Page для регистрации повторяемой оплаты соответствует описанному в разделе Описание Payment Page API. При формировании такого запроса необходимо учитывать следующее:

  1. В запросе должны использоваться следующие обязательные параметры:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • customer_id — идентификатор пользователя уникальный в рамках проекта;
    • payment_amount — сумма платежа в дробных единицах валюты; для регистрация повторяемой оплаты в рамках проверки действительности платёжного инструмента необходимо передавать значение 0;
    • payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
  2. Для регистрации повторяемой оплаты при проверке действительности платёжного инструмента в запросе необходимо дополнительно использовать параметр mode — индикатор режима работы Payment Page, для которого необходимо передавать значение card_verify.
  3. Для регистрации повторяемой оплаты в запросе необходимо передавать параметр recurring, представляющий собой строку, полученную в результате кодирования URL-encoded, и содержащую данные о регистрации повторяемой оплаты:
    • register, boolean — признак регистрации повторяемых оплат, для которого необходимо использовать значение true;
    • type, string — категория регистрируемой повторяемой оплаты, для которой необходимо указывать одно из следующих значений:
      • C — для экспресс-оплаты;
      • U — для автооплаты;
      • R — для регулярной оплаты;
    • period, string — периодичность списаний (для регулярного платежа), в параметре необходимо указывать одно из следующих значений:
      • D — ежедневно;
      • W — еженедельно;
      • M — ежемесячно (если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца);
      • Q — ежеквартально;
      • Y — ежегодно.
    • time, string — время выполнения последующих списаний (для регулярного платежа) в формате hh:mm:ss, передаётся, если указан параметр period;
    • interval, integer — интервал между выбранным периодом проведения оплат, в параметре необходимо передавать числовое значение от 1 до 100, например, каждые три недели. Параметр обязательно используется в связке с параметром period.
  4. Для регистрации регулярной оплаты в параметре recurring также могут использоваться и другие данные:
    • amount, integer — фиксированная сумма последующих списаний в дробных единицах валюты;
    • expiry_day, integer — день окончания проведения повторяемой оплаты;
    • expiry_month, integer — месяц окончания проведения повторяемой оплаты;
    • expiry_year, integer — год окончания проведения повторяемой оплаты;
    • scheduled_payment_id, string — идентификатор, который необходимо присвоить повторяемой оплате для автоматического инициирования списаний (параметр обязательно используется в связке с параметром start_date).
    • start_date, string — дата первого списания в формате dd-mm-yyyy (параметр обязательно используется в связке с параметром scheduled_payment_id);
  5. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом по IP-адресу пользователя: на английском (для всех стран, кроме России) или на русском (для России).
  6. Для добавления описания платежа в запросе дополнительно необходимо использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard (Dashboard Light), а также передаётся мерчанту в составе оповещения о результате платежа.
  7. Дополнительно в запросах могут использоваться любые другие параметры, используемые для работы Payment Page в режимах Purchase и Card Verify. Полный список параметров вызова Payment Page представлен в разделе Параметры открытия платежной формы Payment Page.

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

  • при проведении проверки действительности платёжного инструмента — параметры запроса на открытие Payment Page для проверки действительности платёжного инструмента и параметр recurring с данными о регистрации повторяемых оплат;
  • при проведении оплаты — параметры запроса на открытие Payment Page для проведения оплаты и параметр recurring с данными о регистрации повторяемых оплат.
{
   "project_id": "42",
   "payment_id": "567890",
   "payment_currency": "USD",
   "payment_amount": "400",
   "customer_id": "customer_1",
   "signature": "TSzdE5rJZaATYAKoGpfXriFf82MxF...",

   "recurring": "%7B%22register%22%3A%20true%2C%22type%22%3A%20%22R%22%2C%22amount%22%3A%20400%2C%22
                 expiry_day%22%3A%201%2C%22expiry_month%22%3A%208%2C%22expiry_year%22%3A%202025%2C%2
                 2interval%22%3A%2010%2C%22period%22%3A%20%22D%22%2C%22time%22%3A%20%2210%3A00%3A00%
                 22%2C%22start_date%22%3A%20%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%20%22A2
                 323%22%7D"
   
   // Строка, полученная в результате кодирования следующих данных: 
      {
        "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"
      }

}

Рис.: Пример запроса на открытие Payment Page

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=RU&language_code=ru&force_payment_method=card&recurring=%7B%22register%22%3A%20true%2C%22type%22%3A%20%22R%22%2C%22amount%22%3A%20400%2C%22expiry_day%22%3A%201%2C%22expiry_month%22%3A%208%2C%22expiry_year%22%3A%202025%2C%22interval%22%3A%2010%2C%22period%22%3A%20%22D%22%2C%22time%22%3A%20%2210%3A00%3A00%22%2C%22start_date%22%3A%20%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%20%22A2323%22%7D

Формат оповещений

Формат оповещения о выполнении оплаты или проверке действительности с регистрацией повторяемой оплаты соответствует описанному в разделе Оповещения.

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

Рис.: Пример данных о регистрации повторяемой оплаты из оповещения

{  
  "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":"424242******4243",
    "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"
  },
  "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..."
}