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

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

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

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

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

Регистрация повторяемых оплат может быть запрещена в рамках проекта мерчанта или для провайдера, участвующего в проведении платежа. В таком случае запрос на проведение оплаты с регистрацией повторяемой оплаты может быть отклонён. Чтобы избежать отклонения платежа можно настроить игнорирование параметров, указывающих на необходимость зарегистрировать повторяемую оплату, при наличии таких запретов. Для этого необходимо обратиться к специалистам службы технической поддержки — support@ecommpay.com.

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

Схема выполнения

Для регистрации повторяемой оплаты необходимо отправить запрос на инициирование одной из операций: sale, auth, account verification или invoice. В таком запросе необходимо передать не только параметры, обязательные для инициирования операции, но и параметры, необходимые для регистрации повторяемой оплаты.

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

• Идентификатор. После создания записи о серии списаний этот идентификатор передаётся к веб-сервису в параметре id объекта recurring оповещения о результате операции и должен использоваться в запросах на проведение повторяемой оплаты и для управления ей.
• Статус. Как правило, при создании записи о серии списаний ей присваивается статус active. Этот статус может измениться на статус canceled, если повторяемая оплата отменена по запросу мерчанта или пользователя, а также в некоторых других случаях.

В случае хранения данных на стороне веб-сервиса запись о серии списаний не создаётся.

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

Регистрация с хранением данных на стороне веб-сервиса

При формировании запросов на регистрацию повторяемой оплаты с хранением платёжных данных пользователя на стороне веб-сервиса необходимо учитывать следующее:

1. Должен использоваться POST-запрос к одной из следующих конечных точек:
   • /v2/payment/card/sale,
   • /v2/payment/card/auth,
   • /v2/payment/card/account_verification,
   • /v2/payment/card/account_verification/token.
2. В запросе должны использоваться обязательные для этого запроса объекты и параметры.
3. Помимо обязательных объектов и параметров в запросе должен использоваться параметр stored_card_type с одним из следующих значений:
   • 3 — для автооплаты,
   • 5 — для регулярной оплаты (кроме запросов к конечной точке /v2/payment/card/account_verification/token).

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

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNeR+CqGrNxYyilUwSm...=="
  },
  "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123",
      "stored_card_type": 3    // Регистрация автооплаты
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  },
  "payment": {
      "amount": 400,
      "currency": "USD"
  }
}

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

{  
  "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_12"
  },
  "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":"8c53d11-1160d2c",
    "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":"v7KN5D/aZAdeR+CqGrNxYyilUwSm...=="
}

Регистрация с хранением данных на стороне платёжной платформы