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

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

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

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

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

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

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

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

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

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

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

Схема работы

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

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

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

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

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

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

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

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

  1. В запросе должны использоваться следующие обязательные параметры:
    • project_id — идентификатор проекта, полученный от Rocketpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • customer_id — идентификатор пользователя уникальный в рамках проекта;
    • payment_amount — сумма платежа в дробных единицах валюты; для регистрация повторяемой оплаты в рамках проверки действительности платежного инструмента необходимо передавать значение 0;
    • payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи).
  2. Для регистрации повторяемой оплаты при проверке действительности платежного инструмента в запросе необходимо дополнительно использовать параметр mode — индикатор режима работы Payment Page, для которого необходимо передавать значение card_verify.
  3. Для регистрации повторяемой оплаты в запросе необходимо передавать параметр recurring, представляющий собой строку, полученную в результате кодирования URL-encoding, и содержащую данные о регистрации повторяемой оплаты:
    • 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, string — день окончания проведения повторяемой оплаты;
    • expiry_month, string — месяц окончания проведения повторяемой оплаты;
    • 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, а также передается мерчанту в составе оповещения о результате платежа.
  7. Дополнительно в запросах могут использоваться любые другие параметры, используемые для работы Payment Page в режимах Purchase и Card Verify. Полный список параметров вызова Payment Page представлен в разделе Параметры открытия платежной страницы Payment Page.

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

  • при проведении проверки действительности платежного инструмента — параметры запроса на открытие Payment Page для проверки действительности платежного инструмента и параметр recurring с данными о регистрации повторяемых оплат;
  • при проведении оплаты — параметры запроса на открытие Payment Page для проведения оплаты и параметр recurring с данными о регистрации повторяемых оплат.

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

{
    "register": true,     //регистрация повторяемой оплаты
    "type": "R",          //регистрация регулярной оплаты
    "amount": 400,
    "expiry_day": "01"
    "expiry_month": "08",
    "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"
}

Рис.: Пример параметра recurring с данными, преобразованными в URL-строку

"recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22
                 expiry_day%22%3A%2201%22%2C%22expiry_month%22%3A%2208%22%2C%22expiry_year%
                 22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%
                 2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%
                 22scheduled_payment_id%22%3A%22A2323%22%7D"

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

https://paymentpage.rocketpay.kz/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%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry_day%22%3A%2201%22%2C%22expiry_month%22%3A%2208%22%2C%22expiry_year%22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D

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

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

В следующем примере содержится информация о том, что в рамках проекта 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..."
}