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

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

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

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

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

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

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

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

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

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

Схема работы

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

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

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

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

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

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

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

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

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от ecommpay;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • customer_id — идентификатор пользователя уникальный в рамках проекта;
   • payment_amount — сумма платежа в дробных единицах валюты; для регистрация повторяемой оплаты в рамках проверки действительности платёжного инструмента необходимо передавать значение 0;
   • payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
   • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
   Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. К параметрам, которые становятся обязательными для таких случаев, относятся customer_email и customer_phone (подробнее). Эти параметры можно включать в состав запроса на открытие Payment Page или запрашивать у пользователей (подробнее).
2. Для регистрации повторяемой оплаты при проверке действительности платёжного инструмента необходимо дополнительно использовать параметр mode — индикатор режима работы Payment Page, для которого необходимо передавать значение card_verify.
3. Для указания свойств повторяемой оплаты необходимо передавать параметр recurring — в виде объекта JSON, если для вызова платёжной формы используется JavaScript-библиотека ecommpay, или в виде строки, полученной в результате кодирования URL-encoding, если платёжная форма вызывается иным способом. Параметр recurring должен содержать основные сведения о регистрации повторяемой оплаты:
   • 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 или string — день окончания проведения повторяемой оплаты;
   • expiry_month, integer или string — месяц окончания проведения повторяемой оплаты;
   • expiry_year, integer — год окончания проведения повторяемой оплаты;
   • start_date, string — дата первого списания в формате dd-mm-yyyy (параметр обязательно используется в связке с параметром scheduled_payment_id);
   • scheduled_payment_id, string — идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта (также не стоит путать его с идентификатором серии списаний, передаваемым в параметре id объекта recurring оповещения о регистрации повторяемой оплаты).
     Внимание: Если идентификаторы платежа, который необходимо присвоить повторяемой оплате (scheduled_payment_id), и платежа, в рамках которого эта оплата регистрируется (payment_id), совпадают, запрос на регистрацию отклоняется.
5. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее).
6. Для добавления описания платежа можно использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа.
7. Дополнительно могут использоваться любые другие параметры, применимые в режимах работы Purchase и Card Verify платёжной формы Payment Page. Полный список параметров вызова Payment Page представлен в разделе Параметры вызова платёжной формы.

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

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

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

"recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22
                 expiry_day%22%3A1%2C%22expiry_month%22%3A8%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"

EPayWidget.run(
    { payment_id: '567890',
      payment_amount: '400',
      customer_id: 'customer1',
      payment_currency: 'USD',
      project_id: 42,
      force_payment_method: 'card',
      recurring: '{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}',
      signature: 'qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...' },
    'post')

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=GB&language_code=en&force_payment_method=card&recurring=%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry_day%22%3A1%2C%22expiry_month%22%3A8%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

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

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

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

{  
  "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": "431422******0056",
    "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"
  },
  "scheme_id":"MCS38A0790706",
  "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..."
}