Введение
Для начала приема платежей необходимо:
- Зарегистрировать сайт в личном кабинете.
- Подтвердить право владения доменом через размещение TXT-файла в корне вашего сайта.
- Успешно пройти ручную проверку сайта на соответствие требованиям Мегакассы (1-3 дня).
После успешной активации вашего сайта, вы сможете разместить кнопку на сайте для оплаты через Мегакассу.
Внешний вид кнопки вы формируете самостоятельно, исходя из дизайна вашего сайта.
Варианты интеграции с Мегакассой
В Мегакассе предусмотрено 2 варианта интеграции:
- Оплата через платежную форму Мегакассы
- Моментальный редирект на форму оплаты выбранной платежной системы
Для работы по 1-ому варианту достаточно указать только обязательные поля.
Для 2-ого же варианта, также необходимо указать поля method_id и client_email.
Нужно иметь ввиду, Мегакасса не допускает указания, например, поля client_email и пустое поле method_id.
Либо оба поля пустые, либо оба корректно заполнены.
Форма приёма платежей
Вы можете сформировать прямую ссылку или HTML-форму методом GET или POST на URL https://megakassa.ru/merchant/, на который также необходимо будет передать несколько параметров:
<?php
$shop_id = '1';
$amount = number_format(100.5, 2, '.', ''); // -> "100.50"
$currency = 'RUB'; // или "USD", "EUR"
$description = 'iPhone 8 plus 32 Gb';
$order_id = 123456;
$method_id = '';
$client_email = '';
$debug = ''; // или "1"
$secret_key = '0123456789abcdef'; // из настроек сайта в ЛК
$signature = md5($secret_key.md5(join(':', array(
$shop_id,$amount, $currency, $description,
$order_id, $method_id, $client_email,
$debug, $secret_key
))));
$language = 'ru'; // или 'en'
?>
<form method="post" action="https://megakassa.ru/merchant/" accept-charset="UTF-8">
<input type="hidden" name="shop_id" value="<?=$shop_id;?>" />
<input type="hidden" name="amount" value="<?=$amount;?>" />
<input type="hidden" name="currency" value="<?=$currency;?>" />
<input type="hidden" name="description"
value="<?=htmlentities($description, ENT_QUOTES, 'UTF-8');?>" />
<input type="hidden" name="order_id" value="<?=$order_id;?>" />
<input type="hidden" name="method_id" value="<?=$method_id;?>" />
<input type="hidden" name="client_email" value="<?=$client_email;?>" />
<input type="hidden" name="debug" value="<?=$debug;?>" />
<input type="hidden" name="signature" value="<?=$signature;?>" />
<input type="hidden" name="language" value="<?=$language;?>" />
<input type="submit" value="Купить" />
</form>
В настроящее время доступны следующие валюты: RUB, USD, EUR. Обязательный параметр
Максимальная длина 255 символов. Обязательный параметр
Максимальная длина 8 символов. Обязательный параметр
где $secret_key - секретный ключ, ранее полученный вами при добавлении вашего сайта. Вы всегда сможете увидеть его в настойках вашего сайта, там же, в случае необходимости, сможете и изменить его. Если параметр debug не передан, он будет считаться равным пустой строке "". Обязательный параметр
Возможные значения: ru, en. Опциональный параметр
Если параметр method_id не передан, то при формировании сигнатуры он будет считаться равным пустой строке "".
Посмотреть список соответствий ID для доступных методов оплаты. Опциональный параметр, обязательный при использовании client_email
Если параметр client_email не передан, то при формировании сигнатуры он будет считаться равным пустой строке "". Опциональный параметр, обязательный при использовании method_id
Это параметр обязателен только в случае использования 2-ого варианта интеграции, и только для Qiwi Wallet. Опциональный параметр, обязательный при использовании method_id, client_email для QIWI.
Могут использоваться по своему усмотрению. Вернется в уведомлении об успешной оплате.
Внимание! доп. параметры не защищены сигнатурой, поэтому крайне не рекомендуем использовать их в критичных участах ваших скриптов, они могут быть подделаны злоумышленниками.
Причем, если будет корректно передан необязательный параметр method_id, то пользователь сразу будет перенаправлен на выбранный метод оплаты, минуя форму подтверждения Мегакассы.
Список ID методов оплаты Мегакассы
Получение уведомлений об успешной оплате
<?php
// проверка IP-адреса
$ip_checked = false;
foreach(array(
'HTTP_X_CLUSTER_CLIENT_IP',
'HTTP_X_FORWARDED_FOR',
'HTTP_X_FORWARDED',
'HTTP_FORWARDED_FOR',
'HTTP_FORWARDED',
'HTTP_CLIENT_IP',
'REMOTE_ADDR'
) as $param) {
if(!empty($_SERVER[$param]) &&
$_SERVER[$param] === '5.196.121.217') {
$ip_checked = true;
break;
}
}
if(!$ip_checked) {
die('error');
}
// проверка на наличие обязательных полей
// поля $payment_time и $debug могут дать true для empty()
// поэтому их нет в проверке
foreach(array(
'uid',
'amount',
'amount_shop',
'amount_client',
'currency',
'order_id',
'payment_method_title',
'creation_time',
'client_email',
'status',
'signature'
) as $field) {
if(empty($_REQUEST[$field])) {
die('error');
}
}
// ваш секретный ключ
$secret_key = '0123456789abcdef';
// нормализация данных
$uid = (int)$_REQUEST["uid"];
$amount = (double)$_REQUEST["amount"];
$amount_shop = (double)$_REQUEST["amount_shop"];
$amount_client = (double)$_REQUEST["amount_client"];
$currency = $_REQUEST["currency"];
$order_id = $_REQUEST["order_id"];
$payment_method_id = (int)$_REQUEST["payment_method_id"];
$payment_method_title = $_REQUEST["payment_method_title"];
$creation_time = $_REQUEST["creation_time"];
$payment_time = $_REQUEST["payment_time"];
$client_email = $_REQUEST["client_email"];
$status = $_REQUEST["status"];
$debug = (!empty($_REQUEST["debug"])) ? '1' : '0';
$signature = $_REQUEST["signature"];
// проверка валюты
if(!in_array($currency, array('RUB', 'USD', 'EUR'), true)) {
die('error');
}
// проверка статуса платежа
if(!in_array($status, array('success', 'fail'), true)) {
die('error');
}
// проверка формата сигнатуры
if(!preg_match('/^[0-9a-f]{32}$/', $signature)) {
die('error');
}
// проверка значения сигнатуры
$signature_calc = md5(join(':', array(
$uid, $amount, $amount_shop, $amount_client, $currency,
$order_id, $payment_method_id, $payment_method_title,
$creation_time, $payment_time, $client_email, $status,
$debug, $secret_key
)));
if($signature_calc !== $signature) {
die('error');
}
// Опциональная проверка на запрет тестового платежа
if(!empty($debug)){
die('debug');
}
// далее ваши проверки:
// - на наличие платежа в вашей БД по $order_id
// - на соответствии суммы и валюты платежа в вашей БД
// ...
// обработка платежа
switch($status) {
case 'success':
// время соверешния платежа в Unix timestamp (если нужно)
$payment_time_ts = strtotime($payment_time);
// ваш код при успешной оплате
// ...
break;
case 'fail':
// ваш код при отмене или истечении платежа
// ...
break;
}
// успешный ответ для Мегакассы и завершение скрипта
die('ok');
?>
Сразу после того как пользователь вашего сайта произведет успешную оплату или отменит её, на URL обработчика вашего сайта придет HTTP-уведомление методом POST.
Причем запрос будет производиться между сервером Мегакассы и вашим сайтом, то есть без участия пользователя.
POST состоит из:
В настроящее время доступны следующие валюты: RUB, USD, EUR. string
Максимальная длина 255 символов. string
Уведомление будет считаться успешно обработанным, если Мегакасса со стороны магазина в течение 30 сек. получит ответ с содержанием "ok" в любом регистре. Если содержание ответа будет отличаться от "ok" или же ответ не может быть получен вовремя, то через каждые 10 мин Мегакасса будет отправлять уведомление повторно 6 раз, потом каждые 60 мин в течении 24 часа.
Следует проверять правильность подписи (signature), соответствие суммы платежа (amount) и стоимости заказа в вашей базе данных, IP нашего сервера отправляющего Вам информацию: 5.196.121.217
Возврат пользователя в ваш магазин
После того как оплата будет успешно совершена (или отменена) пользователь вашего магазина окажется на странице Мегакассы, на которой отражен результат выполнения платежа. Далее, пользователь будет перенаправлен на страницу URL успешной оплаты, в случае выполнения платежа, или на URL неуспешной оплаты, в случае, например, отмены платежа пользователем или нехватки денежных средств на его кошельке.
Нужно иметь ввиду, что Мегакасса передает для обоих URL-адресов order_id(если вам надо, требует включения в настройках магазина). Однозначным критерием успешного или неуспешного платежа может являться только вызов URL обработчика со стороны Мегакассы. Связано это с тем, что некоторые платежные системы не могут моментально произвести оплату, и, соответственно, оповестить об этом Мегакассу. Или же сообщают о предварительном успехе, а позже, по различным причинам, оплата может быть отменена.
Готовый класс API с примерами на PHP
Вы можете скачать по ссылке:
https://megakassa.ru/cms_modules/Megakassa_base_module.rar
Выплаты
Начало работы с API
Для начала работы, в настройках Мегакассы вашего сайта необходимо включить API выплат. Чтобы это сделать, нужно зайти в "Настройки" вашего сайта, перейти во вкладку "API Выплат" и нажать на переключатель "Включить API". Вам сразу же автоматически сформируется случайный "Секретный ключ". Он нужен для формирования всех запросов к API.
Вы можете в любое время сменить секретный ключ нажатием на кнопку "Сменить секретный ключ". Имейте ввиду, если у вас API уже настроено, то после смены ключа все текущие запросы перестанут работать.
Создание заявки на проведение выплаты занимает некоторое время, поэтому для того чтобы убедиться, что выплата прошла успешно необходимо через некоторое время запросить статус выплаты через метод «[4] Получение информации о выплате».
Внимание! Никому не сообщайте секретный ключ для API.
Общее описание запроса
Каждый запрос к API Выплат производится через HTTPS-протокол по адресу: https://api.megakassa.ru/vX.X/, где X.X - номер версии API. На текущий момент рабочей версией является 1.0.
Параметры запроса передаются GET-методом в строке URL-запроса. Для каждого запроса необходимо передавать параметры shop_id и sign, которые обеспечивают авторизацию вашего сайта. В зависимости от запроса, могут быть и другие параметры. Все параметры обязательны. Подробнее смотрите ниже.
В настройках Личного Кабинета Мегакассы Вы определяете:
- возможность использования API Выплат (вкл / выкл)
- секретный ключ доступа к API (MD5-хеш)
- IP-адрес, с которого доступно взаимодействие с API (опционально)
Общее описание ответа
{
status: "ok",
data: {
…
}
}
{
status: "error",
data: {
code: 100,
message: "Описание ошибки",
datails: null
}
}
Ответ на любой URL-запрос к API приходит в JSON-формате.
Список параметров ответа:
Параметр | Тип | Описание |
status | String | Статус ответа. Доступен всегда. Бывает только 2 вариантов: “ok” - успешное выполнение “error” - в случае возникновения ошибки |
data | Object | Объект с данными, содержание которого зависит от статуса ответа и метода запроса |
data.code | Integer | Код ошибки. Только для status = “error”. Список кодов ошибок смотрите ниже |
data.message | String | Текст описания ошибки. Только для status = “error” |
data.details | Object | null | Детальные данные по ошибке, если есть. Только для status = “error” |
Описание формирования хеш-строки сигнатуры
<?php
// параметры GET-запроса
$params['currency_from'] = 'RUB';
$params['shop_id'] = 12345;
$params['amount'] = 120.50;
$params['debug'] = 0;
$params['wallet'] = '41001912345678';
$params['method_id'] = 71; // Список методов см. Получение доступных платежных систем
$params['order_id'] = 12345;
$params['comment'] = '';
// секретный ключ из настроек сайта, раздел API Выплат
$secret_key = '68f2b4aec9d5210dbb24a62a9b5df3a1';
// упорядочиваем параметры по ключам и получаем массив значений
ksort($params);
$values = array_values($params);
// добавляем секретный ключ в конец массива значений
$values[] = $secret_key;
// формируем строку сигнатуры
$sign = md5(join(':', $values));
// добавляем в массив параметров
$params['sign'] = $sign;
// Название метода
$method_name = 'withdraw_create';
// URL-адрес для запроса к API
$url = 'https://api.megakassa.ru/v1.0/'.$method_name.'?'.http_build_query($params);;
// пример реализации запроса через библиотеку cURL
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
if(empty($response) || curl_getinfo($ch, CURLINFO_HTTP_CODE) != 200) {
echo 'Произошла ошибка с соединением';
die();
}
// получаем JSON-объект
$json = @json_decode($response);
if(empty($json->status)) {
echo 'Произошла ошибка с ответом от API';
die();
}
// проверка статуса ответа
switch($json->status) {
case 'error':
echo 'Произошла ошибка, код '.$json->data->code.': '.$json->data->message;
die();
case 'ok':
// запрос выполнен успешно
// ...
// ...
break;
default:
echo 'Получен неизвестный статус от API';
die();
}
?>
Сигнатура проверки подлинности представляет собой MD5-хеш, который передаётся в GET-параметре sign в запросе к API.
Формируется следующим образом:
- Берутся все GET-параметры (без самого sign) в виде списка
- Сортируются по названию в алфавитном порядке
- В конец списка добавляется секретный ключ
- Получаем строку путем конкатенации через символ двоеточия “:” между значениями! параметров
- Получаем MD5-хеш из конкатенированной строки
Доступные методы выплат через api
ID | Платежная система | Минимальная сумма вывода |
61 | Visa, MasterCard, Maestro | 300 RUB |
71 | Yandex Money | 2 RUB |
74 | Qiwi Wallet | 2 RUB |
81 | MTS, Beeline, Tele2, Megafon | 2 RUB |
[1] Получение доступных платежных систем
{
status: "ok",
data: {
payment_methods_list: [
{id: 61, title: "Visa, MasterCard, Maestro", currency: "RUB", minimal: 500},
{id: 71, title: "Yandex Money", currency: "RUB", minimal: 2},
{id: 74, title: "Qiwi Wallet", currency: "RUB", minimal: 8
...
{id: 81, title: "MTS, Beeline, Tele2, Megafon", currency: "RUB", minimal: 2}
]
}
}
Метод позволяет получить список всех доступных платежных систем для вашего сайта.
Используется как справочник для построения запроса на проведение выплаты.
HTTP GET: https://api.megakassa.ru/v1.0/payment_methods_list/?shop_id=X&sign=XXX
Параметры запроса:
Параметр | Тип | Описание |
shop_id | Integer | ID вашего сайта |
sign | String | Хеш-строка сигнатуры доступа |
[2] Проверка баланса сайта
{
status: "ok",
data: {
total_balance_in_rub: 9842.58,
currencies_list: [
{uid: "RUR", balance: 1000.00, balance_in_rub: 1000.00},
{uid: "USD", balance: 123.5, balance_in_rub: 7657.12},
{uid: "EUR", balance: 15.8, balance_in_rub: 1185.46},
]
}
}
Метод позволяет узнать текущий баланс по всем доступным валютам.
Также для каждой валюты доступно значение конвертированное в рубли по текущему курсу обмена и итоговый баланс в рублях.
HTTP GET: https://api.megakassa.ru/v1.0/shop_balance/?shop_id=X&sign=XXX
Параметры запроса:
Параметр | Тип | Описание |
shop_id | Integer | ID вашего сайта |
sign | String | Хеш-строка сигнатуры доступа |
Рекомендуем опрашивать не чаще чем 1 раз в минуту, так как ответ запроса кэшируется.
[3] Создание заявки на проведение выплаты
{
status: "ok",
data: {
withdraw_id: 12345,
amount: 1000.00,
amount_due: 990.0,
payment_method_id: 74,
order_id: 54321,
wallet: "1234567890",
debug: 0,
}
}
Метод позволяет создавать заявку на выплату по доступным платежным системам.
Есть возможность указания как суммы к оплате, так и суммы к получению.
Параметры запроса:
Параметр | Тип | Описание |
shop_id | Integer | ID вашего сайта |
method_id | Integer | ID платежной системы и валюты |
amount * | Float | Сумма к оплате (столько заплатит отправитель) |
amount_due * | Float | Сумма к получению (придет на счет получателя после оплаты) |
currency_from | String | Валюта вывода из Мегакассы (RUB, USD, EUR) |
wallet | String | Номер карты или кошелька получателя |
debug | Integer | Флаг тестовой выплаты ("1" - тестовая, "0" - рабочая). Если не передать параметр, то выплата считается рабочая. |
comment | String | Комментарий, до 50 символов |
order_id | Integer | Уникальный ID выплаты на вашем сайте |
sign | String | Хеш-строка сигнатуры доступа |
* Допускается только указывать либо amount, либо amount_due. Попытка указать оба параметра приведет к ошибке.
[4] Получение информации о выплате
{
status: "ok",
data: {
withdraw: {
id: 12345,
api_mode: true,
status: {
id: 5,
title: "Success"
},
amount: 1000.00,
amount_due: 990.0,
payment_method_id: 74,
order_id: 54321,
wallet: "1234567890",
debug: 0,
comment: "Pay for goods",
creation_time: "2017-05-09T10:00:00+03:00",
updated_time: "2017-05-09T10:05:12+03:00"
}
}
}
Метод позволяет получить подробные данные по вашим выплатам.
Например, статус выплаты, время создания и выполнения заявки.
HTTP GET: https://api.megakassa.ru/v1.0/get_withdraw/?shop_id=X&withdraw_id=X&sign=XXX
или
HTTP GET: https://api.megakassa.ru/v1.0/get_withdraw/?shop_id=X&order_id=X&sign=XXX
Параметры запроса:
Параметр | Тип | Описание |
shop_id | Integer | ID вашего сайта |
withdraw_id | Integer | ID выплаты в системе Мегакасса |
order_id | Integer | ID выплаты на вашем сайте |
sign | String | Хеш-строка сигнатуры доступа |
* Допускается только указывать либо withdraw_id, либо order_id. Попытка указать оба параметра приведет к ошибке.
Рекомендуем опрашивать не чаще чем 1 раз в минуту, так как ответ запроса кэшируется.
[5] Получение истории по выплатам
{
status: "ok",
data: {
withdraws_count: 200,
withdraws_list: [{
id: 12345,
api_mode: true,
status: {
id: 5,
title: "Success"
},
amount: 1000.00,
amount_due: 990.0,
payment_method_id: 74,
order_id: 54321,
wallet: "1234567890",
debug: 0,
comment: "Pay for goods",
creation_time: "2017-05-09T10:00:00+03:00",
updated_time: "2017-05-09T10:05:12+03:00"
}, {
...
},
...
]
}
}
Метод возвращает список всех выплат в архиве для вашего сайта.
Для одного запроса одновременно отдаются выплаты по 50 штук, доступен постраничный переход через параметр page.
HTTP GET: https://api.megakassa.ru/v1.0/withdraws_list/?shop_id=X&page=0&sign=XXX
Параметры запроса:
Параметр | Тип | Описание |
shop_id | Integer | ID вашего сайта |
page | Integer | Номер страницы (для первой страницы нужно передать значение "0") |
sign | String | Хеш-строка сигнатуры доступа |
Рекомендуем опрашивать не чаще чем 1 раз в минуту, так как ответ запроса кэшируется.
Список статусов
Статус | Описание |
Confirmed | Запрос подтвержден, находится в очереди на исполнение |
Processing | Запрос на этапе исполнения, идет перевод |
Success | Запрос успешно выполнен, перевод завершен |
Error | Во время перевода произошла ошибка |
Debug | Тестовый запрос |
Список ошибок
Код ошибки | Описание ошибки |
0 | Метод не определен |
1 | Не все обязательные поля были заполнены |
2 | Параметр shop_id был передан некорректно |
3 | Параметр sign был передан некорректно |
4 | Сайт не найден |
5 | API Выплат для сайта выключен |
6 | API Выплат для сайта недоступен по текущему IP-адресу |
7 | Секретный ключ некорректен. |
8 | Параметр sign не соответствует сигнатуре доступа |
9 | Ведутся технические работы, попробуйте позже |
101 | Список платежных систем не доступен |
201 | Список валют для сайта не определен или не доступен |
301 | Необходимо указать только один параметр, либо amount либо amount_due, но не оба сразу |
302 | Параметр method_id был передан некорректно |
303 | Параметр amount был передан некорректно |
304 | Параметр currency_from был передан некорректно |
305 | Параметр wallet был передан некорректно |
306 | Платежная система не определена |
307 | Выбранная валюта не доступна для сайта |
308 | Сумма вывода превышает баланс вашего сайта |
309 | Сумма вывода меньше минимальной для данной платежной системы |
310 | Сумма вывода превышает разовую максимальную сумму вывода для данной платежной системы |
311 | Сумма вывода превышает сумму доступную для вывода. Вероятно, ранее другие пользователи Мегакассы вывели требуемую вами сумму. Попробуйте позже. |
312 | Превышен суточный лимит. |
313 | Превышен месячный лимит на один кошелек или номер карты. |
314 | Вывод с данным order_id уже существует. |
315 | Параметр order_id не был передан. |
401 | Параметр withdraw_id был передан некорректно |
402 | Выплата не найдена |
403 | Выплата не принадлежит вашему сайту |
501 | Параметр page был передан некорректно |
502 | Список выводов пуст |
Готовый класс API с примерами на PHP
Вы можете скачать по ссылке:
https://megakassa.ru/files/API_Megakassa.zip.
Если Вы заметили ошибку, сообщите нам, мы ее обязательно исправим.