Документация / API / Создание страницы оплаты

Документация для разработчиков / Работа с API / Формирование страницы оплаты

Один из способов приема платежей – через API, когда Ваш веб–сайт программно формирует ссылку для перехода к странице оплаты PaymentNut с конкретной детализацией платежа (наименование, цена, и т.п.) и перенаправляет Вашего клиента на эту страницу. Данный способ удобен для случаев, когда у Вас большая вариативность продуктов/услуг, и ручное создание Продукта или Счета в Личном Кабинете неудобно.

URL для приема платежей в RUB (карты выпущенные банками РФ и по СБП): ДОМЕН/api/payment/v2
URL для приема платежей в USD (карты выпущенные зарубежными банками): ДОМЕН/api/payment/v2
Значения доменов указаны в ЛК > Настройки проекта > API; обратите внимание, что домены для платежей в RUB и USD могут отличаться для Вашего проекта
Метод отправки: GET
Поддерживаемые параметры:

Наименование параметра	Описание	Допустимые символы	Минимальное, максимальное кол–во знаков	Допустимые значения	Обязателен	Пример
project_id	Идентификатор проекта; указан в настройках Проекта	[a-zA-Z0-9]	32, 32	Любые	Да	0D2239F1BBDAA3E4F98CFD0CDF2F9D73
amount	Сумма к оплате. Разделитель – точка (.). Обязательно всегда указывать два знака после разделителя.	[0-9.]	1,10	Минимальное: – 1.15 RUB – 11.00 USD Максимальное: – 1000000.00 RUB – 3000.00 USD	Да	95.25
currency_code	Код валюты оплаты. Прием RUB только с карт, выпущенных банками РФ. Прием USD только с зарубежных карт и по предварительному согласованию проекта (для согласования обратитесь в клиентскую поддержку).	–	–	RUB, USD	Да	RUB
manual_confirmation	Необходимость заморозки средств на карте. В случае включения данной опции, средства на карте будут первоначально заморожены (заблокированы/холдированы), списание произойдет автоматически на 7-ой день или ранее, если Вы вручную выполните операцию подтверждения через интерфейс карточки транзакции в Личном Кабинете. Транзакцию так же можно будет отменить до момента автоматического подтверждения через интерфейс карточки транзакции в ЛК или через API. Данная опция (значение 1) недоступна на тарифном плане Стандартный. Данная опция (значение 1) недоступна при оплате в USD.	–	–	0, 1	Да	0
description	Назначение платежа. Отображается на странице оплаты, в карточке транзакции в ЛК, в уведомлениях, API и т.п. При оплате в USD, не отображается на странице оплаты.	[a-zA-Z0-9-()*.,:;а-яА-Я ]	5, 300	Любые	Да	Оплата услуги А
language	Код языка интерфейса страницы оплаты по–умолчанию, допускается русский (ru-RU) и английский (en-US). При оплате в USD, применяется только en-US.	–	–	ru-RU, en-US	Да	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
success_url	В случае успешной оплаты, происходит перенаправление на указанный адрес. На этой странице Вы можете указать информацию по сборке заказа, подтверждение, что заказ принят в работу и т.п. В случае если значение адреса перенаправления не задано, то используется стандартная страница Сервиса. Не следует использовать факт перехода плательщиком на страницу success_url как подтверждение оплаты; для получения статуса платежа (списание средств, отклонения платежа и т.п.) используйте уведомления (вебхуки). Данная опция недоступна при оплате в USD (используется стандартная страница Сервиса)	Значение URL должно быть передано в зашифрованном виде, по стандарту Base64. Допустимые символы в изначальном значении URL [a-zA-Z0-9-\/._:=?&;#] Изначальное значение URL должно начинаться с http:// или https:// Допустимые символы в зашифрованном URL [a-zA-Z0-9=/].	Максимальное в изначальном значении URL – 300	Любые	Нет	aHR0cHM6Ly9leGFtcGxlLmNvbS9wYXltZW50X3N1Y2Nlc3M=
signature	Значение подписи составляется на основе значений нескольких вышеуказанных параметров (см. ниже)	[a-zA-Z0-9]	32, 32	Любые	Да	6D2239F1BZDAA3E4F98CFD0CDF2F9D18
email	Адрес электронной почты плательщика. PaymentNut требует плательщиков вводить их электронную почту перед непосредственной оплатой; для упрощения процесса оплаты Вы можете заранее указать электронную почту плательщика.	В соответствии с RFC 2822	5, 300	Любые	Нет	[email protected]

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

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

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

Например (PHP):

$project_id='0D2239F1BBDAA3E4F98CFD0CDF2F9D73';
$amount='95.25';
$currency_code='RUB';
$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$currency_code$manual_confirmation$description$reference_1$reference_2$reference_3$reference_3_is_unique$custom_data$expiration$api_key");

//значение подписи 5127d855b2cc73780609a8d65b8f81e7

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

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

ДОМЕН/api/payment/v2/project_id=0D2239F1BBDAA3E4F98CFD0CDF2F9D73&amount=95.25&currency_code=RUB&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=&success_url=aHR0cHM6Ly9leGFtcGxlLmNvbS9wYXltZW50X3N1Y2Nlc3M=&s[email protected]

Пример формирования ссылки для оплаты и перенаправления на страницу оплаты (PHP):

$project_id='0D2239F1BBDAA3E4F98CFD0CDF2F9D73';
$amount='95.25';
$currency_code='RUB';
$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$currency_code$manual_confirmation$description$reference_1$reference_2$reference_3$reference_3_is_unique$custom_data$expiration$api_key");

//значение подписи 5127d855b2cc73780609a8d65b8f81e7

//дополнительные параметры
$success_url_raw='https://example.com/payment_success';
$success_url=base64_encode($success_url_raw);
$language='ru-RU';
$email='[email protected]';

//формируем ссылку
$paymentnut_payment_page="ДОМЕН/api/payment/v2/project_id=$project_id&amount=$amount&currency_code=$currency_code&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&success_url=$success_url&signature=$signature&email=$email";

//значение ссылки ДОМЕН/api/payment/v2/project_id=0D2239F1BBDAA3E4F98CFD0CDF2F9D73&amount=95.25&currency_code=RUB&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=&success_url=aHR0cHM6Ly9leGFtcGxlLmNvbS9wYXltZW50X3N1Y2Nlc3M=&signature=5127d855b2cc73780609a8d65b8f81e7&email=test@example.com

//перенаправляем на ссылку
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) указан неверно или проект не может принимать платежи
19	Неправильная подпись (signature)
24	Значение поля amount менее минимального
25	Недопустимое значение поля currency_code
26	Недопустимое значение поля language
27	Недопустимые символы или кол–во символов в поле manual_confirmation
28	Недопустимое значение поля manual_confirmation
31	Значение поля amount превышает максимальное
35	Недопустимое кол–во цифр после разделителя в поле amount
36	Недопустимые символы в поле success_url (до расшифровки по base64)
52	Недопустимые символы или кол–во символов в поле custom_data
53	Значение поля manual_confirmation (1) несовместимо с валютой оплаты (currency_code)
54	Значение поля manual_confirmation (1) несовместимо с тарифным планом проекта
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
65	Неправильный домен/URL платежной ссылки для приема платежа в USD
67	Неправильный домен/URL платежной ссылки для приема платежа в RUB

Ошибки при открытии страницы оплаты для платежей в USD (карты выпущенные зарубежными банками)

1. Обратите внимание, что оплата иностранной картой невозможна, если пользователь открывает платежную ссылку/страницу имея IP адрес одной из стран, указанных в списке здесь.

2. Так же оплата иностранной картой невозможна, если пользователь имеет IP адрес разрешенной страны (не входящей в указанный выше список), но при этом использует VPN, прокси, TOR и т.п.

В обоих случаях, при открытии платежной страницы, после ввода электронной почты, выводится сообщение об ошибке (скриншот ниже). В случае если Ваш плательщик/клиент обращается с этой ошибкой и при этом не использует VPN/прокси/TOR, пожалуйста обратитесь в техническую поддержку PaymentNut для временного снятия данного ограничения.

В случае если IP адрес плательщика допустимый, вместо сообщения об ошибке отображается форма для ввода данных банковской карты.

В случае если Ваш IP адрес не пропускается и Вам необходимо провести тестовый платеж в целях тестирования работы вебхуков/API, то можете использовать платеж в рублях с российской карты.

Работа с API

Работа с уведомлениями

Документация для разработчиков / Работа с API / Формирование страницы оплаты