.. meta:: :description: /api/v4/update-recurring-payments API endpoint SBC: обновляет несколько существующих конфигураций рекуррентных платежей одним пакетным вызовом. .. _api_v4_update-recurring-payments: /api/v4/update-recurring-payments ############################################ .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ | Если запрос принят без ошибок, платежный шлюз находит профиль повторяющегося платежа для каждого предоставленного recurring-payment-id и обновляет эти профили. Повторяющиеся транзакции будут обработаны в соответствии с обновленными профилями повторяющихся платежей с использованием платежных данных, сохраненных в каждом профиле. | Обновление повторяющегося платежа Multiple инициируется через запрос :code:`HTTPS POST` с использованием :ref:`URL` и :ref:`parameters`, указанных ниже. Используйте :ref:`RSA-SHA256` для аутентификации. .. _api_v4_update-recurring-payments_request_url: API URL ^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.sbctech.ru/paynet/api/v4/update-recurring-payments/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/update-recurring-payments/ENDPOINTID` .. _api_v4_update-recurring-payments_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. | Ниже приведено описание каждого параметра, который можно включить в CSV и добавить к параметру :code:`payload`, который будет использоваться в запросе. | Любые изменения в профиле повторяющихся платежей, внесенные с помощью команды :code:`Update`, можно просмотреть только через пользовательский интерфейс. .. note:: | Экран сведений о RPI (профиль повторяющегося платежа) содержит информацию о связанных данных держателя карты и клиента, повторяющемся графике и обработанных транзакциях с этим RPI. Этот экран также содержит историю изменений для этого RPI. История изменений в настоящее время доступна только для исходных карт (SRC). | Введите :code:`native` в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере. | Если рекуррентный платёж перешёл в состояние остановки, его расписание можно обновить с помощью параметров :ex:`start-date` и :ex:`finish-date`. Однако возобновить его можно только через UI, нажав :code:`Возобновить`. | Чтобы остановить автоматическое повторяющееся расписание, используйте параметр :ex:`finish-date` с прошлой датой в разделе :ref:`Параметры запроса`. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - Название параметра CSV - Описание - Значение * - :code:`client-orderid` - Идентификатор заказа Присоединяющейся стороны. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`recurring-payment-id` - Повторяющийся идентификатор, присвоенный заказу отделом QA. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`credit-card-number` - Номер кредитной карты плательщика. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 19 * - :code:`card-printed-name` - Напечатанное имя плательщика на карте. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`expire-year` - Срок истечения года карты плательщика. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 4 * - :code:`expire-month` - Срок истечения месяца карты плательщика. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 2 * - :code:`amount` - Сумма валюты должна совпадать с валютой назначенного проекта. По достижении даты окончания, регулярный платеж перейдет в статус - остановлен. Поддерживается для типов SRC и DST. Требуется, если не используются:code:`amount-from` и:code:`amount-to` или:code:`amount-sequence`. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`amount-from` - Если выбрана комбинация :code:`amount-from` и :code:`amount-to`, каждая плата будет иметь случайную сумму между этими двумя числами. Поддерживается для типов SRC и DST. Требуется, если :code:`amount` или :code:`amount-sequence` не используются. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`amount-to` - Если выбрана комбинация :code:`amount-from` и :code:`amount-to`, каждая плата будет иметь случайную сумму между этими двумя числами. Поддерживается для типов SRC и DST. Требуется, если :code:`amount` или :code:`amount-sequence` не используются. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`amount-sequence` - Если выбрана последовательность сумм, с клиента будет списана сумма из этого списка. Пример настройки последовательности сумм::ex:`10.5`,:ex:`24.6`,:ex:`32.0`. Если количество повторов больше количества элементов в последовательности сумм, каждое новое списание будет с последней суммы в последовательности сумм. Для того чтобы списание начиналось с первой суммы в цепочке, текущее количество повторов должно быть установлено как 0. Поддерживается для типов SRC и DST. Требуется, если:code:`amount-from` и:code:`amount-to` или:code:`amount` не используются. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`period` - Возможные значения: :ex:`ежедневно`, :ex:`еженедельно` и :ex:`ежемесячно`. В случае, если выбрано ежедневно, клиент будет платить каждый день. Если выбрано еженедельно - каждые 7 дней. Если выбрано ежемесячно, клиент будет платить в тот же день месяца, с начальной даты, независимо от того, сколько дней в месяце. :code:`Interval` и :code:`period` можно указывать или опускать только вместе. Не поддерживается для DST. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :code:`interval` - Interval — это множитель, применяемый к периоду. Например, если интервал равен 2, а период выбран как «Ежедневно», клиент будет платить раз в 2 дня. :code:`Interval` и :code:`period` можно указывать или опускать только вместе. Не поддерживается для DST. - | ``Необходимость``: Условно | ``Тип``: Int | ``Длина``: - * - :code:`country` - Страна плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`city` - Город плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`address1` - Адрес плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 256 * - :code:`first-name` - Имя плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`last-name` - Фамилия плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`customer-ip` - IP-адрес плательщика. Поддерживается для типа SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 45 * - :code:`order_desc` - Описание повторяющегося платежа. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 65K * - :code:`zip-code` - Почтовый индекс плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 10 * - :code:`birthday` - Дата рождения плательщика. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`email` - Электронная почта плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`ssn` - Поле номера социального страхования. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 32 * - :code:`phone` - Полный международный номер телефона плательщика, включая код страны. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`state` - Штат плательщика. Список допустимых кодов штатов см. в разделе :ref:`Обязательные коды штатов`. Требуется для США, Канады и Австралии. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2-3 * - :code:`start-date` - Дата, когда запланировано первое списание. Если дата начала установлена как текущая дата и тип установлен как авто, первое списание будет произведено сегодня. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`finish-date` - Дата, когда с Плательщика будет взиматься плата в последний раз. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`max-repeats-number` - Индекс повторяющейся транзакции, первый платеж будет иметь индекс 0. Текущее число повторов увеличивается, даже если платеж был неудачным. Когда текущее число повторов достигает максимального числа повторов, повторяющийся платеж переходит в статус остановки, и клиент больше не платит. Если платеж был произведен автоматически, никаких дополнительных платежей не будет (если это не сделано вручную), даже если повторяющийся платеж остановлен и перенесен снова. - | ``Необходимость``: Опционально | ``Тип``: Int | ``Длина``: - * - :code:`purpose` - Цель транзакции. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`notify_url` - Поле Notify url. Также можно использовать параметр :code:`server_callback_url`. Для получения дополнительной информации см. :ref:`Обратный вызов Присоединяющейся Стороны`. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`server_callback_url` - URL-адрес Присоединяющейся Стороны, который получит запрос обратного вызова, как только транзакция достигнет окончательного статуса. Присоединяющаяся сторона может использовать URL-адрес обратного вызова сервера для индивидуальной обработки завершения транзакции, например, для сбора данных о платежах в информационной системе Присоединяющейся Стороны. Подробности обратного вызова см. в:ref:`Параметры обратного вызова Присоединяющейся Стороны`. Отправьте либо:ex:`notify_url`, либо:ex:`server_callback_url`, но не оба. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 .. _api_v4_update-recurring-payments_response_parameters: Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра. .. list-table:: :widths: 35, 65 :header-rows: 1 :class: longtable * - Параметры ответа - Описание * - :code:`type` - Тип ответа. Пример: :ex:`update-recurring-payment-response`, :ex:`validation-error`, :ex:`error`. Если тип равен :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` содержат сведения об ошибке. Могут быть получены несколько кодов ошибок: :ex:`200`, :ex:`403` и :ex:`500`. Для кода ошибки :ex:`500` будет возвращен дополнительный идентификатор ошибки. * - :code:`status` - Подробности смотрите в:ref:`status_list`. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Торговца Пример запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | **Шаг 1.** Создайте CSV-файл с предоставленной структурой: .. code-block:: none "client-orderid";"recurring-payment-id";"payment-description";"first-name";"last-name";"address1";"city";"zip-code"; "country";"state";"phone";"email";"customer-ip";"period";"interval";"start-date";"finish-date";"max-repeats-number";"amount"; "amount-from";"amount-to";"amount-sequence";"currency";"card-printed-name";"credit-card-number";"expire-month";"expire-year" | **Шаг 2.** Кодируйте CSV в base64 с помощью следующей команды: .. code-block:: bash base64 update-recurring-payments-example.csv | **Шаг 3**. Присвойте закодированное значение :ex:`base64` параметру :code:`payload` и отправьте запрос: .. code-block:: http POST /paynet/api/v4/update-recurring-payments/ HTTP/1.1 Host: sandbox.sbctech.ru User-Agent: curl/8.4.0 Accept: */* Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727177782",oauth_nonce="Js4dwXkF8eI",oauth_version="1.0",oauth_signature="VwdA7BQ68v%2BmpB0N%2BUOxK%2BxYk355i1QzeUPGGGFwDEBn7Y8v1xpSolGQ45HehGmJHNjXHc7A1mP3x7V7r2pQju1LpDEvAb2MHNLSCHiCEjI95sCtrotE%2Fs5%2FmQmIJ8te%2FGFCR1uK%2BzMPG8bpHqn%2B5EIEsuLPq6TSOjD0N3RvnV%2BHdmjH5cxTcmtRrcY0u6VIpvkBUlqpKuTVJXLvbpxRexvgPMDow78QS3DLRQhi6G7Y%2FVshKpKC%2FSRThhe8L33tFckX6KaEbJ3XIMEmP7O%2F%2FQdLfWQBn4ldSp8K8lpkgZks4CZbAjDY%2BQpSfwdc1s8kJf17Ymk1R69aGBmjzJrw00tV4dzY4DE6XVqSTUR8X%2FCa0XMrtD46ichsFoRvFtIeyV%2FIud%2F%2FLSb8XDqk%2BaftSLazBokmT8Qe1FMf0UMgUYBLCl0B4O66Ys8kH4Z6guC2MXarwu%2BDlfuelrcAHevS68hewrMb%2FjppSJWAbQiBOABeW6s1Rb4dvbJnZribkKhEwrxmnT5drsTYvukC2UCoUblEOgVkFHdHk5E3OqT4wMxqXojlYr5Il7m1GkHVYELb964ukROLkohGoTjYEKj%2FUHirjybDWeynTCSaGe%2Bv3JtEbkydWXannkdtTvk0xkbT6LurBiNWy1FuSTmKod9ibqyNiEv6j%2Be14BBGXs3xc5A%3D" Content-Length: 888 Connection: keep-alive payload=cmVjdXJyaW5nLXBheW1lbnQtaWQ7dHlwZTtjbGllbnQtb3JkZXJpZDtwYXltZW50LWRlc2NyaXB0aW9uO2ZpcnN0LW5hbWU7bGFzdC1uYW1lO2FkZHJlc3MxO2NpdHk7emlwLWNvZGU7Y291bnRyeTtzdGF0ZTtwaG9uZTtlbWFpbDtjdXN0b21lci1pcDtwZXJpb2Q7aW50ZXJ2YWw7c3RhcnQtZGF0ZTtmaW5pc2gtZGF0ZTtjdXJyZW50LXJlcGVhdHMtbnVtYmVyO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTQ5MjI4NjttYW51YWw7MTIzNDU2Nzg5MDtPdXIgc3VwZXIgZ29vZHM7Sm9objtTbWl0aDsxMjM0IFBlYWNlIHN0cmVldDtDaGljYWdvOzEyMzQ1NjtVUztJTDsxMjM0NTY3ODtqb2huLnNtaXRoQGV4YW1wbGUuY29tOzEuMi4zLjQ7d2VlazsxOzAxLjAxLjIwMzA7MDEuMDEuMjA0MDswOzEwMDA7MTA7Ozs7VVNEO0pPSE4gU01JVEg7NDUzODA5NjQxNTA4NDc1NjsxMjsyMDIwOzEyMztObyBwdXJwb3NlIGF0IGFsbDtodHRwOi8vZXhhbXBsZS5jb20vbm90aWZ5LW1lOzEyMzQ7MDIuMDEuMTk4MA0K Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Успешный ответ имеет пустое тело и HTTP-код 200. .. code-block:: http HTTP/1.1 200 Server: server Date: Tue, 24 Sep 2024 11:40:45 GMT Content-Length: 0 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Неуспешный ответ имеет пустое тело и HTTP-код 403. .. code-block:: http HTTP/1.1 403 Server: server Date: Wed, 25 Sep 2024 08:47:54 GMT Content-Length: 0 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Конструктор запросов ^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/V4RecursUpdate.html