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

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

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

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

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

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

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

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

Для регистрации повторяемой оплаты необходимо отправить запрос на инициирование одной из операций: 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"
  },
  "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...=="
}

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