Документация Adsrek Pay API
Полное руководство по созданию счетов, HMAC-подписям, проверке статусов, callback-уведомлениям и внутренним выплатам на AR-кошельки.
Быстрый старт
Минимальный рабочий сценарий приёма оплаты.
payment_url.https://adsrekpay.compaid и проверки подписи.Общие требования
Формат запросов и поддерживаемые значения.
Все методы принимают только POST. Рекомендуемый заголовок: Content-Type: application/json. Также принимается обычный POST-массив.
Максимальный размер тела запроса — 65 536 байт. Превышение возвращает HTTP 413.
RUB, USD, EUR, USDT.
RUB, USD, EUR — 2 знака после точки. USDT — 8 знаков. Перед подписью сумма нормализуется сервером.
Счёт действует 24 часа с момента создания. В ответе приходит Unix timestamp expires_at.
Используйте UTF-8. Поля order_id и description очищаются и ограничиваются по длине.
Авторизация и HMAC-SHA256
Каждый запрос подписывается SECRET KEY выбранного сайта.
В запросе всегда передаются shop_id, api_key и 64-символьный шестнадцатеричный sign. SECRET KEY используется только для вычисления подписи и никогда не отправляется в API.
create|SHOP_ID|API_KEY|ORDER_ID|AMOUNT|CURRENCYstatus|SHOP_ID|API_KEY|ORDER_IDpayout|SHOP_ID|API_KEY|ORDER_ID|AMOUNT|CURRENCY|TARGETfunction adsrekSign(string $canonical, string $secretKey): string
{
return hash_hmac('sha256', $canonical, $secretKey);
}
$amount = number_format(10, 2, '.', '');
$canonical = 'create|1001|aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa|ORDER-1001|' . $amount . '|RUB';
$sign = adsrekSign($canonical, 'YOUR_SECRET_KEY');
10.00, а для 1 USDT — 1.00000000. Валюта передаётся в верхнем регистре.Создание счёта
POST https://adsrekpay.com/api/pay/create.php
| Поле | Обязательное | Описание |
|---|---|---|
shop_id | Да | ID сайта из кабинета. |
api_key | Да | Публичный API KEY сайта. |
order_id | Да | Уникальный ID заказа в пределах сайта, до 100 символов. |
amount | Да | Сумма не меньше 0.01. |
currency | Да | RUB, USD, EUR или USDT. |
description | Нет | Описание заказа, до 255 символов. |
callback_url | Нет | Публичный HTTPS URL. Переопределяет адрес сайта для этого счёта. |
success_url | Нет | HTTPS URL возврата после успешной оплаты. |
fail_url | Нет | HTTPS URL возврата при отмене или ошибке. |
sign | Да | HMAC-SHA256 канонической строки. |
{
"shop_id": 1001,
"api_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"order_id": "ORDER-1001",
"amount": "10.00",
"currency": "RUB",
"description": "Оплата заказа ORDER-1001",
"callback_url": "https://site.ru/payment/callback",
"success_url": "https://site.ru/payment/success",
"fail_url": "https://site.ru/payment/fail",
"sign": "HMAC_SHA256_HEX"
}
{
"ok": true,
"invoice_id": 1501,
"order_id": "ORDER-1001",
"status": "new",
"amount": "10.00",
"currency": "RUB",
"payment_url": "https://adsrekpay.com/merchant/invoice.php?id=TOKEN",
"expires_at": 1785704400
}
order_id, суммой и валютой вернёт существующий счёт. Если сумма или валюта отличаются, API вернёт ORDER_ID_CONFLICT.Проверка статуса счёта
POST https://adsrekpay.com/api/pay/status.php
{
"shop_id": 1001,
"api_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"order_id": "ORDER-1001",
"sign": "HMAC_SHA256_HEX"
}{
"ok": true,
"invoice": {
"id": "1501",
"order_id": "ORDER-1001",
"amount": "10.00",
"currency": "RUB",
"status": "paid",
"created_at": "1785618000",
"paid_at": "1785618125"
}
}Проверяйте одновременно status, amount, currency и order_id. Не считайте заказ оплаченным по одному только URL возврата.
Callback / webhook
Уведомление отправляется после успешной оплаты счёта.
POST application/x-www-form-urlencoded.
Любой HTTP-код от 200 до 299 считается успешной доставкой.
До 5 попыток, с интервалом не менее 5 минут, пока не получен 2xx.
Только публичный HTTPS, проверка SSL, без перенаправлений. Таймаут соединения 5 секунд, общий — 10 секунд.
invoice_id=1501
shop_id=1001order_id=ORDER-1001
amount=10.00
currency=RUB
status=paid
paid_at=1785618125
sign=HMAC_SHA256_HEXinvoice_id|shop_id|order_id|amount|currency|status
1501|1001|ORDER-1001|10.00|RUB|paid<?php
$secretKey = getenv('ADSREK_PAY_SECRET');
$data = $_POST;
$required = ['invoice_id','shop_id','order_id','amount','currency','status','sign'];
foreach ($required as $field) {
if (!isset($data[$field])) {
http_response_code(400);
exit('MISSING_FIELD');
}
}
$canonical = implode('|', [
(int)$data['invoice_id'],
(int)$data['shop_id'],
(string)$data['order_id'],
(string)$data['amount'],
(string)$data['currency'],
(string)$data['status'],
]);
$expected = hash_hmac('sha256', $canonical, $secretKey);
if (!hash_equals($expected, strtolower((string)$data['sign']))) {
http_response_code(401);
exit('BAD_SIGNATURE');
}
// Найдите заказ по order_id и заблокируйте строку в транзакции БД.
// Повторный callback для уже оплаченного заказа должен вернуть 200 без повторного начисления.
if ($data['status'] === 'paid') {
// Дополнительно сравните amount и currency с вашим заказом.
// Отметьте заказ оплаченным атомарно.
}
http_response_code(200);
echo 'OK';
Выплата на AR-кошелёк
POST https://adsrekpay.com/api/pay/payout.php
{
"shop_id": 1001,
"api_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"order_id": "PAYOUT-1001",
"amount": "10.00",
"currency": "RUB",
"target": "AR584193027",
"sign": "HMAC_SHA256_HEX"
}{
"ok": true,
"payout": {
"transfer_id": 9021,
"amount": "10.00",
"currency": "RUB",
"recipient": "AR584193027"
}
}order_id обязателен и обеспечивает идемпотентность. При повторе успешно выполненной выплаты API вернёт сохранённый результат, а не спишет деньги ещё раз.
Статусы счёта
Фактические статусы Merchant API v1.
newОжидает оплатыСчёт создан и доступен клиенту.paidОплаченФинальный успешный статус.expiredИстёкПрошло 24 часа без оплаты.cancelОтменёнФинальный статус отмены.refundedВозвращёнСредства возвращены.Ошибки API
Ответ ошибки имеет вид {"ok":false,"error":"CODE"}.
| HTTP | Код | Значение |
|---|---|---|
| 400 | INVALID_JSON | Тело запроса не удалось разобрать. |
| 401 | AUTH_REQUIRED | Отсутствуют shop_id, api_key или корректная 64-символьная подпись. |
| 401 | SHOP_NOT_FOUND | Сайт не найден, выключен или API KEY неверен. |
| 401 | BAD_SIGNATURE | HMAC-подпись не совпала. |
| 401 | SHOP_SECRET_ERROR | Сервер не смог расшифровать SECRET KEY сайта. |
| 404 | INVOICE_NOT_FOUND | Счёт с указанным order_id не найден. |
| 405 | METHOD_NOT_ALLOWED | Использован метод, отличный от POST. |
| 413 | PAYLOAD_TOO_LARGE | Тело запроса превышает 65 536 байт. |
| 422 | BAD_CURRENCY | Валюта не поддерживается. |
| 422 | BAD_AMOUNT | Сумма не прошла нормализацию. |
| 422 | BAD_INVOICE | Пустой order_id или сумма меньше минимальной. |
| 422 | BAD_CALLBACK_URL | Callback URL не является публичным HTTPS-адресом. |
| 422 | ORDER_ID_CONFLICT | Повторный order_id передан с другой суммой или валютой. |
| 422 | RECIPIENT_NOT_FOUND | Получатель внутренней выплаты не найден. |
| 422 | INSUFFICIENT_FUNDS | На балансе магазина недостаточно суммы и комиссии. |
| 422 | DUPLICATE_OR_IN_PROGRESS | Выплата с этим order_id уже выполняется или завершилась ошибкой. |
| 422 | SELF_PAYOUT_NOT_ALLOWED | Нельзя выполнить API-выплату самому себе. |
Готовые примеры
Код для серверной интеграции.
<?php
$shopId = 1001;
$apiKey = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
$secretKey = getenv('ADSREK_PAY_SECRET');
$orderId = 'ORDER-1001';
$amount = number_format(10, 2, '.', '');
$currency = 'RUB';
$canonical = implode('|', ['create', $shopId, $apiKey, $orderId, $amount, $currency]);
$payload = [
'shop_id' => $shopId,
'api_key' => $apiKey,
'order_id' => $orderId,
'amount' => $amount,
'currency' => $currency,
'description' => 'Оплата заказа ' . $orderId,
'sign' => hash_hmac('sha256', $canonical, $secretKey),
];
$ch = curl_init('https://adsrekpay.com/api/pay/create.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ($httpCode !== 200 || empty($data['ok'])) {
throw new RuntimeException($data['error'] ?? 'Adsrek Pay API error');
}
header('Location: ' . $data['payment_url']);
exit;
import hashlib
import hmac
import os
import requests
shop_id = 1001api_key = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
secret_key = os.environ["ADSREK_PAY_SECRET"]
order_id = "ORDER-1001"
amount = "10.00"
currency = "RUB"
canonical = f"create|{shop_id}|{api_key}|{order_id}|{amount}|{currency}"
sign = hmac.new(secret_key.encode(), canonical.encode(), hashlib.sha256).hexdigest()
payload = {
"shop_id": shop_id,
"api_key": api_key,
"order_id": order_id,
"amount": amount,
"currency": currency,
"description": f"Оплата заказа {order_id}",
"sign": sign,
}
response = requests.post("https://adsrekpay.com/api/pay/create.php", json=payload, timeout=15)
response.raise_for_status()
data = response.json()
print(data["payment_url"])
// Счёт создаётся только на вашем сервере, где хранится SECRET KEY.
const response = await fetch('/your-server/create-adsrek-invoice', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({order_id: 'ORDER-1001'})
});
const data = await response.json();
if (!data.payment_url) throw new Error('Не удалось создать счёт');
window.location.assign(data.payment_url);
Безопасность
Обязательные правила для боевой интеграции.
- SECRET KEY — только на сервере. Не вставляйте его в HTML, JavaScript, мобильное приложение или публичный репозиторий.
- Всегда используйте HTTPS. Callback на HTTP и локальные/private IP блокируются.
- Проверяйте подпись через hash_equals. Обычное сравнение строк может быть уязвимо к timing-атакам.
- Проверяйте сумму, валюту и order_id. Подписанный callback нужно сопоставить с данными заказа в вашей базе.
- Обрабатывайте повторные уведомления идемпотентно. Один счёт не должен зачисляться дважды.
- После перевыпуска ключей старые ключи сразу перестают работать. Обновляйте конфигурацию атомарно.
- Храните резервную копию config/paycore.local.php. Этот файл нужен Adsrek Pay для расшифровки SECRET KEY магазинов.
Ограничения и текущая версия
Фактические параметры Merchant API v1.
Merchant API v1. Endpoint-адреса содержат PHP-файлы и должны использоваться без изменения.
0.01 в выбранной валюте.
1.00% удерживается из суммы, поступающей владельцу магазина.
0.50% списывается дополнительно с владельца магазина.
Отдельный тестовый контур пока не предусмотрен. Для проверки используйте отдельный сайт и минимальную сумму.
Специальный тарифный rate limit в текущей версии не задан. Не отправляйте частые циклические запросы: используйте callback и разумный polling.