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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Должен использоваться POST-запрос к одной из следующих конечных точек:
  2. В запросе должны использоваться обязательные для этого запроса объекты и параметры.
  3. Помимо обязательных объектов и параметров в запросе должен использоваться параметр 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_1",
      "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":"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...=="
}

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

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

  1. Должен использоваться POST-запрос к одной из следующих конечных точек:
  2. В запросе должны использоваться обязательные для этого запроса объекты и параметры.
  3. Помимо обязательных объектов и параметров в запросе должен использоваться объект recurring, содержащий параметры с информацией о регистрируемой оплате:
    • register — признак регистрации повторяемой оплаты, необходимо использовать значение true;
    • type — категория регистрируемой повторяемой оплаты, необходимо использовать одно из следующих значений:
      • C — для экспресс-оплаты,
      • U — для автооплаты,
      • R — для регулярной оплаты;
    • time — время последующих списаний (для регулярной оплаты) в формате hh:mm:ss;
    • period — периодичность списаний (для регулярной оплаты):
      • D — ежедневно,
      • W — еженедельно,
      • M — ежемесячно,
      • Q — ежеквартально,
      • Y — ежегодно.
  4. Для регистрации регулярной оплаты также могут использоваться и другие параметры в объекте 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_1",
      "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_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...=="
}