Prodamus
Search…
Документация для самостоятельной интеграции сервисов
В данный раздел поможет интегрировать Продамус с системами, для которых нет официальной интеграции. А так же поможет разработчикам, прописать дополнительные параметры для уже существующих интеграций

Формируем запрос

Для формирования платежной ссылки вам необходимо отправить GET или POST запрос себе на платежную страницу
Где прописать URL-адрес и скопировать секретный ключ подробно в разделе "Где найти url для уведомлений и секретный ключ"
В зависимости от сервиса, с которым вы интегрируетесь, вы можете прописывать параметры платежной страницы отдельно, передавая их программным кодом или использую стандартные команды вашего сервиса (например Автопилот или SmartSender) либо в самой ссылке Get-запроса.
Для формирования GET или POST запроса вам потребуется:
    URL-адрес платежной формы в системе Продамус. По сути это адрес из адресной строки вашей платежной страницы
ссылка должна быть вида http://название_поддомена.payform.ru/
Например https://demo.payform.ru/

Параметры, которые вы можете передать в запросе

Обязательные параметры при формировании ссылки

Параметр
Тип
Описание
sys
строка
код системы интернет-магазина (необходимо согласовать с поддержкой Продамуса)

Возможные значения параметра do

    1.
    "link" - возвращает ссылку, которую отправляем пользователю для самостоятельного перехода на страницу оплаты
    2.
    "pay" - отправляет покупателя сразу на оплату. Используется для интернет-магазинов действие "Оплата"

Параметры массива products

Параметр
Тип
Описание
Обязательный
name
строка
наименование товара
ДА
price
число
цена товара
ДА
quantity
целое число
количество товара
ДА
sku
строка
id товара в системе интернет-магазин
НЕТ
Чтобы прописать параметры массива: наименование, цена и количество товара, необходимо обратиться в глубь массива products
Это может выглядеть так products[0]name (для php) или так products.0.price (для java-скрипта) в зависимости от нюансов системы, на котором вы производите настройки
Параметры продукта, являются НЕобязательными
Параметр
Тип
Описание
order_sum
число
сумма заказа
discount_value
число
размер скидки в рублях

Параметры для рекуррентных платежей

Параметр
Тип
Описание
Обязательный
subscription
целое число
id подписки
ДА
subscription_date_start
строка
дата начала подписки в формате "гггг-мм-дд чч:мм"
P.S. Если указать дату в прошлом, то старт подписки будет сдвинут на интервал этой подписки.
нет
subscription_demo_period
целое число
количество дней демо-периода подписки
нет
subscription_limit_autopayments
целое число
максимальное количество авто-платежей по подписке
если не указано или меньше единицы, значение будет взято из настроек подписного товара
нет
Параметры для пользователей Вк, являются НЕобязательными
Параметр
Тип
Описание
vk_user_id
целое число
id пользователя в системе Вк
vk_user_name
строка
ФИО пользователя в системе Вк

Параметры передающие данные о юр.статусе плательщика

Параметр
Тип
Описание
npd_income_type
строка
тип плательщика, с возможными значениями:
FROM_INDIVIDUAL - физическое лицо
FROM_LEGAL_ENTITY - юридическое лицо
FROM_FOREIGN_AGENCY - иностранная организация
значение по умолчанию: FROM_INDIVIDUAL
npd_income_inn
целое число
инн плательщика
обязательно, если форма работает в режиме самозанятого и тип плательщика FROM_LEGAL_ENTITY
npd_income_company
строка
название компании плательщика
обязательно, если форма в режиме самозанятого и тип плательщика FROM_LEGAL_ENTITY или FROM_FOREIGN_AGENCY

Общие Необязательные параметры

Параметр
Тип
Описание
order_id
строка
номер заказа в Вашей системе
customer_phone
строка
номер телефона клиента (обязательный к заполнению при оплате, подробнее о параметре customer_phone)
customer_email
строка
e-mail адрес клиента
customer_extra
строка
описание заказа (Поле дополнительные данные)
ref
строка
идентификатор партнера (ПРОМОКОД)
paid_content
строка
платный контент
link_expired
строка
срок действия ссылки в формате "гггг-мм-дд чч:мм"
payment_method
строка
метод оплаты, выбранный клиентом, если есть возможность выбора на стороне интернет-магазина, иначе клиент выбирает метод оплаты на стороне платежной формы
доступные значения:
AC - банковская карта
PC - Яндекс.Деньги
QW - Qiwi Wallet
WM - Webmoney
GP - платежный терминал sbol - Сбербанк онлайн
invoice - Оплата по счету
installment_0_0_3 - Рассрочка от Тинькофф на 3 месяца
installment_0_0_6 - Рассрочка от Тинькофф на 6 месяцев
installment_0_0_10 - Рассрочка от Тинькофф на 10 месяцев
installment_0_0_12 - Рассрочка от Тинькофф на 12 месяцев
installment_0_0_24 - Рассрочка от Тинькофф на 24 месяца
installment_0_0_36 - Рассрочка от Тинькофф на 36 месяцев
available_payment_methods
строка
Список доступных методов оплаты. Список возможных значений аналогичен параметру payment_method. Допускается передача нескольких значений, разделяя их вертикальной чертой. Если available_payment_methods передан, то список доступных методов оплаты будет ограничен переданными кодами. Если в результате фильтрации не остается ни одного метода оплаты, данный параметр будет проигнорирован и выведется полный список доступных методов.
urlReturn
строка
URL-адрес для возврата пользователя без оплаты
urlSuccess
строка
URL-адрес для возврата пользователя при успешной оплате
urlNotification
строка
служебный URL-адрес для уведомления интернет-магазина о поступлении оплаты по заказу
в случае успешной обработки запроса, должен вернуть ответ с кодом 200
_param_хххх
строка
произвольный сквозной параметр, где хххх - имя вашего произвольного параметра
_utm_хххх
строка
сквозной параметр в виде utm-метки, где хххх - имя вашей метки
Например: _utm_source
installments_disabled
целое число
отключение рассрочки
если передан и не 0, методы оплаты связанные с рассрочкой будут недоступны для выбора при оплате
demoFlow
строка
Параметр для проверки негативного сценария с отказом по рассрочке. ❗Работает только в демо-режиме❗ Доступное значение:
reject

Параметр customer_phone

Данный параметр является обязательным при оплате покупателем товара на вашей платежной странице, но не является обязательным при формировании ссылки.
То есть вы можете сформировать ссылку на оплату не указывая номер телефона покупателя, он заполнит это поле самостоятельно. В этом случае покупателю откроется ссылка в предварительном окне оплаты, где система попросит заполнить поле номер телефона (рис. 1
) и после его заполнения и нажатия кнопки "Оплатить" ваш плательщик уже перейдет на страницу с выбором метода оплаты и сможет оплатить товар (рис.2
)
Если вы хотите исключить дополнительный шаг при покупке, то можете прописать параметр customer_phone уже при формировании ссылки на оплату, тогда ваш покупатель будет переходить сразу на шаг выбора удобного ему метода оплаты (рис.2
)
рис. 1
рис. 2
Параметры urlReturn и urlSuccess актуальны, например, в тех случаях, когда оплата была инициирована на стороне Вашего интернет-магазина и необходимо чтобы пользователь вернулся обратно. В случае отсутствия данных параметров в запросе, сообщение об успехе или ошибке, после оплаты, будет показано показано на платежной странице системы Продамус.
Если передан параметр subscription, параметр products игнорируется.

Ссылка на оплату

При значении параметра do=link ссылка возвращается в текстовом формате вида https://payform.ru/u8zDE/
Именно ее вам необходимо передать клиенту по средствам возможности вашего бота при помощи сообщения в мессенджере или через сторонние сервисы-рассыльщики
Так же есть возможность прописать развернутую ссылку с прописанными необходимыми в ней параметрами
Пример ссылки с запросом и прописанными в ней параметрами:
https://demo.payform.ru/?order_id=test&customer_phone=79998887755&products[0][price]=2000&products[0][quantity]=1&products[0][name]=Обучающие материалы&customer_extra=Полная оплата курса&do=pay

При настройке самостоятельной интеграции

Чтобы сформировать Webhook на стороне вашего сервиса для передачи данных об плате, вам необходимо добавить программный код на вашем сайте

Пример программного кода формирования ссылки для демо-формы:

В данном примере используется платежная страница демо-формы: https://demo.payform.ru
Секретный ключ демо-формы: 2y2aw4oknnke80bp1a8fniwuuq7tdkwmmuq7vwi4nzbr8z1182ftbn6p8mhw3bhz
1
<?php
2
3
header('Content-type:text/plain;charset=utf-8');
4
5
require_once __DIR__ . '/Hmac.php';
6
7
$linktoform = 'https://demo.payform.ru/';
8
9
// Секретный ключ. Можно найти на странице настроек,
10
// в личном кабинете платежной формы.
11
$secret_key = '2y2aw4oknnke80bp1a8fniwuuq7tdkwmmuq7vwi4nzbr8z1182ftbn6p8mhw3bhz';
12
13
$data = [
14
// хххх - номер заказ в системе интернет-магазина
15
'order_id' => хххх,
16
17
// +7хххххххххх - мобильный телефон клиента
18
'customer_phone' => '+7хххххххххх',
19
20
// ИМЯ@prodamus.ru - e-mail адрес клиента
21
'customer_email' => 'ИМЯ@prodamus.ru',
22
23
// перечень товаров заказа
24
'products' => [
25
[
26
// id товара в системе интернет-магазина
27
// (не обязательно) - при необходимоти прописать
28
'sku' => ХХХХХ,
29
30
// название товара - необходимо прописать название вашего товара
31
// (обязательный параметр)
32
'name' => 'товар 1',
33
34
// цена за единицу товара, 123 - значение, которое нужно прописать
35
// (обязательный параметр)
36
'price' => '123',
37
38
// количество товара, х - значение, которое нужно прописать
39
// (обязательный параметр)
40
'quantity' => 'Х',
41
42
// данные о налоге
43
// (не обязательно, если не указано будет взято из настроек Магазина
44
// на стороне системы)
45
'tax' => [
46
47
// ставка НДС, с возможными значениями (при необходимоти заменить):
48
// 0 – без НДС;
49
// 1 – НДС по ставке 0%;
50
// 2 – НДС чека по ставке 10%;
51
// 3 – НДС чека по ставке 18%;
52
// 4 – НДС чека по расчетной ставке 10/110;
53
// 5 – НДС чека по расчетной ставке 18/118.
54
// 6 - НДС чека по ставке 20%;
55
// 7 - НДС чека по расчётной ставке 20/120.
56
'tax_type' => 0,
57
58
// (не обязательно) сумма налога, хх - при необходимости заменить
59
'tax_sum' => хх,
60
61
],
62
63
// Тип оплаты, с возможными значениями (при необходимости заменить):
64
// 1 - полная предварительная оплата до момента передачи предмета расчёта;
65
// 2 - частичная предварительная оплата до момента передачи
66
// предмета расчёта;
67
// 3 - аванс;
68
// 4 - полная оплата в момент передачи предмета расчёта;
69
// 5 - частичная оплата предмета расчёта в момент его передачи
70
// с последующей оплатой в кредит;
71
// 6 - передача предмета расчёта без его оплаты в момент
72
// его передачи с последующей оплатой в кредит;
73
// 7 - оплата предмета расчёта после его передачи с оплатой в кредит.
74
// (не обязательно, если не указано будет взято из настроек
75
// Магазина на стороне системы)
76
'paymentMethod' => х,
77
78
// Тип оплачиваемой позиции, с возможными
79
// значениями (при необходимости заменить):
80
// 1 - товар;
81
// 2 - подакцизный товар;
82
// 3 - работа;
83
// 4 - услуга;
84
// 5 - ставка азартной игры;
85
// 6 - выигрыш азартной игры;
86
// 7 - лотерейный билет;
87
// 8 - выигрыш лотереи;
88
// 9 - предоставление РИД;
89
// 10 - платёж;
90
// 11 - агентское вознаграждение;
91
// 12 - составной предмет расчёта;
92
// 13 - иной предмет расчёта.
93
// (не обязательно, если не указано будет взято из настроек Магазина на стороне системы)
94
'paymentObject' => х,
95
],
96
],
97
98
// id подписки (при необходимости прописать)
99
// актуально и обязательно только для рекуррентных платежей,
100
// передается вместо параметра products
101
'subscription' => 123,
102
103
// вк id пользователя (при необходимости прописать)
104
'vk_user_id' => 123,
105
106
// фио пользователя в ВК (при необходимости прописать)
107
'vk_user_name' => 'Фамилия Имя Отчество',
108
109
// дополнительные данные
110
'customer_extra' => 'Текст, который отобразится в поле "Дополнительные данные"',
111
112
// для интернет-магазинов доступно только действие "Оплата"
113
'do' => 'pay',
114
115
// url-адрес для возврата пользователя без оплаты
116
// (при необходимости прописать свой адрес)
117
'urlReturn' => 'https://demo.payform.ru/demo-return',
118
119
// url-адрес для возврата пользователя при успешной оплате
120
// (при необходимости прописать свой адрес)
121
'urlSuccess' => 'https://demo.payform.ru/demo-success',
122
123
// служебный url-адрес для уведомления интернет-магазина
124
// о поступлении оплаты по заказу
125
// пока реализован только для Advantshop,
126
// формат данных настроен под систему интернет-магазина
127
// (при необходимости прописать свой адрес)
128
'urlNotification' => 'https://demo.payform.ru/demo-notification',
129
130
// код системы интернет-магазина, запросить у поддержки,
131
// для самописных систем можно оставлять пустым полем
132
// (при необходимости прописать свой код)
133
'sys' => 'код системы',
134
135
// метод оплаты, выбранный клиентом
136
// если есть возможность выбора на стороне интернет-магазина,
137
// иначе клиент выбирает метод оплаты на стороне платежной формы
138
// варианты (при необходимости прописать значение):
139
// AC - банковская карта
140
// PC - Яндекс.Деньги
141
// QW - Qiwi Wallet
142
// WM - Webmoney
143
// GP - платежный терминал
144
'payment_method' => 'ХХ',
145
146
// сумма скидки на заказ
147
// указывается только в том случае, если скидка
148
// не прменена к товарным позициям на стороне интернет-магазина
149
// алгоритм распределения скидки по товарам
150
// настраивается на стороне пейформы
151
'discount_value' => 0.00,
152
153
// тип плательщика, с возможными значениями:
154
// FROM_INDIVIDUAL - Физическое лицо
155
// FROM_LEGAL_ENTITY - Юридическое лицо
156
// FROM_FOREIGN_AGENCY - Иностранная организация
157
// (не обязательно. если форма работает в режиме самозанятого
158
// значение по умолчанию: FROM_INDIVIDUAL)
159
'npd_income_type' => 'FROM_INDIVIDUAL',
160
161
// инн плательщика (при необходимости прописат)
162
// (обязательно, если форма в режиме самозанятого
163
// и тип плательщика FROM_LEGAL_ENTITY)
164
'npd_income_inn' => 1234567890,
165
166
// название компании плательщика (при необходимости прописать название)
167
// (обязательно, если форма в режиме самозанятого
168
// и тип плательщика FROM_LEGAL_ENTITY или FROM_FOREIGN_AGENCY)
169
'npd_income_company' => 'Название компании плательщика',
170
171
// срок действия ссылки в формате: дд.мм.гггг чч:мм или гггг-мм-дд чч:мм
172
// при необходимости добавить дату
173
// (не обязательно, по умолчанию срок действия ссылки не ограничен)
174
'link_expired' => 'дд.мм.гггг чч:мм',
175
176
// дата начала подписки в формате: дд.мм.гггг чч:мм или гггг-мм-дд чч:мм
177
// при необходимости добавить дату
178
// (не обязательно, актуально только для рекуррентных платежей,
179
// по умолчанию текущая дата/время)
180
'subscription_date_start' => 'дд.мм.гггг чч:мм',
181
182
// текст который будет показан пользователю после совершения оплаты
183
// (не обязательно)
184
'paid_content' => 'Текс сообщения'
185
];
186
187
188
$data['signature'] = Hmac::create($data, $secret_key);
189
190
$link = sprintf('%s?%s', $linktoform, http_build_query($data));
Copied!
Массив data содержит данные для формирования платежной ссылки. Параметр signature - подпись запроса. Формируется на основе данных формы и секретного ключа. Для формирования подписи запроса можно воспользоваться готовой библиотекой Hmac
Hmac.php
1KB
Binary
Библиотека Hmac.php
Hmac.js.zip
1KB
Binary
Библиотека Hmac.js

Как принять Уведомление об успешной оплате

При настройке принятия веб-хука с уведомлением об успешной оплате на вашем сервисе (пример уведомления об оплате здесь), вам необходимо проверить подпись пришедшего запроса. Так скажем, убедиться, что Веб-Хук пришел именно от Продамуса.
Проверка подписи необходима в целях безопасности, иначе, технически, веб-хук может отправить кто угодно. Подпись формируется на основе данных запроса и секретного ключа вашей платежной страницы.
Для проверки подписи, необходимо вызвать метод verify класса Hmac, в качестве аргументов передайте данные входящего POST запроса, секретный ключ платежной страницы и подпись из заголовков запроса. Метод сформирует подпись на основе данных запроса и секретного ключа (аргументы 1 и 2) и сравнит его с подписью, которая была передана в запросе (аргумент 3). Если метод вернул false (подписи не совпадают), необходимо вернуть http-код отличный от 200 и прекратить дальнейшую обработку. В случае, если метод вернул true (подписи совпадают), необходимо вернуть http-код 200 и отработать дальнейшие команды на стороне вашего сервиса.
Пример проверки подписи запроса:
1
require_once 'Hmac.php';
2
3
$secret_key = 'ваш_секретный_ключ';
4
$headers = apache_request_headers();
5
6
try {
7
if ( empty($_POST) ) {
8
throw new Exception('$_POST is empty');
9
}
10
elseif ( empty($headers['Sign']) ) {
11
throw new Exception('signature not found');
12
}
13
elseif ( !Hmac::verify($_POST, $secret_key, $headers['Sign']) ) {
14
throw new Exception('signature incorrect');
15
}
16
17
http_response_code(200);
18
echo 'success';
19
}
20
catch (Exception $e) {
21
http_response_code($e->getCode() ? $e->getCode() : 400);
22
printf('error: %s', $e->getMessage());
23
}
Copied!
Hmac.php
1KB
Binary
Библиотека Hmac

Проверка успешной интеграции

Для тестирования используйте свою платежную странницу, в исключительном случае вы можете воспользоваться данными нашей демо-страницы, для этого необходимо запросить доступ у менеджеров
по телефону: 8 (495) 150-08-71
в личные сообщения группы в VK: https://vk.com/im?sel=-11636316
на электронную почту: [email protected]
в Телеграм-канале: https://t.me/prodamus_bot
После всех настроек обязательно проверьте формирование ссылки. Пройдите по ней, проверьте все ли параметры прописаны корректно
После завершения тестирования интеграции с Вашей стороны, просим написать в поддержку Продамуса. Мы осуществим проверку со своей стороны.
А так же разместим соответствующую информацию на своих сайтах и группах в соцсетях
Last modified 29d ago