.. meta:: :description: /api/v4/create-recurring-payment API endpoint SBC: создаёт один запланированный рекуррентный платёж с настройкой интервала и суммы. .. _api_v4_create-recurring-payment: /api/v4/create-recurring-payment ################################# .. role:: ex .. role:: code Введение ^^^^^^^^^^^^ | /api/v4/create-recurring-payment — это синхронная команда API. Если запрос принят без ошибок, платежный шлюз создает профиль повторяющегося платежа и назначает ему новый recurring-payment-id. Повторяющиеся транзакции будут обрабатываться в соответствии с созданным профилем повторяющегося платежа с использованием платежных данных, сохраненных в этом профиле. | Создание повторяющегося платежа инициируется через запрос :code:`HTTPS POST` с использованием :ref:`URL` и :ref:`parameters`, указанных ниже. Используйте :ref:`RSA-SHA256` для аутентификации. .. _api_v4_create-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/create-recurring-payment/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/create-recurring-payment/ENDPOINTID` .. _api_v4_create-recurring-payment_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. .. note:: | Если рекуррентный платёж перешёл в состояние остановки, его расписание можно обновить с помощью параметров :ex:`start-date` и :ex:`finish-date`. Однако возобновить его можно только через UI, нажав :code:`Возобновить`. | Введите :code:`native` в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере. | Чтобы создать профиль повторяющегося платежа с автоматическим повторяющимся графиком, отправьте параметры :code:`interval` и :code:`period`. Чтобы создать профиль повторяющегося платежа без автоматического повторяющегося графика, не отправляйте параметры :code:`interval` и :code:`period`. Чтобы остановить автоматический повторяющийся график, используйте :ref:`/api/v4/update-recurring-payment`. Доступно только для SRC. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :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-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:`create-recurring-payment-response`, :ex:`validation-error`, :ex:`error`. Если тип равен :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` содержат сведения об ошибке. * - :code:`recurring-payment-id` - Повторяющийся идентификатор, присвоенный заказу SBC. * - :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/create-recurring-payment/ HTTP/1.1 User-Agent: curl/8.4.0 Accept: */* Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="qdyD66xc8sDEQwo3r12VjJfJhAOXuj6O", oauth_signature="eZve%2FSvPCTBXtQM%2BEwTEROtsQE27gZJr36EThL8ECCrnWH9Xw8JxcysNEPTG5HfcYwR2IOjDk3uiSNFa1oT2bQT9XONQTl1JVTOhIiMrMJT7GT1rGuLSsEvghaBoRLrcth6SC0c%2F%2FINyOxmIc%2B79E3T8hkpH6J6VI%2BSRG162%2BlHBPc1u1SGGnhkkRYU621AUGu2FDrc4neob4QJSm%2BaF3a0AgWDGiLbeQ0Ivn3YJ441EKd99kBWdaCuUp0eSfcmh3U2Js66edCjWXDEW7uuywP%2BU%2FBEeq06XxoVNGE2NF2LArXgoNqfzz2Tpisq35%2FE7Yg%2F9hphww75HMoJCECe0yVIHmKXd8HBDNMyT7gg3w5bnKbo%2FURX0m%2Fpe7bxkJ1mLNsKouHVkvjLZKpWVVUyCl%2BJ3x0BoEN5QK7xh0fNbV4Ue9TUOz59q0v%2B7lz5E1B4TvxQ9pa%2FmNCl4P2JgTosLvXNcdGn9Dq0TC0gb62O2W81MoZAljJQew%2FcKAUFTXBMZK6eIXzA81BPQVejv8nIVsvHKNo2Ko0s3hJPKGaeVAN0gyUAPw0%2BsJI3bnN2CPSW92xysGRWJYBtsHhqDhmgtoDNvw7LFB6BzRk5GPa9iQju34l47GsCUUIs3%2ByipIl7Q3HnM%2Bet9L8JSl7K02MwR6zlLxtd9UXHDq3pnmKzly6I%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721312072", oauth_version="1.0" Content-Length: 595 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 &city=Chicago &client-orderid=1575634981130 &country=US &credit-card-number=4464920026265488 ¤cy=USD &customer-ip=1.2.3.4 &cvv2=123 &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 &rp_card_type=SRC &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:16:20 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: 137 type=create-recurring-payment-response &serial-number=00000000-0000-0000-0000-000002f36d81 &recurring-payment-id=1492124 &status=approved Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 500 Server: server Date: Thu, 18 Jul 2024 14:24:28 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 [8485772c-21d6-42aa-b2eb-3b5ae4e07d19] .. only:: openapi_doc_enabled Open API Collection ^^^^^^^^^^^^^^^^^^^ Open this method in the OpenAPI Reference .. raw:: html View in OpenAPI Конструктор запросов ^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/V4RecurCreate.html