Документация API

1. Создание магазина

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

Скриншот создания магазина

2. Настройка магазина

Проведите настройку магазина, включите способы оплаты.

Скриншот настроек магазина

Публичный ключ - используется для формирования подписи в форме оплаты.
Секретный ключ - используется для формирования подписи в скрипте оповещения.
URL оповещения - страница Вашего сайта, на который будут отправлены данные с информацией о платеже. Метод отправки: POST.
Успешный URL - страница Вашего сайта, на которую будет перенаправлен пользователь после успешной оплаты (мы передаем параметр `label`, GET-запросом).
Неудачный URL - страница Вашего сайта, на которую будет перенаправлен пользователь в случае неудачной оплаты.

3. Настройка формы оплаты (формирование ссылки)

Пример формы оплаты на HTML (подставьте значения: номер магазина, публичный ключ):

<form method="POST" action="https://amarapay.ru/oplata/index.php">
<input type="hidden" name="shopid" value="ВАШ_НОМЕР_МАГАЗИНА">
<input type="hidden" name="pub_key" value="ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ">
<input type="text" name="label" placeholder="Номер заказа или ID пользователя" required>
<input type="text" name="summa" placeholder="Сумма" required>
<button type="submit" name="create">Оплатить</button>
</form>

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

<?php
$shop_id = 1; // ID Вашего магазина
$label = 'nickname_or_email'; // Номер заказа, логин пользователя и т.д.
$amount = 100; // Сумма платежа (от 1 до 15000 рублей)
$public_key = 'ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ'; // Публичный ключ из настроек магазина

// Формирование хеша для подписи платежа
$hash = hash('sha256', $shop_id . $amount . $public_key . $label);

$link = "https://amarapay.ru/merchant?" .
        "shop_id=" . urlencode($shop_id) .
        "&amount=" . urlencode($amount) .
        "&label=" . urlencode($label) .
        "&hash=" . urlencode($hash);

// Перенаправление пользователя на страницу оплаты
header("Location: $link");
exit(); // Важно завершить выполнение скрипта после перенаправления
?>
  • shop_id - ID Вашего магазина
  • amount - Сумма платежа (от 1 рубля до 15000 рублей)
  • label - Номер заказа (также это может быть название товара или логин пользователя, для зачисления средств)
  • public_key - Публичный ключ из настроек магазина
  • hash - Цифровая подпись системы

ВАЖНО! Для создания ссылки на оплату должна быть сгенерирована подпись, с её помощью подделать данные платежа невозможно.
Подпись шифруется методом sha256 и содержит в себе:
- ID магазина
- Сумму
- Публичный ключ
- Передаваемый параметр `label`

После создания ссылки на оплату, при переходе на неё будут доступны способы оплаты:

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

4. Оповещение о платеже на ваш сайт (серверное уведомление)

Пример обработчика POST-уведомления от AmaraPay:

<?php
// Секретный ключ из настроек вашего магазина
// НИКОГДА не выставляйте этот ключ публично!
$secret_key = 'ВАШ_СЕКРЕТНЫЙ_КЛЮЧ';

// Получаем данные из POST-запроса
$transaction_id = $_POST['id'] ?? null;      // Номер платежа в системе Amarapay
$label          = $_POST['label'] ?? null;   // Номер или название заказа в вашей системе
$payment_date   = $_POST['time'] ?? null;    // Дата и время платежа
$shop_id        = $_POST['shop_id'] ?? null; // Номер магазина в AmaraPay
$amount         = $_POST['amount'] ?? null;  // Сумма платежа
$received_hash  = $_POST['hash'] ?? null;    // Подпись (HASH sha256), полученная от AmaraPay

// Проверка наличия всех обязательных параметров
if (is_null($transaction_id) || is_null($label) || is_null($shop_id) || is_null($amount) || is_null($received_hash)) {
    die('ERROR: Missing parameters');
}

// Формирование хеша для проверки подлинности уведомления
// Обратите внимание: порядок параметров в хеше должен соответствовать спецификации AmaraPay
$check_hash = hash('sha256', $shop_id . $amount . $secret_key . $transaction_id);

// Проверка подписи
if ($received_hash !== $check_hash) {
    // Если хеши не совпадают, это может быть поддельный запрос
    // Логируйте эту ошибку для дальнейшего анализа
    error_log("Amarapay webhook: Invalid hash for transaction ID {$transaction_id}. Received: {$received_hash}, Expected: {$check_hash}");
    die('ERROR: Invalid hash');
}

// --- Оплата прошла успешно, далее ваш код обработки платежа ---
// Например, обновить статус заказа в вашей базе данных, выдать товар/услугу и т.д.
//
// Пример:
// require_once 'db_connect.php'; // Подключение к базе данных
// $stmt = $pdo->prepare("UPDATE orders SET status = 'paid', payment_id = ?, payment_date = ? WHERE label = ? AND amount = ?");
// $stmt->execute([$transaction_id, $payment_date, $label, $amount]);
//
// if ($stmt->rowCount() > 0) {
//    // Успешно обновили заказ
//    // Можно отправить уведомление пользователю
// } else {
//    // Заказ не найден или уже обновлен
//    error_log("Amarapay webhook: Could not update order for label {$label}, transaction ID {$transaction_id}");
// }

// Важно: всегда возвращать "200" для подтверждения успешного получения уведомления
die('200');
?>

Мы передаем на ваш сайт POST уведомление, в котором:

  • id - номер платежа в системе Amarapay
  • label - номер или название заказа в вашей системе
  • shop_id - номер магазина в AmaraPay
  • amount - сумма платежа
  • hash - подпись (HASH sha256)

ВАЖНО! Сервис AmaraPay передает подпись (HASH), для безопасности платежа.
Подпись шифруется методом sha256 и содержит в себе:
- ID магазина
- Сумму
- Секретный ключ
- ID транзакции AmaraPay

5. Пример подключения Telegram бота на PHP с MySQL

Этот пример покажет, как интегрировать платежи AmaraPay в вашего Telegram бота. Пользователи смогут оплачивать товары или услуги прямо через бота, а бот будет автоматически обновлять статус заказа в базе данных и уведомлять пользователя после успешной оплаты.

Предварительные требования:

  • Созданный Telegram бот через BotFather. У вас должен быть токен бота.
  • Хостинг с PHP и доступом к MySQL.
  • Установленный cURL на сервере (обычно установлен по умолчанию).
  • Магазин AmaraPay с настроенными публичным и секретным ключами, а также URL оповещения.

Структура файлов проекта:

your_bot_directory/
├── config.php                <!-- Конфигурация базы данных, токенов и ключей AmaraPay -->
├── db_connect.php            <!-- Файл для подключения к базе данных -->
├── telegram_api.php          <!-- Вспомогательные функции для работы с Telegram API -->
├── webhook.php               <!-- Основной скрипт для обработки входящих обновлений от Telegram -->
└── amarapay_webhook.php      <!-- Скрипт-обработчик уведомлений от AmaraPay об успешной оплате -->

Шаг 1: Настройка базы данных (MySQL)

Создайте следующую структуру таблиц в вашей базе данных:

CREATE TABLE `users` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `telegram_user_id` BIGINT UNIQUE NOT NULL,
    `first_name` VARCHAR(255),
    `last_name` VARCHAR(255),
    `username` VARCHAR(255),
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE `payments` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `user_id` BIGINT NOT NULL, <!-- telegram_user_id -->
    `amarapay_transaction_id` VARCHAR(255) UNIQUE NULL, <!-- ID транзакции в AmaraPay -->
    `label` VARCHAR(255) UNIQUE NOT NULL, <!-- Уникальный ID платежа в вашей системе (например, order_ID) -->
    `amount` DECIMAL(10, 2) NOT NULL,
    `currency` VARCHAR(3) DEFAULT 'RUB',
    `status` ENUM('pending', 'paid', 'failed', 'cancelled') DEFAULT 'pending',
    `payment_url` TEXT NULL, <!-- Ссылка на оплату -->
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX (`user_id`),
    INDEX (`label`),
    FOREIGN KEY (`user_id`) REFERENCES `users`(`telegram_user_id`) ON DELETE CASCADE ON UPDATE CASCADE
);

Шаг 2: Файл конфигурации (`config.php`)

Создайте файл `config.php` и заполните его вашими данными. Не забудьте указать полные URL для вебхуков!

<?php
define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASS', 'your_database_password');

define('TELEGRAM_BOT_TOKEN', 'ВАШ_ТОКЕН_ТЕЛЕГРАМ_БОТА'); // Получите его у BotFather
define('AMARAPAY_SHOP_ID', 'ВАШ_НОМЕР_МАГАЗИНА'); // ID вашего магазина AmaraPay
define('AMARAPAY_PUBLIC_KEY', 'ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ'); // Публичный ключ AmaraPay
define('AMARAPAY_SECRET_KEY', 'ВАШ_СЕКРЕТНЫЙ_КЛЮЧ'); // Секретный ключ AmaraPay

// Полный URL до файла webhook.php на вашем сервере
define('TELEGRAM_WEBHOOK_URL', 'https://ваш-домен.ru/your_bot_directory/webhook.php');

// Полный URL до файла amarapay_webhook.php на вашем сервере
// Этот URL нужно будет указать в настройках магазина AmaraPay как "URL оповещения"
define('AMARAPAY_NOTIFICATION_URL', 'https://ваш-домен.ru/your_bot_directory/amarapay_webhook.php');

// URL страницы успешной оплаты (куда перенаправит AmaraPay)
define('AMARAPAY_SUCCESS_URL', 'https://ваш-домен.ru/success_payment.php');

// URL страницы неудачной оплаты
define('AMARAPAY_FAIL_URL', 'https://ваш-домен.ru/fail_payment.php');

// Базовый URL AmaraPay для формирования ссылок на оплату
define('AMARAPAY_MERCHANT_URL', 'https://amarapay.ru/merchant');
?>

Шаг 3: Подключение к базе данных (`db_connect.php`)

<?php
require_once 'config.php';

try {
    $pdo = new PDO(
        "mysql:host=" . DB_HOST . ";dbname=" . DB_NAME . ";charset=utf8mb4",
        DB_USER,
        DB_PASS,
        [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES   => false,
        ]
    );
} catch (PDOException $e) {
    die("Ошибка подключения к базе данных: " . $e->getMessage());
}
?>

Шаг 4: Вспомогательные функции Telegram API (`telegram_api.php`)

<?php
require_once 'config.php';

function telegram_api_request(string $method, array $params = []): array
{
    $url = "https://api.telegram.org/bot" . TELEGRAM_BOT_TOKEN . "/" . $method;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error) {
        error_log("Telegram API error ({$method}): " . $error);
        return ['ok' => false, 'description' => $error];
    }
    return json_decode($response, true);
}

function send_telegram_message(int $chat_id, string $text, array $reply_markup = []): array
{
    $params = [
        'chat_id' => $chat_id,
        'text' => $text,
        'parse_mode' => 'HTML',
    ];
    if (!empty($reply_markup)) {
        $params['reply_markup'] = json_encode($reply_markup);
    }
    return telegram_api_request('sendMessage', $params);
}

function set_telegram_webhook(string $url): array
{
    return telegram_api_request('setWebhook', ['url' => $url]);
}
?>

Шаг 5: Основной обработчик бота (`webhook.php`)

Этот скрипт будет получать все обновления от Telegram. Его нужно будет установить как вебхук для вашего бота.

<?php
require_once 'config.php';
require_once 'db_connect.php';
require_once 'telegram_api.php';

// Получаем входящие данные от Telegram
$update = json_decode(file_get_contents('php://input'), true);

if (!$update) {
    // Если нет данных, просто выходим
    exit('No update data.');
}

// Извлекаем информацию о сообщении
$message = $update['message'] ?? null;
if (!$message) {
    exit('No message data.');
}

$chat_id = $message['chat']['id'];
$user_id = $message['from']['id'];
$text = $message['text'] ?? '';
$first_name = $message['from']['first_name'] ?? '';
$last_name = $message['from']['last_name'] ?? '';
$username = $message['from']['username'] ?? '';

// Логирование для отладки
error_log("Received message from {$user_id} in chat {$chat_id}: {$text}");

// Сохраняем/обновляем пользователя в БД
$stmt = $pdo->prepare("INSERT INTO users (telegram_user_id, first_name, last_name, username) VALUES (?, ?, ?, ?) ON DUPLICATE KEY UPDATE first_name = VALUES(first_name), last_name = VALUES(last_name), username = VALUES(username)");
$stmt->execute([$user_id, $first_name, $last_name, $username]);

// Обработка команд
switch ($text) {
    case '/start':
        send_telegram_message($chat_id, "Привет, {$first_name}! Я бот для приема платежей через AmaraPay. Используйте /pay, чтобы совершить тестовый платеж.");
        break;

    case '/pay':
        // Пример: создаем новый платеж на 100 рублей
        $amount = 100.00;
        $order_label = 'order_' . $user_id . '_' . time(); // Уникальный ID заказа/платежа

        // Сохраняем информацию о платеже в БД со статусом 'pending'
        $stmt = $pdo->prepare("INSERT INTO payments (user_id, label, amount, status) VALUES (?, ?, ?, 'pending')");
        $stmt->execute([$user_id, $order_label, $amount]);

        // Формирование хеша для подписи платежа
        $hash = hash('sha256', AMARAPAY_SHOP_ID . $amount . AMARAPAY_PUBLIC_KEY . $order_label);

        // Формирование ссылки на оплату AmaraPay
        $payment_link = AMARAPAY_MERCHANT_URL .
            "?shop_id=" . urlencode(AMARAPAY_SHOP_ID) .
            "&amount=" . urlencode($amount) .
            "&label=" . urlencode($order_label) .
            "&hash=" . urlencode($hash) .
            "&success_url=" . urlencode(AMARAPAY_SUCCESS_URL) . // Опционально
            "&fail_url=" . urlencode(AMARAPAY_FAIL_URL); // Опционально

        // Обновляем payment_url в БД
        $stmt = $pdo->prepare("UPDATE payments SET payment_url = ? WHERE label = ?");
        $stmt->execute([$payment_link, $order_label]);

        // Отправляем ссылку пользователю
        $keyboard = [
            'inline_keyboard' => [
                [['text' => "Оплатить {$amount} RUB", 'url' => $payment_link]]
            ]
        ];
        send_telegram_message($chat_id, "Для оплаты {$amount} RUB используйте ссылку ниже:", $keyboard);
        break;

    default:
        send_telegram_message($chat_id, "Неизвестная команда. Попробуйте /start или /pay.");
        break;
}

// Установка вебхука (выполнить один раз, например, вручную или при первом запуске)
// Можно закомментировать после первой успешной установки
// $webhook_status = set_telegram_webhook(TELEGRAM_WEBHOOK_URL);
// if ($webhook_status['ok']) {
//     error_log("Webhook установлен успешно: " . TELEGRAM_WEBHOOK_URL);
// } else {
//     error_log("Ошибка установки вебхука: " . ($webhook_status['description'] ?? 'Неизвестная ошибка'));
// }

?>

Шаг 6: Обработчик уведомлений AmaraPay (`amarapay_webhook.php`)

Этот скрипт будет получать POST-уведомления от AmaraPay после успешной оплаты. Убедитесь, что вы указали `AMARAPAY_NOTIFICATION_URL` в настройках своего магазина AmaraPay.

<?php
require_once 'config.php';
require_once 'db_connect.php';
require_once 'telegram_api.php';

// Логируем все входящие POST-данные для отладки
error_log("Amarapay webhook received POST: " . print_r($_POST, true));

// Секретный ключ из настроек вашего магазина
$secret_key = AMARAPAY_SECRET_KEY;

// Получаем данные из POST-запроса
$transaction_id = $_POST['id'] ?? null;      // Номер платежа в системе Amarapay
$label          = $_POST['label'] ?? null;   // Номер или название заказа в вашей системе (у нас это order_label)
$payment_date   = $_POST['time'] ?? null;    // Дата и время платежа
$shop_id        = $_POST['shop_id'] ?? null; // Номер магазина в AmaraPay
$amount         = $_POST['amount'] ?? null;  // Сумма платежа
$received_hash  = $_POST['hash'] ?? null;    // Подпись (HASH sha256), полученная от AmaraPay

// Проверка наличия всех обязательных параметров
if (is_null($transaction_id) || is_null($label) || is_null($shop_id) || is_null($amount) || is_null($received_hash)) {
    error_log("Amarapay webhook ERROR: Missing parameters. POST: " . print_r($_POST, true));
    die('ERROR: Missing parameters');
}

// Проверка, соответствует ли ID магазина нашему
if ($shop_id != AMARAPAY_SHOP_ID) {
    error_log("Amarapay webhook ERROR: Shop ID mismatch. Received: {$shop_id}, Expected: " . AMARAPAY_SHOP_ID);
    die('ERROR: Shop ID mismatch');
}

// Формирование хеша для проверки подлинности уведомления
$check_hash = hash('sha256', $shop_id . $amount . $secret_key . $transaction_id);

// Проверка подписи
if ($received_hash !== $check_hash) {
    error_log("Amarapay webhook ERROR: Invalid hash for transaction ID {$transaction_id}. Received: {$received_hash}, Expected: {$check_hash}");
    die('ERROR: Invalid hash');
}

// --- Оплата прошла успешно, далее ваш код обработки платежа ---
try {
    // Находим платеж по label и обновляем его статус
    $stmt = $pdo->prepare("SELECT user_id, amount FROM payments WHERE label = ? AND status = 'pending'");
    $stmt->execute([$label]);
    $payment = $stmt->fetch();

    if ($payment) {
        // Проверяем, совпадает ли сумма
        if ((float)$payment['amount'] !== (float)$amount) {
            error_log("Amarapay webhook ERROR: Amount mismatch for label {$label}. DB: {$payment['amount']}, Received: {$amount}");
            die('ERROR: Amount mismatch');
        }

        $stmt = $pdo->prepare("UPDATE payments SET status = 'paid', amarapay_transaction_id = ?, updated_at = NOW() WHERE label = ? AND status = 'pending'");
        $stmt->execute([$transaction_id, $label]);

        if ($stmt->rowCount() > 0) {
            // Платеж успешно обновлен
            $user_id = $payment['user_id'];
            send_telegram_message($user_id, "✅ Ваш платеж на сумму {$amount} RUB успешно принят! Номер заказа: {$label}. ID транзакции: {$transaction_id}.");
            error_log("Amarapay webhook SUCCESS: Payment for label {$label}, transaction ID {$transaction_id} processed.");
        } else {
            // Платеж уже был обработан или не найден в статусе 'pending'
            error_log("Amarapay webhook INFO: Payment for label {$label}, transaction ID {$transaction_id} already processed or not pending.");
        }
    } else {
        // Платеж с таким label не найден в статусе 'pending'
        error_log("Amarapay webhook ERROR: Payment with label {$label} not found or not in pending status.");
        die('ERROR: Payment not found or already processed');
    }
} catch (PDOException $e) {
    error_log("Amarapay webhook DB ERROR: " . $e->getMessage());
    die('ERROR: Database error');
}

// Важно: всегда возвращать "200" для подтверждения успешного получения уведомления
die('200');
?>

Шаг 7: Установка Telegram вебхука

После того как вы загрузили все файлы на сервер и настроили `config.php`, вам нужно один раз установить вебхук для вашего Telegram бота, чтобы он знал, куда отправлять обновления.

Вы можете либо раскомментировать и запустить часть кода в `webhook.php` для установки вебхука, либо сделать это вручную, отправив GET-запрос в браузере или через cURL: 

https://api.telegram.org/botВАШ_ТОКЕН_ТЕЛЕГРАМ_БОТА/setWebhook?url=https://ваш-домен.ru/your_bot_directory/webhook.php

Вы должны получить ответ `{"ok":true,"result":true,"description":"Webhook was set"}`.

Шаг 8: Настройка URL оповещения в AmaraPay

Зайдите в настройки вашего магазина AmaraPay и укажите `https://ваш-домен.ru/your_bot_directory/amarapay_webhook.php` (значение `AMARAPAY_NOTIFICATION_URL` из `config.php`) в поле "URL оповещения".

Готово!

Теперь ваш Telegram бот готов принимать платежи через AmaraPay. Пользователи могут инициировать платеж, получать ссылку, а бот будет автоматически обновлять их статус после успешной оплаты.

Начните принимать платежи уже сегодня