.. meta:: :description: /api/v4/create-recurring-payments API endpoint SBC: создаёт пакет запланированных рекуррентных платежей одним вызовом API. .. _api_v4_create-recurring-payments: /api/v4/create-recurring-payments ######################################### .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | Если запрос принят без ошибок, платежный шлюз создает отдельные профили повторяющихся платежей для каждой записи, предоставленной в запросе, и назначает каждому из них новый recurring-payment-id. Повторяющиеся транзакции будут обрабатываться в соответствии с созданными профилями повторяющихся платежей с использованием платежных данных, сохраненных в каждом профиле. | Создание группы повторяющихся платежей, инициируется через запрос :code:`HTTPS POST` с использованием :ref:`URLs` и :ref:`параметров`, указанных ниже. Используйте :ref:`RSA-SHA256` для аутентификации. .. _api_v4_create-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/create-recurring-payments/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/create-recurring-payments/ENDPOINTID` .. _api_v4_create-recurring-payments_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. | Ниже приведено описание каждого параметра, который можно включить в CSV и добавить к параметру :code:`payload`, который будет использоваться в запросе. | Подробную информацию о профиле повторяющихся платежей можно просмотреть только через пользовательский интерфейс. .. note:: | Если рекуррентный платёж перешёл в состояние остановки, его расписание можно обновить с помощью параметров :ex:`start-date` и :ex:`finish-date`. Однако возобновить его можно только через UI, нажав :code:`Возобновить`. | Введите :code:`native` в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере. | Чтобы создать профиль повторяющегося платежа с автоматическим повторяющимся графиком, отправьте параметры :code:`interval` и :code:`period`. Чтобы создать профиль повторяющегося платежа без автоматического повторяющегося графика, не отправляйте параметры :code:`interval` и :code:`period`. Чтобы остановить автоматический повторяющийся график, используйте :ref:`/api/v4/update-recurring-payments `. Доступно только для SRC. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - Название параметра CSV - Описание - Значение * - :code:`rp_card_type` - SRC — Исходная карта отправителя. DST — Карта назначения получателя. - | ``Необходимость``: Обязательно | ``Тип``: Enum | ``Длина``: 3 * - :code:`client-orderid` - Идентификатор заказа Присоединяющейся стороны. Поддерживается для типов SRC и DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`credit-card-number` - Номер кредитной карты плательщика. Поддерживается для типа SRC и DST. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 19 * - :code:`cvv2` - Код CVV2 плательщика. CVV2 (Card Verification Значение) — это трех - или четырехзначное число, напечатанное на обратной стороне карты в области подписи. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 3-4 * - :code:`card-printed-name` - Напечатанное имя плательщика на карте. Обязательно для SRC, необязательно для DST. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`expire-year` - Срок истечения года карты плательщика. Обязательно для SRC, необязательно для DST. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 4 * - :code:`expire-month` - Срок истечения месяца карты плательщика. Обязательно для SRC, необязательно для DST. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 2 * - :code:`amount` - Сумма валюты должна совпадать с валютой назначенного проекта. По достижении даты окончания, регулярный платеж перейдет в статус - остановлен. Поддерживается для типов SRC и DST. Требуется, если не используются:code:`amount-from` и:code:`amount-to` или:code:`amount-sequence`. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`currency` - Тип валюты. Поддерживается для типа SRC и DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 3 * - :code:`country` - Страна плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2 * - :code:`city` - Город плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`zip-code` - Почтовый индекс плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 10 * - :code:`address1` - Адрес плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 256 * - :code:`first-name` - Имя плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`last-name` - Фамилия плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`email` - Электронная почта плательщика. Не поддерживается для DST. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :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:`order_desc` - Описание периодического платежа. Поддерживается для типа SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 65K * - :code:`customer-ip` - IP-адрес плательщика. Поддерживается для типа SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 45 * - :code:`ssn` - Поле номера социального страхования. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 32 * - :code:`birthday` - Дата рождения плательщика. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`phone` - Номер телефона плательщика. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`state` - Штат плательщика. Пожалуйста, см. :ref:`Обязательные коды штатов` для списка допустимых кодов штатов. Требуется для США, Канады и Австралии. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2-3 * - :code:`start-date` - Дата, когда запланировано первое списание. Если дата начала установлена как текущая дата и тип установлен как авто, первое списание будет произведено в этот же день. Поддерживается для типов SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`finish-date` - Дата, когда с плательщика будет взиматься плата в последний раз. Поддерживается для типов SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Длина``: 8 * - :code:`max-repeats-number` - Индекс повторяющейся транзакции, первый платеж будет иметь индекс 0. Текущее число повторов увеличивается, даже если платеж был неудачным. Когда текущее число повторов достигает максимального числа повторов, повторяющийся платеж переходит в статус остановки, и клиент больше не платит. Если платеж был произведен автоматически, никаких дополнительных платежей взиматься не будет (если это не сделано вручную), даже если повторяющийся платеж остановлен и перенесен снова. Поддерживается для типов SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: Int | ``Длина``: - * - :code:`purpose` - Цель транзакции. Не поддерживается для DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`notify_url` - Поле Notify url. Также можно использовать параметр :code:`server_callback_url`. Для получения дополнительной информации см. :ref:`Обратный вызов Присоединяющейся Стороны`. Поддерживается для типов SRC и DST. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`server_callback_url` - URL-адрес Присоединяющейся Стороны, который получит запрос обратного вызова, как только транзакция достигнет окончательного статуса. Присоединяющаяся сторона может использовать URL-адрес обратного вызова сервера для индивидуальной обработки завершения транзакции, например, для сбора данных о платежах в информационной системе Присоединяющейся Стороны. Подробности обратного вызова см. в:ref:`Параметры обратного вызова Присоединяющейся Стороны`. Отправьте либо:ex:`notify_url`, либо:ex:`server_callback_url`, но не оба. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 .. _api_v4_create-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:`create-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:`recurring-payment-id` - Повторяющийся идентификатор, присвоенный заказу SBC. * - :code:`status` - Подробности см. в :ref:`status_list`. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны. Пример запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | **Шаг 1.** Создайте CSV-файл с предоставленной структурой: .. code-block:: none "client-orderid";"rp_card_type";"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 create-recurring-payments-example.csv | **Шаг 3**. Присвойте закодированное значение :ex:`base64` параметру :code:`payload` и отправьте запрос: .. code-block:: http POST /paynet/api/v4/create-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="1727178538",oauth_nonce="cdtNANOCATq",oauth_version="1.0",oauth_signature="B5m%2FOQOSBgqWI%2F%2FG3GhZw2kCJZDda7J6fLpOu6wFyBEj60PJp5u1mqBnIufzkkmrSkyZkCT6v12WIhwE%2BWTtJ7Wg%2BRx9cqXPfhk5JhQpnofsVheXpCpftoLvvBTqn8p67WaS%2B6kfzGtGhdXHYVBzIxXDxabnMjMC8u8EtfWsovzTp%2BAYfZKn2H0qH7B62dfUW4PuRCTmy9svbwLhbPULkh3oJ3a1M%2BnRqXIasIrd3WY1MD9lkqUetAtW3xIWnOoMvPZ0wzk2UEbU%2BoZ2KTiA9KO09%2Ffq7OylRhiDpqtz65EMBiKujFFSF42bzYsB1SmPssk09xJoWmsNR9tFZsdx2Hgl7yFZTXhxV3nlSZTGDVZaVe2pPSi8va5W9yTlPMPU5HcNE5MuZ3T9PSEURQvM691UcPSdlJAi8q7B0EhXDzwOlgLV7DsFDtpsXSeXopFpG6uHiNPIjW65p6XFQ31xr4foZCahVeymuIoiXE6uAkHJJ89oHqKsOBnI7xILu2UpflHnl7gn%2BvX9IWdUHx1xEMdBPWdUQRFNllGvT2N8nYrtZe96L%2BfwxarYR2Fh1LtyqwCtEXhQm5jhjpR3NQpqddY3NSd75NUP7zlDQwXCknMQps6uSdng9Uv%2B7IFx3oNUfjVMxp4CGcmEtSxH7Ykx8dX5srNOKLDJT5tyExLLjXk%3D" Content-Length: 754 Connection: keep-alive payload=Y2xpZW50LW9yZGVyaWQ7cnBfY2FyZF90eXBlO29yZGVyX2Rlc2M7Zmlyc3QtbmFtZTtsYXN0LW5hbWU7YWRkcmVzczE7Y2l0eTt6aXAtY29kZTtjb3VudHJ5O3N0YXRlO3Bob25lO2VtYWlsO3BlcmlvZDtpbnRlcnZhbDtzdGFydC1kYXRlO2ZpbmlzaC1kYXRlO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTIzNDU2Nzg5MDtTUkM7O1dpbGw7U3RpbGw7MTIzNCBSZWluO1JlaW1zOzEyMzQ1NjtGUjtCUkU7MTIzNDU2Nzg7d2lsbHN0aWxsQGV4YW1wbGUuY29tO3dlZWs7MTsxNi4wOS4yMDI0OzE3LjA5LjIwMjQ7MTAwMDsxMDs7OztVU0Q7V0lMTCBTVElMTDs0NDU4MjA0NjgxMzg3MDUzOzEyOzIwNDA7MTIzO05vIHB1cnBvc2UgYXQgYWxsO2h0dHA6Ly9leGFtcGxlLmNvbS9jcmVhdGUtbWU7MTIzNDsyMi4wMS4xOTgwDQo%3D Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Успешный ответ имеет пустое тело и HTTP-код 200. .. code-block:: http HTTP/1.1 200 Server: server Date: Tue, 24 Sep 2024 09:44:01 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 Strict-Transport-Security: max-age=31536000 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Неуспешный ответ имеет пустое тело и HTTP-код 403. .. code-block:: http HTTP/1.1 403 Server: server Date: Wed, 25 Sep 2024 08:45:42 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/V4RecursCreate.html