Управление списаниями в рамках оплаты

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

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

  • получение сведений о серии списаний;
  • изменение условий: суммы и срока действия, а для регулярных оплат — параметров, задающих график списаний;
  • отмена дальнейшего выполнения списаний со стороны мерчанта.

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

Помимо этого, управлять списаниями для регулярных оплат можно через интерфейс Dashboard.

Получение сведений о серии списаний

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

  1. Должен использоваться POST-запрос к конечной точке /v2/payment/card/recurring/info.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
    • Объект recurring с идентификатором записи о серии списаний id, полученным в оповещении с данными о регистрации.

Таким образом, корректный запрос должен содержать идентификатор проекта, подпись и идентификатор записи о серии списаний.

Рис. 1. Пример набора данных в запросе на получение сведений о серии списаний
{  
  "general":{  
    "project_id":42,
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}

Сведения о серии списаний передаются от платёжной платформы к веб-сервису в ответе стандартного формата, описание которого представлено в разделе Формат ответа.

В данном случае ответ свидетельствует о том, что в рамках проекта 42 для пользователя customer_12 было выполнено списание в размере 4,00 USD с платёжной карты № 424242******4243 и ожидаются последующие списания.

Рис. 2. Пример сведений о серии списаний из ответа
{  
  "project_id": 42,
  "recurring":{ 
    "id": 1079,    // Идентификатор записи о серии списаний
    "type": "R",
    "period": "W",
    "period_interval": 3,
    "start_date": "2020-10-10",
    "start_time": "10:00:00",
    "amount": 400,
    "last_payment_at": "0000-00-00 00:00:00",
    "valid_thru": "2025-05-25 00:00:00",
    "status": "active",
    "currency": "USD"
  }
}

Изменение условий серии списаний

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

  1. Должен использоваться POST-запрос к конечной точке /v2/payment/card/recurring/update.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
    • Объект recurring с идентификатором записи о серии списаний id, полученным в оповещении с данными о регистрации.
  3. Дополнительно следует использовать параметры, задающие условия повторяемой оплаты. К таким параметрам относятся:
    • expiry_year — год окончания действия повторяемой оплаты;
    • expiry_month — месяц окончания действия повторяемой оплаты;
    • expiry_day — день окончания действия повторяемой оплаты;
    • interval — множитель для кратного увеличения периода списаний, например чтобы списания выполнялись раз в три недели, в параметре period надо задать значение W, а в параметре interval значение 3; возможные значения: от 1 до 100;
    • amount — сумма последующих списаний;
    • period — периодичность списаний (D — ежедневно, W — еженедельно, M — ежемесячно, Q — ежеквартально, Y — ежегодно);
    • time — время последующих списаний;
    • scheduled_payment_id — идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполнялась регистрация повторяемой оплаты, и быть уникальным в рамках проекта;
    • start_date — дата первого списания.

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

Рис. 3. Пример набора данных в запросе на изменение условий проведения оплаты
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079,
    "interval":3,
    "period":"M",
    "time":"12:00:00"
  }
}

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

В данном случае оповещение свидетельствует о том, что условия повторяемой оплаты изменены на следующие: периодичность списаний — каждые три месяца, время выполнения последующих списаний — 12:00:00.

Рис. 4. Пример данных из оповещения об изменении условий оплаты
{  
  "project_id":123,
  "recurring":{
    "id":1079,               // Идентификатор записи о серии списаний
    "currency":"USD",
    "status":"active",       // Статус записи о серии списаний
    "type":"R",
    "expiry_month":"5",     // Месяц окончания действия повторяемой оплаты
    "expiry_year":"2025",    // Год окончания действия повторяемой оплаты
    "period":"M",            // Периодичность списаний
    "period_interval":3,
    "time":"12:00:00"        // Время выполнения последующих списаний
  },
  "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...=="
}

Отмена дальнейшего выполнения списаний

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

  1. Должен использоваться POST-запрос к конечной точке /v2/payment/card/recurring/cancel.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
    • Объект recurring с идентификатором записи о серии списаний id, полученным в оповещении с данными о регистрации.

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и идентификатор серии списаний.

Рис. 5. Пример набора данных в запросе на отмену проведения оплаты
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"VftZ1ZZ5D/aMdeR+CqilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}

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

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

Рис. 6. Пример данных из оповещения об отмене проведения оплаты
{  
  "project_id":42,
  "recurring":{  
    "id":1079,            // Идентификатор серии списаний
    "currency":"USD",
    "status":"canceled",  // Статус, свидетельствующий об отмене повторяемой оплаты
    "type":"R",
    "expiry_month":"5",
    "expiry_year":"2025",
    "period":"M",
    "period_interval":3,
    "time":"12:00:00"
  },
  "signature":"MpfogAxwRItZ1Z/AeMde+GrNYyUwSm...=="
}