PaymentNut
Документация для разработчиков / Работа с API / Формирование подписки
Создание подписки через API по общему смыслу сходно с программным формированием обычного платежа.

URL для приема платежей/подписок в RUB (карты выпущенные банками РФ): ДОМЕН/api/payment-subscription/v2 (значение домена указано в ЛК > Настройки проекта > API)
Метод отправки: GET
Поддерживаемые параметры:

Наименование параметра Описание Допустимые символы Минимальное, максимальное кол–во знаков Допустимые значения Обязателен Пример
project_id Идентификатор проекта; указан в настройках Проекта [a-zA-Z0-9] 32, 32 Любые Да 0D2239F1BBDAA3E4F98CFD0CDF2F9D73
recurrent_interval Интервал между платежами 1 – день
2 – неделя
3 – месяц
Да 1
recurrent_period Период. В комбинации с интервалом, 1 'месяц' значит раз в месяц, а 2 'неделя' – раз в две недели. Должен быть больше 0 и целым числом. Сочетание значения периода и интервала не должно превышать одного года. [1-9] Больше нуля Да 1
recurrent_max_periods Количество регулярных платежей в подписке. 0 — без ограничений. Допускается только целое число. [0-9] 1,3 Любые Да 1
amount Сумма установочного платежа. Разделитель – точка (.). Обязательно всегда указывать два знака (копейки) после разделителя. [0-9.] 1,10 Минимальное – 1.15, максимальное – 1000000.00 Да 95.25
recurrent_amount Сумма каждого регулярного платежа Разделитель – точка (.). Обязательно всегда указывать два знака (копейки) после разделителя.

Сумма регулярного платежа может отличаться от суммы установочного платежа.
[0-9.] 1,10 Минимальное – 1.15, максимальное – 1000000.00 Да 780.00
currency_code Код валюты оплаты, допускается только Российский Рубль (RUB).

Прием платежей только с карт, выпущенных банками РФ.
RUB Да RUB
recurrent_start_date Дата и время (UTC) первого регулярного платежа (в Unix timestamp). Если значение не задано, то первый регулярный платеж произойдет спустя указанный интервал и период, например через месяц, после установочного платежа. Если указываете явную дату и время, то она должна быть как минимум на 12 часов позднее текущего времени и не старше одного года от текущего времени [0-9] Как минимум на 12 часов позднее текущего времени Нет 1696344453
manual_confirmation Необходимость заморозки средств на карте. В настоящее время недоступно для подписок; следует указывать значение 0. 0, 1 Да 0
description Назначение подписки. Отображается на странице оплаты, в карточке подписки/транзакции в ЛК, в уведомлениях, API и т.п. [a-zA-Z0-9-()*.,:;а-яА-Я ] 5, 300 Любые Да Оплата услуги А
language Код языка интерфейса страницы оплаты по–умолчанию, в настоящее время допускается только русский (ru-RU) ru-RU Да ru-RU
reference_1 Произвольные данные для отслеживания транзакции. Эти данные не отображаются на странице оплаты, но доступны для просмотра Вам в карточке транзакции в Личном Кабинете, при экспорте транзакций в CSV, при просмотре транзакции через API и в обратном вызове (вебхуке) [a-zA-Z0-9 ] 0, 32 Любые Нет Customer 1
reference_2 Дополнительные произвольные данные для отслеживания транзакции, как reference_1 [a-zA-Z0-9 ] 0, 32 Любые Нет Invoice 1
reference_3 Дополнительные произвольные данные для отслеживания транзакции, как reference_1 [a-zA-Z0-9 ] 0, 32 Любые Нет Account 1
reference_3_is_unique Запрет открытия страницы оплаты, если ранее уже проводилась успешная установочная транзакция (status=3/4) с таким же значением reference_3. Может использоваться при создании уникальной ссылки для подписки, для избежания повторных оплат по-ошибке.

Внимание! Данная опция не гарантирует то, что плательщик не сможет произвести повторную оплату с таким же значением reference_3. Пользователь может открыть две или более страницы оплаты во вкладках браузера, а затем произвести оплату в каждой открытой вкладке.
[1] 1, 1 1 (только если задано значение для reference_3) Нет 1
custom_data Произвольные данные для отслеживания транзакции, если reference_1/2/3 недостаточно. Эти данные не отображаются на странице оплаты, но доступны для просмотра Вам в карточке транзакции в Личном Кабинете, при экспорте транзакций в CSV, при просмотре транзакции через API и в обратном вызове (вебхуке).

В случае если допустимых символов (A-Za-z0-9+=/._) недостаточно для передачи данных, Вы можете зашифровать их значение по стандарту Base64 (допустимые символы обеспечивают поддержку Base64).
[A-Za-z0-9+=\/._] 0, 1000 Любые Нет e3N5c3RlbV9pZDogJzU4MycsIHBheW1lbnRfaWQ6ICdEMjk4NC0zJ30=
expiration Дата и время (UTC) истечения срока действия платежной ссылки, Unix timestamp.

Внимание! Данная опция не гарантирует то, что плательщик не сможет произвести оплату после заданной даты. Пользователь может открыть страницу оплаты до даты истечения и произвести оплату позднее.
[0-9] 10, 10 Любые Нет 1661904000
signature Значение подписи составляется на основе значений нескольких вышеуказанных параметров (см. ниже) [a-zA-Z0-9] 32, 32 Любые Да 3c2f2e4ddb0e77dbb1709d9de019bd59

Формирование значения подписи

Подпись (параметр signature) нужна для того, что бы третье лицо не могло сформировать или изменить страницу оплаты не зная API ключ Проекта. Значение API ключа доступно в настройках Проекта Личного Кабинета его владельцу. В подпись, кроме API ключа, входят значения и других параметров платежа; финальное значение подписи шифруется по алгоритму MD5.

Для формирования значения подписи для создания подписки, возьмите значения параметров следующим образом: Project_idAmountRecurrent_amountRecurrent_intervalRecurrent_periodRecurrent_max_periodsRecurrent_start_dateCurrency_codeManual_confirmationDescriptionReference_1Reference_2Reference_3Custom_dataExpirationApi_key в одну строку (без пробелов) и зашифруйте ее по алгоритму MD5.

Например (PHP):
$project_id='0D2239F1BBDAA3E4F98CFD0CDF2F9D73';
$recurrent_interval='1';
$recurrent_period='1';
$recurrent_max_periods='0';
$amount='95.25';
$recurrent_amount='780.00';
$currency_code='RUB';
$recurrent_start_date=''; //не задаем явное значение, для примера
$manual_confirmation='0';
$description='Оплата услуги А';
$reference_1='Customer 1';
$reference_2='Invoice 1';
$reference_3='Account 1';
$reference_3_is_unique='';  //не задаем явное значение, для примера
$custom_data='{system_id: \'583\', payment_id: \'D2984-3\'}';
$custom_data=base64_encode($custom_data);
$expiration='';  //не задаем явное значение, для примера
$api_key='1EA457132ABC39FBBA99A0EEFE0BF13D';

$signature=md5("$project_id$amount$recurrent_amount$recurrent_interval$recurrent_period$recurrent_max_periods$recurrent_start_date$currency_code$manual_confirmation$description$reference_1$reference_2$reference_3$reference_3_is_unique$custom_data$expiration$api_key");

//значение подписи 7dbf7777db3577cfc8689983f0114cdb




Пример сформированной ссылки для перехода к странице оплаты PaymentNut

Данный пример служит для иллюстрации корректного синтаксиса запроса.

ДОМЕН/api/payment-subscription/v2/project_id=0D2239F1BBDAA3E4F98CFD0CDF2F9D73&recurrent_interval=1&recurrent_period=1&recurrent_max_periods=0&amount=95.25&recurrent_amount=780.00&currency_code=RUB&recurrent_start_date=&manual_confirmation=0&description=Оплата услуги А&language=ru-RU&reference_1=Customer 1&reference_2=Invoice 1&reference_3=Account 1&reference_3_is_unique=&custom_data=e3N5c3RlbV9pZDogJzU4MycsIHBheW1lbnRfaWQ6ICdEMjk4NC0zJ30=&expiration=&signature=7dbf7777db3577cfc8689983f0114cdb

Пример формирования ссылки для оплаты и перенаправления на страницу оплаты (PHP):
$project_id='0D2239F1BBDAA3E4F98CFD0CDF2F9D73';
$recurrent_interval='1';
$recurrent_period='1';
$recurrent_max_periods='0';
$amount='95.25';
$recurrent_amount='780.00';
$currency_code='RUB';
$recurrent_start_date=''; //не задаем явное значение, для примера
$manual_confirmation='0';
$description='Оплата услуги А';
$reference_1='Customer 1';
$reference_2='Invoice 1';
$reference_3='Account 1';
$reference_3_is_unique='';  //не задаем явное значение, для примера
$custom_data='{system_id: \'583\', payment_id: \'D2984-3\'}';
$custom_data=base64_encode($custom_data);
$expiration='';  //не задаем явное значение, для примера
$api_key='1EA457132ABC39FBBA99A0EEFE0BF13D';

//формируем подпись
$signature=md5("$project_id$amount$recurrent_amount$recurrent_interval$recurrent_period$recurrent_max_periods$recurrent_start_date$currency_code$manual_confirmation$description$reference_1$reference_2$reference_3$reference_3_is_unique$custom_data$expiration$api_key");

//значение подписи 7dbf7777db3577cfc8689983f0114cdb

//дополнительные параметры
$language='ru-RU';

//формируем ссылку
$paymentnut_payment_page="ДОМЕН/api/payment-subscription/v2/project_id=$project_id&recurrent_interval=$recurrent_interval&recurrent_period=$recurrent_period&recurrent_max_periods=$recurrent_max_periods&amount=$amount&recurrent_amount=$recurrent_amount&currency_code=$currency_code&recurrent_start_date=$recurrent_start_date&manual_confirmation=$manual_confirmation&description=$description&language=$language&reference_1=$reference_1&reference_2=$reference_2&reference_3=$reference_3&reference_3_is_unique=$reference_3_is_unique&custom_data=$custom_data&expiration=$expiration&signature=$signature";

//значение ссылки ДОМЕН/api/payment-subscription/v2/project_id=0D2239F1BBDAA3E4F98CFD0CDF2F9D73&recurrent_interval=1&recurrent_period=1&recurrent_max_periods=0&amount=95.25&recurrent_amount=780.00&currency_code=RUB&recurrent_start_date=&manual_confirmation=0&description=Оплата услуги А&language=ru-RU&reference_1=Customer 1&reference_2=Invoice 1&reference_3=Account 1&reference_3_is_unique=&custom_data=e3N5c3RlbV9pZDogJzU4MycsIHBheW1lbnRfaWQ6ICdEMjk4NC0zJ30=&expiration=&signature=7dbf7777db3577cfc8689983f0114cdb

//перенаправляем на ссылку
header("Location: $paymentnut_payment_page");





Ошибки при открытии страницы оплаты

В случае, если при открытии страницы оплаты возвращается один или несколько кодов ошибок, сверьтесь со значениями ошибок ниже. Если Вы не можете определить причину ошибки, то обратитесь в службу поддержки указав используемую ссылку.

Код ошибки Значение
3 Недопустимые символы или кол–во символов в поле project_id
4 Недопустимые символы или кол–во символов в поле signature
5 Недопустимые символы или кол–во символов в поле reference_1
6 Недопустимые символы или кол–во символов в поле reference_2
7 Недопустимые символы или кол–во символов в поле reference_3
8 Недопустимые символы или кол–во символов в поле amount
9 Недопустимые символы или кол–во символов в поле currency_code
10 Недопустимые символы или кол–во символов в поле description
11 Неправильный формат ссылки success_url (после расшифровки по base64)
13 Недопустимые символы в поле success_url (после расшифровки по base64)
15 Превышено максимальное кол–во символов в поле success_url (после расшифровки по base64)
17 Недопустимые символы или кол–во символов в поле language
18 Идентификатор проекта (project_id) указан неверно или проект не может принимать платежи или проект не может работать по API
19 Неправильная подпись (signature)
24 Значение поля amount менее минимального
25 Недопустимое значение поля currency_code
26 Недопустимое значение поля language
27 Недопустимые символы или кол–во символов в поле manual_confirmation
28 Недопустимое значение поля manual_confirmation
31 Значение поля amount превышает максимальное
35 Недопустимое кол–во цифр после разделителя в поле amount
36 Недопустимые символы в поле success_url (до расшифровки по base64)
37 Недопустимое значение поля recurrent_interval
38 Недопустимое значение поля recurrent_period
39 Пустое значение поля recurrent_max_periods
40 Значение поля recurrent_interval в сочетании с recurrent_period дают интервал между платежами более одного года
41 Недопустимые символы или кол–во символов в поле recurrent_amount
42 Значение поля recurrent_amount менее минимального
43 Значение поля recurrent_amount превышает максимальное
44 Значение поля recurrent_start_date менее 12 часов позднее текущего времени
45 Значение поля recurrent_start_date превышает один год от текущего времени
46 Недопустимое кол–во цифр после разделителя в поле recurrent_amount
47 Недопустимые символы в поле recurrent_period
48 Недопустимые символы в поле recurrent_max_periods
49 Недопустимые символы в поле recurrent_start_date
52 Недопустимые символы или кол–во символов в поле custom_data
54 Значение поля manual_confirmation (1) несовместимо с тарифным планом проекта
55 Недопустимое кол–во символов в поле recurrent_max_periods
58 Недопустимые символы в expiration
59 Недопустимое кол–во символов в expiration
60 Срабатывание правила expiration: текущее время превышает expiration (срок действия платежной ссылки истек)
61 Недопустимое значение reference_3_is_unique
62 Значение reference_3_is_unique задано, но не задано значение reference_3
63 Срабатывание правила reference_3_is_unique: ранее уже проводилась успешная транзакция (status=3/4) с таким же значением reference_3
64 Проекту не согласован данный метод API