You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 32 Next »

Общая информация

Обращение к методам API IntellectMoney осуществляется через прикладывание к запросам Bearer-токена либо SSL-сертификата. Чтобы получить их, нужно отправить заявку в личном кабинете и дождаться ее подтверждения менеджером. Проверить работоспособность доступа можно на тестовом API, см. примеры. Доступ к API необходимо подтверждать с периодичность раз в год.

Уровни доступа

Базовый уровень доступа

Минимальный уровень доступа. С ним возможно вызывать только методы API, не требующие передачу данных держателей карт (номер карты, срок действия и т.д.). Этот уровень выставляется по умолчанию при создании заявки на доступ.

Доступ уровня PCI DSS

Необходим для доступа к методам API, в которые передаются данные держателей карт. Доступ требует подтверждения Вашего уровня соответствия стандарту PCI DSS.

Доступ уровня PCI DSS обязателен для следующих методов API

APIМетоды
Merchant API

BankCardPayment

GetBankCardPaymentState

ActivationPay

PeerToPeer (P2P) API

PayByCard

Payout API

CreateBankCardRussiaOperation

Создание заявки на доступ

Заявка на доступ создается в личном кабинете (пункт меню "Запросы доступов" в разделе "Настройки") пользователя кошелька или интернет-магазина.

В случае если Вам требуется доступ уровня PCI DSS, поставьте галочку "Требуется доступ уровня PCI DSS", загрузите сертификат SAQ и отчет об ASV сканировании, и укажите сроки их действия. Можно прикреплять изображения и файлы в формате pdf, docx.


Результат обработки заявки на доступ будет отправлен на почту, указанную при регистрации кошелька или интернет-магазина. В случае отклонения заявки на доступ, Вы можете подать ее повторно, приложив актуальные документы.

Получение Bearer токена и SSL-сертификата

В случае успешной обработки заявки на доступ Вы получите письмо с темой "Ваш доступ к API активирован".

Задайте пароль и скачайте сертификат из личного кабинета (пункт меню "Запросы доступов" в разделе "Настройки"). Безопасный пароль должен иметь длину от 7 до 20 символов, состоять из букв латинского алфавита (минимум одна буква в верхнем и нижнем регистре), цифр и хотя бы одного символа (@, $, !, %, *, ?, &). Сертификат скачивается в формате PFX. Вы можете проверить работоспособность Вашего доступа на тестовом API, см. примеры.

Токен и секретный ключ отображаются по нажатию кнопки "Показать". В целях безопасности токен и ключ можно просмотреть только один раз. В случае утери токена или ключа нужно запросить новые, используя форму "Перезапрос доступа". Старые токен и ключ при этом перестанут работать.


Внимание

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


Продление доступа

Срок действия доступа к API составляет один год и продлевается автоматически. О выпуске продленного сертификата или токена пользователь уведомляется по почте. После получения уведомления их можно получить в личном кабинете.

Если Вы используете API уровня PCI DSS, дополнительно следует подтверждать Ваш уровень соответствия стандарту PCI DSS по истечении срока действия документа SAQ. О необходимости обновления сведений о документе SAQ пользователь уведомляется по почте (тема письма "Срок действия документа SAQ подходит к концу").

Примеры использования

Bearer токен

Для авторизации с помощью Bearer токена необходимо передать в запросе два HTTP заголовка:

Пример Header'ов
Authorization: Bearer 808e1cc4630440858f5199e4c0a3e706
Sign: 1c4e379396faee212c676d500ee12a21354d8f68b1acbc40b64065cd7dcd50fa

В заголовке Authorization передается Bearer токен, полученный в личном кабинете. В заголовке Sign передается хеш, сформированный определенным образом из параметров запроса. Правило формирования хеша меняется в зависимости от вызываемого метода API.

Для примера разберем вызов метода CreateInvoice. Правило формирования хеша для него выглядит так:

Правило формирования хеша метода CreateInvoice
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::signSecretKey

Вместо названий параметров, перечисленных в правиле, нужно подставить значения, передаваемые в метод. Если какой то из параметров не был передан. то на его место подставляется пустая строка. Вместо signSecretKey подставляется секретный ключ, полученный вместе с токеном в личном кабинете.

При вызове метода CreateInvoice с параметрами

Пример параметров, передаваемых в CreateInvoice
eshopId: 462539
orderId: myorder
recipientAmount: 10.00
recipientCurrency: RUB
email: e@e.ru

строка с подставленными значениями будет выглядеть так:

Строка для заголовка Sign
462539::myorder::::10.00::RUB::::e@e.ru::::::::::::::::21baff51c1a342f3ac059e61e0894583

Эту строку нужно закодировать в UTF–8 и посчитать от нее SHA256 хеш. Для строки выше получается такой хеш:

Хеш для заголовка Sign
1c4e379396faee212c676d500ee12a21354d8f68b1acbc40b64065cd7dcd50fa

Этот хеш передается в заголовке Sign.

Далее дан пример кода на C#, позволяющий вызвать функцию CreateInvoice. Чтобы им воспользоваться, нужно вписать в строки свои данные.

Пример вызова функции CreateInvoice
public static void CreateInvoice() {
	// Secret Key из настроек магазина -> прием платежей.
	string eshopSecretKey = "1234abcd"; 

	// параметры запроса
	var param = new Dictionary<string, string>
	{
		["eshopId"] = "499999", // для работы примера выставьте номер своего магазина
		["orderId"] = "мой заказ",
		["recipientAmount"] = "10.00",
		["recipientCurrency"] = "TST", // пример предполагает, что в магазине выставлена тестовая валюта.
		["email"] = "youremail@gmail.com", // для работы примера выставьте email на который зарегистрирован аккаунт организации на сайте intellectmoney.
	};

	// Этот параметр не связан с заголовком Sign и с авторизацией по bearer токену. Это другой хеш, использующийся для валидации параметров при вызове метода CreateInvoice.
	param["hash"] = GetCreateInvoiceHash(param, eshopSecretKey);

	// токен и секретный ключ из личного кабинета
	string bearerToken = "808e1cc4630440858f5109e4c0a3e707";
	string signSecretKey = "670bcc16e5c9483fa85096c16ce8c413";
	
	// генерируем хеш для заголовка Sign
	string signHashString = $"{param["eshopId"]}::{param["orderId"]}::::{param["recipientAmount"]}::{param["recipientCurrency"]}::::{param["email"]}::::::::::::::::{signSecretKey}";
	string signHash = GetHashSHA256(signHashString);
	
	// отправляем запрос
	HttpClientHandler clientHandler = new HttpClientHandler();
	using (var content = new FormUrlEncodedContent(param))
	{
		using (HttpClient client = new HttpClient(clientHandler))
		{
			client.DefaultRequestHeaders.Add("Authorization", $"Bearer {bearerToken}");
			client.DefaultRequestHeaders.Add("Sign", signHash);

			using (HttpResponseMessage response = client.PostAsync($"https://api.intellectmoney.ru/merchant/createInvoice", content).Result)
			{
				string responseText = response.Content.ReadAsStringAsync().Result;
				Console.WriteLine(responseText);
				Console.ReadKey();
			}
		}
	}
}

private static string GetCreateInvoiceHash(Dictionary<string, string> param, string eshopSecretKey)
{
	return GetHashMD5($"{param["eshopId"]}::{param["orderId"]}::::{param["recipientAmount"]}::{param["recipientCurrency"]}::::{param["email"]}::::::::::::::::{eshopSecretKey}");
}

private static string GetHashMD5(string source)
{
	byte[] data = Encoding.UTF8.GetBytes(source);
    using (MD5 md5 = new MD5CryptoServiceProvider())
    {
        data = md5.ComputeHash(data);
    }
    return BitConverter.ToString(data).Replace("-", "").ToLower();
}

private static string GetHashSHA256(string source)
{
	byte[] data = Encoding.UTF8.GetBytes(source);
	using (var sha256 = new SHA256CryptoServiceProvider())
	{
		data = sha256.ComputeHash(data);
	}
	return BitConverter.ToString(data).Replace("-", "").ToLower();
}

Сертификат

Для тестирования SSL-сертификата доступны методы API:

При успешном вызове метода вы получите ответ следующего вида:

Пример ответа успешной валидации
{
  "OperationState": {
    "Code": 0,
    "Desc": "Успешно обработана"
  },
  "OperationId": "e8d24ac5-099b-41ce-a84a-a09b4ad9fe40",
  "Result": {
    "State": {
      "Code": 0,
      "Desc": "Успешно обработан."
    },
    "Data": "Congratulations! Your certificate is valid.
Property value is value"
  }
}

Далее даны примеры кода для вызова этих методов на разных языках.

C#

Пример C#
// Путь до сертификата, скачанного из личного кабинета.
string certPath = @"certificate.pfx";
// Пароль от сертификата, заданный в личном кабинете.
string certPassword = "Z3nJ#f@85G";

using (X509Certificate2 certificate = new X509Certificate2(certPath, certPassword))
{
	HttpClientHandler clientHandler = new HttpClientHandler();
	clientHandler.SslProtocols = SslProtocols.Tls12 | SslProtocols.Tls13;
	clientHandler.ClientCertificates.Add(certificate);
	clientHandler.ClientCertificateOptions = ClientCertificateOption.Manual;
	var requestParams = new Dictionary<string, string>
	{
        // Пример того, как задаются параметров запроса.
        // Вызывающийся здесь метод getCertificateValidationPcidssLevel не требует параметров, но они используются для вызова других методов API.
		["property"] = "value",
	};
	using (var content = new FormUrlEncodedContent(requestParams))
	{
		using (HttpClient client = new HttpClient(clientHandler))
		{
			using (HttpResponseMessage response = client.PostAsync($"https://api.intellectmoney.ru/personal/certificate/getCertificateValidationPcidssLevel", content).Result)
			{
				string responseText = response.Content.ReadAsStringAsync().Result;
				Console.WriteLine(responseText);
				Console.ReadKey();
			}
		}
	}
}

PHP

Для использования сертификата в PHP его следует конвертировать из формата PFX в формат PEM. Можно использовать утилиту OpenSSL:

openssl pkcs12 -in cert_file.pfx -out cert_file.pem

При выполнении команды OpenSSL запросит пароль. Необходимо указать пароль, заданный в личном кабинете перед скачиванием pfx файла.

Пример PHP
<?php
	$url = "https://api.intellectmoney.ru/personal/certificate/getCertificateValidationBaseLevel";
	$cert_file = 'cert_file.pem';
	$cert_password = '1234';
	$ch = curl_init();
	$options = array(
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_URL => $url,
	CURLOPT_SSLCERT => $cert_file,
	CURLOPT_SSLCERTPASSWD => $cert_password,
	);
	curl_setopt_array($ch, $options);
	$output = curl_exec($ch);
	if ($output === false) {
	echo "Curl Error : " . curl_error($ch);
	} else {
	echo $output;
	}
?>

Инструкция по получению SAQ и отчета об ASV сканирования для организации

Для получения SAQ необходимо пройти программу соответствия PCI DSS. В этом Вам помогут специализированные компании (список квалифицированных компаний можно посмотреть здесь).

Например, можно подтвердить соответствие PCI DSS, получить SAQ и пройти ASV сканирование, обратившись в компанию trustwave.com
Для этого потребуется купить аккаунт по ссылке (нажать на кнопку "get started"), либо обратиться в отдел продаж по почте InfoSales@Trustwave.com или по бесплатному телефону: 888-878-7817.

  • No labels