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

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

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

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

Прим.: В соответствии с рекомендациями международных платежных систем Visa и Mastercard от 2020 года временно поддерживается выполнение списаний в рамках повторяемой оплаты для платежных карт с истекшим сроком действия — при условии, что такая возможность поддерживается и на стороне провайдера или платежной системы. Списания в этом случае могут выполняться как до истечения срока действия повторяемой оплаты, так и после истечения этого срока, если срок действия задан как равный сроку действия платежной карты. Для исключения такой возможности следует изменить условия повторяемой оплаты, указав в параметрах запроса год и месяц окончания срока действия этой оплаты, отличные от срока действия карты (подробнее — Изменение условий серии списаний).

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

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

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

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

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

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

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

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

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

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

Должен использоваться POST-запрос к одной из следующих конечных точек:
В запросе должны использоваться обязательные для этого запроса объекты и параметры.
Помимо обязательных объектов и параметров в запросе должен использоваться параметр stored_card_type с одним из следующих значений:
- 3 — для автооплаты,
- 5 — для регулярной оплаты.

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

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

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNeR+CqGrNxYyilUwSm...=="
  },
  "card": {
      "pan": "4242424242424243",
      "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"
  }
}

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

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

{  
  "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_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...=="
}

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

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

Должен использоваться POST-запрос к одной из следующих конечных точек:
В запросе должны использоваться обязательные для этого запроса объекты и параметры.
Помимо обязательных объектов и параметров в запросе должен использоваться объект recurring, содержащий параметры с информацией о регистрируемой оплате:
- register — признак регистрации повторяемой оплаты, необходимо использовать значение true;
- type — категория регистрируемой повторяемой оплаты, необходимо использовать одно из следующих значений:
  - C — для экспресс-оплаты,
  - U — для автооплаты,
  - R — для регулярной оплаты;
- time — время последующих списаний (для регулярной оплаты) в формате hh:mm:ss;
- period — периодичность списаний (для регулярной оплаты):
  - D — ежедневно,
  - W — еженедельно,
  - M — ежемесячно,
  - Q — ежеквартально,
  - Y — ежегодно.
Для регистрации регулярной оплаты также могут использоваться и другие параметры в объекте recurring:
- expiry_year — год окончания действия повторяемой оплаты;
- expiry_month — месяц окончания действия повторяемой оплаты;
- expiry_day — день окончания действия повторяемой оплаты;
- interval — множитель для кратного увеличения периода списаний, например чтобы списания выполнялись раз в три недели, в параметре period надо задать значение W, а в параметре interval значение 3; возможные значения: от 1 до 100;
- amount — сумма последующих списаний;
- scheduled_payment_id — идентификатор, который необходимо присвоить повторяемой оплате (для автоматического инициирования списаний);
- start_date — дата первого списания.

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

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

{
  "general": {
      "project_id": 42,
      "payment_id": "567890",
      "signature": "v7KN1ZZ5D/aZAeR+CqGrwSm...=="
  },
  "card": {
      "pan": "4242424242424243",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123"
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  }
  "payment": {
      "amount": 400000,
      "currency": "USD"
  },
  "recurring": {
      "type": "R",
// Регистрация регулярной оплаты
      "period": "W",
      "interval": 3,
// Списания каждые 3 недели
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
// Последнее списание 5-го мая 2025 года
      "time": "10:00:00",
// Выполнение списаний в 10:00:00
      "register": true,
// Регистрация повторяемой оплаты
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}

В примере далее оповещение свидетельствует о том, что повторяемая оплата зарегистрирована и записи о серии списаний присвоен идентификатор 1001648059.

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

{  
  "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_12"
  },
  "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...=="
}

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

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

{
  "general": {
    "project_id": 111,
    "payment_id": "45611111",
    "signature": "s2eoM1aloGxDhYsLCpfwnnbL0FQkzAgi2Wrd0A9Edt4ycDwx3n3jnC3V1PtnrMsFsc9gH+*******"
  },
  "customer": {
    "ip_address": "248.1.1.1",
    "id": "1"
  },
  "payment": {
    "amount": 1000,
    "currency": "KZT",
    "extra_param": "recurring" // обязательный параметр в данном функционале 
  },
  "token": "d5c6a06d727128380530176eff82a128a6c6a1b***************",
  "card": {
    "save": false
  }
}