.. meta:: :description: /api/v4/update-recurring-payment API endpoint SBC: обновляет интервал, сумму или статус существующей конфигурации рекуррентного платежа. .. _api_v4_update-recurring-payment: /api/v4/update-recurring-payment ###################################### .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^ | /api/v4/update-recurring-payment — это синхронная команда API. Если запрос принят без ошибок, платежный шлюз находит профиль повторяющегося платежа по предоставленному recurring-payment-id и обновляет этот профиль. Повторяющиеся транзакции будут обработаны в соответствии с обновленным профилем повторяющегося платежа с использованием платежных данных, сохраненных в этом профиле. | Обновление повторяющегося платежа инициируется через :code:`HTTPS POST`запрос с использованием :ref:`URL` и :ref:`параметров`, указанных ниже. Используйте :ref:`RSA-SHA256` для аутентификации. .. _api_v4_update-recurring-payment_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-payment/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/update-recurring-payment/ENDPOINTID` .. _api_v4_update-recurring-payment_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. .. note:: | Экран сведений о RPI (профиль повторяющегося платежа) содержит информацию о связанных данных держателя карты и клиента, повторяющемся графике и обработанных транзакциях с этим RPI. Этот экран также содержит историю изменений для этого RPI. История изменений в настоящее время доступна только для исходных карт (SRC). | Введите :code:`native` в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере. | Если рекуррентный платёж перешёл в состояние остановки, его расписание можно обновить с помощью параметров :ex:`start-date` и :ex:`finish-date`. Однако возобновить его можно только через UI, нажав :code:`Возобновить`. | Чтобы остановить автоматическое повторяющееся расписание, используйте :ref:`Параметры запроса `. Доступно только для SRC. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`client-orderid` - Идентификатор заказа Присоединяющейся стороны. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`recurring-payment-id` - Повторяющийся идентификатор, присвоенный заказу отделом QA. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`credit-card-number` - Номер кредитной карты плательщика. :code:`card-printed-name` можно указать только если указан номер карты. - | ``Необходимость``: Условно | ``Тип``: 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:`customer-ip` - IP-адрес плательщика. Поддерживается для типа SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 45 * - :code:`country` - Страна плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`city` - Город плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`address1` - Адрес плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 256 * - :code:`first-name` - Имя плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`last-name` - Фамилия плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :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-payment_response_parameters: Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра. .. warning:: /api/v4/create-recurring-payment — это синхронная команда API. Ответ будет возвращен после того, как профиль повторяющегося платежа будет создан на стороне платежного шлюза. .. 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` содержат сведения об ошибке. * - :code:`status` - Если запрос принят, этот параметр имеет значение :code:`approved`. Это не статус транзакции. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны. * - :code:`error-message` - Для транзакций в статусе :ex:`declined` или :ex:`error`, этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`declined` или :ex:`error`. Пример запроса ^^^^^^^^^^^^^^^^^^^^ .. code-block:: http POST /paynet/api/v4/update-recurring-payment/ HTTP/1.1 User-Agent: curl/8.4.0 Accept: */* Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="XBhUVJU4N8fBnNRGfY91Z3wuZ6iNgjVM", oauth_signature="RIRufAZeoBZBMpVlr7Bt%2Bc6fDTUxZJgxjJUlTo7Pm9zlGeZAl427VF6c%2B0lkGvZfATlooYBK%2FeoZaUU5gJITePycMmZr2gPzAk8xCielclB8N0j5Rp3ga0A%2B3uJDTgQdvsrosYK4tsES%2BPsR6qjhf%2FqWGHbpwCooXbMLwI9a9yMdkwmcRNQGPWAz7I%2FJ8gdDLvkjM0H8fZRp%2Bz%2FSAd3%2FgX%2F%2BCJv7bMn26hOGUxJua7u5GIKX6mmZ5FpV71xdy04ebPu4qAXGPGNKBZXLJGqzYfYVlW9XWKKkFhUA4RLYUZqnfokHA8uy3zb8IY8tKZOjXxmytlFKdVr%2BYAiHxlMt%2BEq%2BlovLAXWENbIXvJYhRiX%2F3QO2cq2ZznAsanZQiyU7AT3O9lnLHuvKc2wbuFKr277lNR24cykI3ja%2FGMR%2F8T%2BXjZKFF%2F1sYVRGd93CQDx6NHnH98vp%2Bv3PMopOmLWwggyOApmDBDsa8jYoU1TDOs6gNRTsXIyFiSwl3e48fNAp%2FjFZfUl90K8wGusNzrof05UdTPR%2B7zpv4jL1hd1XyN%2F4x7aNNQ28tm5LSoVU6t%2BQkvwRm%2FNxnDKMYEE9rq7s4Uq5KTzAmM89pAu52WFbDQXYoZgy3vm%2B0SsJDXH0IVXsDpLDt1zcJClWoeXxT0fqOcEojJhuosvbcI%2FIaEpxWH8%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721312815", oauth_version="1.0" Content-Length: 624 Content-Type: application/x-www-form-urlencoded Connection: keep-alive address1=1234%20Peace%20street &amount=55 &birthday=1980-01-02 &card-printed-name=JOHN%20SMITH &recurring-payment-id=1492124 &city=Chicago &client-orderid=1575634981130 &country=US &credit-card-number=4464920026265488 ¤cy=USD &customer-ip=1.2.3.4 &email=john.smith%40example.com &expire-month=12 &expire-year=2040 &finish-date=2040-01-01 &first-name=John &interval=1 &last-name=Smith &max-repeats-number=1000 ¬ify-url=http%3A%2F%2Fexample.com%2Fnotify-me &order_desc=testing%20purposes &period=week &phone=12345678 &purpose=No%20purpose%20at%20all &ssn=1234 &start-date=2030-01-01 &state=IL &zip-code=123456 &server_callback_url=https://httpstat.us/200 Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 200 Server: server Date: Thu, 18 Jul 2024 14:27:39 GMT Content-Type: text/html;charset=utf-8 Connection: keep-alive Keep-Alive: timeout=60 Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 107 type=update-recurring-payment-response &serial-number=00000000-0000-0000-0000-000002f36d82 &status=approved Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 500 Server: server Date: Thu, 18 Jul 2024 14:41:27 GMT Content-Length: 61 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Internal server error [00b20f25-2933-48e3-973b-0664114b8492] .. only:: openapi_doc_enabled Open API Collection ^^^^^^^^^^^^^^^^^^^ Open this method in the OpenAPI Reference .. raw:: html View in OpenAPI Конструктор запросов ^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/V4RecurUpdate.html