Для интеграции платежей через Uniteller с использованием PHP необходимо использовать их API, которое поддерживает создание одноразовых и постоянных ссылок на оплату. Основной метод – формирование запроса к серверу Uniteller с указанием суммы, валюты, описания заказа и уникального идентификатора транзакции.
Шаг 1: подготовка параметров. Минимальный набор включает сумму в копейках, валюту (RUB, USD, EUR), описание заказа и уникальный номер. Все данные следует передавать в кодировке UTF-8, чтобы избежать ошибок при генерации подписи.
Шаг 2: формирование подписи. Uniteller требует передачи контрольной подписи, созданной на основе секретного ключа и параметров запроса. Для PHP удобно использовать функцию hash_hmac(‘sha256’, $data, $secretKey), где $data – строка, объединяющая ключевые параметры.
Шаг 3: отправка запроса. После формирования подписи создается URL с параметрами GET или POST-запрос к API Uniteller. В ответ сервис возвращает ссылку на оплату, которую можно передавать клиенту.
В процессе разработки рекомендуется логировать все параметры запроса и ответы сервера, чтобы ускорить отладку и избежать проблем с некорректными транзакциями. Также важно проверять статус ответа Uniteller перед подтверждением заказа на стороне сайта.
Регистрация и получение API-ключа Uniteller
Для работы с Uniteller необходимо создать аккаунт на платформе. Перейдите на официальный сайт uniteller.ru и выберите раздел Регистрация. Укажите корректные данные компании: ИНН, название юридического лица, контактный e-mail и телефон.
После отправки формы на указанный e-mail придет письмо с подтверждением регистрации. Аккаунт необходимо активировать, перейдя по ссылке в письме.
Для получения API-ключа авторизуйтесь в личном кабинете и откройте раздел Настройки интеграции или API. Выберите создание нового ключа, задайте описание для идентификации (например, «Интеграция с сайтом») и сохраните ключ в безопасном месте.
Uniteller предоставляет два типа ключей: тестовый и боевой. Тестовый ключ предназначен для отработки сценариев платежей без списания реальных средств. Боевой ключ необходим для проведения операций с реальными платежами. Использование ключей в коде PHP должно учитывать их назначение, чтобы случайно не выполнять платежи через тестовый ключ в продакшн-среде.
API-ключ формируется в виде длинной строки из букв и цифр. При передаче его в запросах соблюдайте конфиденциальность: храните в переменных окружения или защищенных конфигурационных файлах, не включайте напрямую в публичный код.
Для успешного подключения убедитесь, что ваш сервер поддерживает HTTPS и имеет доступ к uniteller.ru, иначе запросы к API будут отклоняться.
Настройка PHP для работы с API Uniteller
Для взаимодействия с API Uniteller требуется PHP версии не ниже 7.4 и поддержка расширения cURL. Убедитесь, что расширения json и mbstring активированы.
Основные шаги настройки:
- Установка cURL:
- На Linux:
sudo apt install php-curl - На Windows: раскомментируйте
extension=curlв php.ini
- На Linux:
- Проверка доступности JSON:
- Выполните
php -m | grep json; модуль должен присутствовать
- Выполните
- Настройка сертификатов SSL:
- Скачайте актуальный файл
cacert.pemс curl.se - Укажите путь в php.ini через
curl.cainfo = "C:\path\to\cacert.pem"или/etc/ssl/certs/cacert.pem
- Скачайте актуальный файл
Для работы с Uniteller API требуется API-ключ. Создайте его в личном кабинете Uniteller и сохраните в защищённом файле конфигурации. Пример хранения:
<?php
return [
'api_key' => 'ваш_api_ключ',
'merchant_id' => 'идентификатор_мерчанта',
'api_url' => 'https://api.uniteller.ru/v2/'
];
?>Рекомендуется использовать функцию require_once для подключения конфигурации и проверку наличия всех ключей перед отправкой запросов. Это снижает риск ошибок авторизации.
$ch = curl_init();
curl_setopt($ch, CURLOPT_VERBOSE, true);Это позволяет отслеживать заголовки HTTP и тело запроса, что важно при формировании платежных ссылок и проверке ответов API.
Формирование данных платежа в формате JSON
Для генерации ссылки на оплату Uniteller требуется передавать платежные данные в формате JSON. Структура JSON должна включать ключевые параметры: order_id, amount, currency, description и customer.
Пример структуры:
{
"order_id": "12345",
"amount": 1500.00,
"currency": "RUB",
"description": "Оплата заказа №12345",
"customer": {
"email": "client@example.com",
"phone": "+79001234567"
}
}order_id должен быть уникальным для каждого платежа. amount указывается в виде числа с точностью до двух знаков после запятой. currency принимает значения ISO 4217, чаще всего «RUB». description формируется максимально конкретно, чтобы покупатель и система могли однозначно идентифицировать заказ.
Объект customer должен содержать хотя бы один идентификатор: email или phone. Если указаны оба, Uniteller использует их для подтверждения платежа и уведомлений.
Для передачи JSON в PHP используйте функцию json_encode(). Перед кодированием убедитесь, что все данные имеют корректный тип: строки для текста, числа для суммы, массив для объекта клиента. Например:
$paymentData = [
"order_id" => "12345",
"amount" => 1500.00,
"currency" => "RUB",
"description" => "Оплата заказа №12345",
"customer" => [
"email" => "client@example.com",
"phone" => "+79001234567"
]
];
$jsonData = json_encode($paymentData, JSON_UNESCAPED_UNICODE);Использование JSON_UNESCAPED_UNICODE предотвращает кодирование кириллицы в Unicode, что делает описание и имя клиента читаемыми в платежной ссылке.
Корректно сформированный JSON является обязательным условием для успешной генерации ссылки на оплату через API Uniteller.
Создание запроса на генерацию ссылки через cURL
Для формирования запроса на генерацию ссылки Uniteller используется метод POST с передачей JSON-данных. Обязательные параметры включают merchant_id, amount, order_id и description. Пример запроса через cURL:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.uniteller.ru/v1/payment");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$data = json_encode(array(
'merchant_id' => 'ВАШ_MERCHANT_ID',
'amount' => 1500,
'order_id' => 'ORD12345',
'description' => 'Оплата заказа #ORD12345'
));
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
$link = $result['payment_url'];
Важно проверять HTTP-код ответа. Для успешного запроса ожидается код 200 и наличие ключа payment_url в JSON-ответе. Если код отличается или ключ отсутствует, запрос следует логировать и повторять с корректировкой данных.
Рекомендуется использовать тайм-ауты и повторные попытки при сетевых сбоях. Например, через опции CURLOPT_TIMEOUT и CURLOPT_CONNECTTIMEOUT. Для безопасной передачи данных следует использовать HTTPS и проверять сертификат сервера с CURLOPT_SSL_VERIFYPEER.
В случае передачи дополнительных параметров, таких как email клиента или success_url, их включают в массив JSON. Uniteller автоматически добавляет их к сгенерированной ссылке, что позволяет адаптировать платежную форму под конкретный заказ.
Обработка ответа и извлечение ссылки на оплату
После формирования запроса к API Uniteller сервер возвращает JSON-ответ, содержащий ключевые параметры платежа. Для извлечения ссылки на оплату необходимо выполнить следующие действия:
- Декодировать JSON-ответ с помощью функции
json_decode: - Проверить наличие обязательного поля
'payment_url': - Сохранить значение ссылки для дальнейшего использования:
- При необходимости зарегистрировать ссылку в базе данных или передать пользователю через интерфейс:
- Для базы данных: использовать подготовленные выражения
PDOилиmysqliдля безопасного сохранения.
$response = json_decode($apiResult, true);if (!isset($response['payment_url'])) {
throw new Exception('Ссылка на оплату отсутствует в ответе API');
}$paymentLink = $response['payment_url'];Дополнительно рекомендуется проверять поле 'status' в ответе API, чтобы убедиться, что платеж доступен для генерации ссылки. Если статус не 'success', обработку ссылки следует прервать и зарегистрировать ошибку.
Пример полной обработки ответа:
$response = json_decode($apiResult, true);
if ($response['status'] !== 'success') {
error_log('Ошибка генерации ссылки: ' . $response['error_message']);
return;
}
$paymentLink = $response['payment_url'];
echo 'Оплатить';Отладка ошибок при генерации ссылок
Ошибки при формировании ссылок на оплату Uniteller чаще всего связаны с некорректными параметрами запроса или проблемами в обработке данных на стороне PHP. Для эффективной диагностики используйте пошаговый подход.
Первый шаг – проверка обязательных полей. Uniteller требует корректные значения для:
| Параметр | Описание |
|---|---|
| merchantId | Идентификатор магазина, полученный от Uniteller |
| orderId | Уникальный номер заказа |
| amount | Сумма к оплате в копейках (целое число) |
| currency | Трёхсимвольный код валюты (например, RUB) |
| description | Краткое описание товара или услуги |
Следующий этап – проверка генерации контрольной подписи. Для PHP это обычно функция hash_hmac:
$signature = hash_hmac('sha256', $dataString, $secretKey);
Неправильный порядок полей или кодировка строки данных приведёт к отказу сервера Uniteller. Убедитесь, что строки соединяются без лишних пробелов и специальных символов.
Для выявления проблем с формированием ссылки рекомендуется логировать каждый шаг:
| Этап | Что логировать |
|---|---|
| Подготовка данных | Содержимое массива параметров перед генерацией подписи |
| Генерация подписи | Полученный хэш и исходная строка для подписи |
| Финальная ссылка | Полный URL с параметрами и подписью |
При ошибках сервера Uniteller проверяйте коды ответа HTTP и текст ошибки в теле ответа. Например, 400 указывает на неверные параметры, 403 – на неправильную подпись. Использование функции curl_getinfo() в PHP позволяет получить подробные данные запроса.
Для локальной отладки можно создавать тестовые заказы с минимальными суммами и фиксированными данными. Это ускоряет выявление ошибок без риска для реальных платежей.
Если ошибка повторяется, проверьте соответствие версий PHP и поддерживаемых библиотек OpenSSL, так как Uniteller использует HMAC SHA256 и TLS 1.2. Несовместимость может привести к некорректной подписи или отказу соединения.
Вопрос-ответ:
Как сгенерировать ссылку на оплату через Uniteller с помощью PHP?
Для создания ссылки на оплату через Uniteller необходимо сформировать массив с параметрами заказа: сумма, валюта, описание, уникальный идентификатор заказа и адреса для уведомлений. Затем этот массив передаётся в функцию формирования подписи и URL. После генерации ссылки её можно отправить клиенту или встроить в кнопку на сайте. Важный момент — корректно вычислять подпись с использованием секретного ключа, чтобы Uniteller принимал запрос.
Какие параметры обязательны при создании ссылки на оплату Uniteller?
Обязательными считаются параметры суммы (amount), валюты (currency), идентификатора заказа (order_id), имени или описания товара (description) и адресов для уведомлений о платеже (success_url, fail_url). Без этих данных система не сможет корректно сформировать платежную ссылку, и попытка оплаты завершится ошибкой. Дополнительно можно передавать email клиента или другие необязательные параметры для удобства учёта.
Как правильно вычислить подпись для ссылки Uniteller на PHP?
Подпись создаётся с использованием секретного ключа и хэш-функции, которую требует Uniteller. Обычно это SHA-256 или MD5, в зависимости от настроек вашего аккаунта. Все значения параметров сначала объединяются в определённом порядке в строку, после чего применяется хэш-функция вместе с ключом. Полученная подпись добавляется в URL как отдельный параметр. Любая ошибка в порядке параметров или ключе приведёт к тому, что ссылка не будет работать.
Можно ли автоматически генерировать ссылки на оплату для нескольких заказов?
Да, это можно реализовать с помощью цикла в PHP, который проходит по массиву заказов и для каждого формирует уникальную ссылку с учётом индивидуального идентификатора и суммы. Главное — убедиться, что для каждой ссылки создаётся правильная подпись и уникальный order_id. Такой подход позволяет интегрировать Uniteller в систему с большим количеством заказов и отправлять клиентам персонализированные ссылки.
Что делать, если ссылка на оплату Uniteller не работает?
Если ссылка не работает, сначала проверьте правильность всех обязательных параметров и корректность подписи. Часто ошибки возникают из-за неправильного порядка параметров при формировании подписи, неверного ключа или некорректного формата суммы. Также убедитесь, что success_url и fail_url доступны для сервера и корректно прописаны. После исправления этих моментов ссылка должна работать корректно.
Загрузка...
