Введение

Для начала приема платежей необходимо:

1. Зарегистрировать сайт в личном кабинете.
2. Подтвердить право владения доменом через размещение TXT-файла в корне вашего сайта.
3. Успешно пройти ручную проверку сайта на соответствие требованиям Мегакассы (1-3 дня).

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

Варианты интеграции с Мегакассой

В Мегакассе предусмотрено 2 варианта интеграции:

1. Оплата через платежную форму Мегакассы
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>

Причем, если будет корректно передан необязательный параметр 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 состоит из:

Уведомление будет считаться успешно обработанным, если Мегакасса со стороны магазина в течение 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, которые обеспечивают авторизацию вашего сайта. В зависимости от запроса, могут быть и другие параметры. Все параметры обязательны. Подробнее смотрите ниже.

В настройках Личного Кабинета Мегакассы Вы определяете:

1. возможность использования API Выплат (вкл / выкл)
2. секретный ключ доступа к API (MD5-хеш)
3. 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.
Формируется следующим образом:

1. Берутся все GET-параметры (без самого sign) в виде списка
2. Сортируются по названию в алфавитном порядке
3. В конец списка добавляется секретный ключ
4. Получаем строку путем конкатенации через символ двоеточия “:” между значениями! параметров
5. Получаем 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,
    }
}

Метод позволяет создавать заявку на выплату по доступным платежным системам.
Есть возможность указания как суммы к оплате, так и суммы к получению.

HTTP GET: https://api.megakassa.ru/v1.0/withdraw_create/?shop_id=X&method_id=X&amount=X&order_id=X&currency_from=RUR&wallet=X&comment=X&sign=XXX

Параметры запроса:

Параметр	Тип	Описание
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.

 

Если Вы заметили ошибку, сообщите нам, мы ее обязательно исправим.