Справочник API Mefos Pay

API Mefos Pay позволяет интегрировать автоматический прием платежей в UAH с конвертацией в USDT на ваш сайт или в приложение.

Наш API построен на принципах REST. Он принимает JSON-запросы, возвращает JSON-ответы и использует стандартные HTTP-коды и методы.

Базовый URL: https://mefospay.cc/api/v1

Авторизация

Авторизуйте запросы, передавая ваш секретный API-ключ в заголовке X-API-Key. Ключ можно найти в Telegram-боте в разделе Настройки → API-ключ и секрет.

X-API-Key: mp_live_51Hxxxxxxxx

HMAC-подпись (Рекомендуется) Для дополнительной безопасности подписывайте запросы с помощью вашего API Secret. Добавьте заголовки X-Timestamp и X-Signature. Подпись вычисляется как HMAC_SHA256(api_secret, timestamp + "." + raw_body).

Создать платёж

Создает новый заказ и генерирует ссылку на оплату для клиента.

POST

/payments

Parameters

Название	Тип	Обязательно	Описание
`order_id`	string	Yes	Уникальный ID заказа (до 64 символов, a-z, A-Z, 0-9, -, _).
`amount`	number	Yes	Сумма в UAH, которую вы хотите получить (без учета наценки).
`currency`	string	No	Код валюты. По умолчанию `UAH`.
`description`	string	No	Описание заказа на странице оплаты.
`success_url`	string	No	URL для редиректа клиента после успешной оплаты.
`fail_url`	string	No	URL для редиректа клиента при ошибке.

Пример запроса

curl -X POST https://mefospay.cc/api/v1/payments \ -H "X-API-Key: mp_live_51Hxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "order_id": "order-10023", "amount": 1500.00, "description": "Premium Subscription" }'

Пример ответа

{ "payment_id": 123, "order_id": "order-10023", "status": "waiting", "amount": 1500.00, "client_amount": 1725.00, "payment_link": "https://mefospay.cc/site/pay/?id=123", "credentials": "5168 7521 6323 0942, Ivan I." }

Идемпотентность API идемпотентно по order_id. Если вы отправите повторный запрос с тем же order_id, API вернет существующий объект платежа вместо создания нового.

Статус платежа

Возвращает текущий статус конкретного платежа.

GET

/payments/{order_id}

Пример запроса

curl https://mefospay.cc/api/v1/payments/order-10023 \ -H "X-API-Key: mp_live_51Hxxxxxxxx"

Баланс

Возвращает ваш текущий доступный баланс в USDT.

GET

/balance

Пример ответа

{ "available": 104.50, "balance": 104.50, "reserved": 0.00 }

Выплаты

Создает запрос на вывод средств. Средства сразу резервируются и отправляются на ваш TRC-20 кошелек после подтверждения администратором.

POST

/payouts

Parameters

Название	Тип	Обязательно	Описание
`amount`	number	Yes	Сумма в USDT (минимум 2.00).
`address`	string	Yes	Валидный адрес TRC-20 кошелька.

Пример запроса

curl -X POST https://mefospay.cc/api/v1/payouts \ -H "X-API-Key: mp_live_51Hxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "amount": 10.00, "address": "TXYZabc1234567890abcdef1234567890" }'

Пример ответа

{ "payout_id": 5, "status": "pending", "amount": 10.00, "address": "TXYZabc1234567890abcdef1234567890", "created_at": "2023-10-25T15:00:00Z" }

Требуется подтверждение Все выплаты проверяются администратором перед отправкой в блокчейн. Это защищает ваш аккаунт от несанкционированного вывода.

Webhooks

Мы отправляем вебхуки на ваш сервер для уведомления об изменении статуса платежа. Укажите ваш URL в Telegram-боте в разделе Настройки → Изменить Webhook URL.

Тело события

{ "event": "payment.success", "payment_id": 123, "order_id": "order-10023", "amount": 1725.00, "commission": 225.00, "credited": 32.32, "currency": "UAH", "status": "success", "paid_at": "2023-10-25T14:30:00Z" }

Требования к ответу Ваш сервер должен вернуть код 2xx в течение 15 секунд для подтверждения получения. Если мы не получим 2xx, мы повторим отправку с экспоненциальной задержкой (1м, 5м, 15м, 1ч, 6ч).

Убедитесь, что ваш обработчик идемпотентен. Одно и то же событие может быть доставлено несколько раз.

Проверка подписи

Проверяйте заголовок X-Signature, чтобы убедиться, что вебхук отправлен от Mefos Pay. Подпись — это hex-кодированный HMAC-SHA256 от сырого тела запроса с использованием вашего API Secret.

Python

PHP

import hmac import hashlib def verify_webhook(raw_body: bytes, signature: str, api_secret: str) -> bool: expected = hmac.new( api_secret.encode(), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature)

$body = file_get_contents("php://input"); $sig = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; $expected = hash_hmac("sha256", $body, $api_secret); if (!hash_equals($expected, $sig)) { http_response_code(401); exit("Invalid signature"); }

Статусы

Статус	Описание
`pending`	Платеж создан, ожидаем выдачу реквизитов от провайдера.
`waiting`	Реквизиты выданы, ожидаем оплату от клиента.
`success`	Платеж завершен, средства зачислены на ваш баланс.
`failed`	Ошибка оплаты.
`expired`	Время оплаты истекло (15 минут).
`canceled`	Платеж отменен.

Ошибки

Код	Описание
`400`	Неверные параметры запроса (например, неверный order_id, amount ≤ 0).
`401`	Неверный API-ключ или подпись.
`403`	Аккаунт неактивен или не верифицирован.
`404`	Платеж не найден.
`429`	Превышен дневной лимит.
`502`	Провайдер платежей временно недоступен.