Обращение к методам API IntellectMoney осуществляется через прикладывание к запросам Bearer-токена либо SSL-сертификата. Чтобы получить их, нужно отправить заявку в личном кабинете и дождаться ее подтверждения менеджером. Проверить работоспособность доступа можно на тестовом API, см. примеры. Доступ к API необходимо подтверждать с периодичность раз в год.
Минимальный уровень доступа. С ним возможно вызывать только методы API, не требующие передачу данных держателей карт (номер карты, срок действия и т.д.). Этот уровень выставляется по умолчанию при создании заявки на доступ.
Необходим для доступа к методам 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.
Результат обработки заявки на доступ будет отправлен на почту, указанную при регистрации кошелька или интернет-магазина. В случае отклонения заявки на доступ, Вы можете подать ее повторно, приложив актуальные документы.
В случае успешной обработки заявки на доступ Вы получите письмо с темой "Ваш доступ к API активирован".
Задайте пароль и скачайте сертификат из личного кабинета (пункт меню "Запросы доступов" в разделе "Настройки"). Безопасный пароль должен иметь длину от 7 до 20 символов, состоять из букв латинского алфавита (минимум одна буква в верхнем и нижнем регистре), цифр и хотя бы одного символа (@, $, !, %, *, ?, &). Сертификат скачивается в формате PFX. Вы можете проверить работоспособность Вашего доступа на тестовом API, см. примеры.
Токен и секретный ключ отображаются по нажатию кнопки "Показать". В целях безопасности токен и ключ можно просмотреть только один раз. В случае утери токена или ключа нужно запросить новые, используя форму "Перезапрос доступа". Старые токен и ключ при этом перестанут работать.
Обращаем Ваше внимание на то, что в целях безопасности сертификат можно скачать только один раз. Токен и его секретный ключ также отображаются только один раз. В случае утери скачанного файла или токена, необходимо запросить новые с помощью формы перезапроса доступа. |
Срок действия доступа к API составляет один год и продлевается автоматически. О выпуске продленного сертификата или токена пользователь уведомляется по почте. После получения уведомления их можно получить в личном кабинете.
Если Вы используете API уровня PCI DSS, дополнительно следует подтверждать Ваш уровень соответствия стандарту PCI DSS по истечении срока действия документа SAQ. О необходимости обновления сведений о документе SAQ пользователь уведомляется по почте (тема письма "Срок действия документа SAQ подходит к концу").
Для авторизации с помощью Bearer токена необходимо передать в запросе два HTTP заголовка:
Authorization: Bearer 808e1cc4630440858f5199e4c0a3e706 Sign: 1c4e379396faee212c676d500ee12a21354d8f68b1acbc40b64065cd7dcd50fa |
В заголовке Authorization передается Bearer токен, полученный в личном кабинете. В заголовке Sign передается хеш, сформированный определенным образом из параметров запроса. Правило формирования заголовка Sign меняется в зависимости от вызываемого метода API.
Для примера разберем вызов метода CreateInvoice. Правило формирования заголовка Sign для него выглядит так:
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::signSecretKey |
Вместо названий параметров, перечисленных в правиле, нужно подставить значения, передаваемые в метод. Если какой то из параметров не был передан. то на его место подставляется пустая строка. Вместо signSecretKey
подставляется секретный ключ, полученный вместе с токеном в личном кабинете.
При вызове метода CreateInvoice с параметрами
eshopId: 462539 orderId: myorder recipientAmount: 10.00 recipientCurrency: RUB email: e@e.ru |
строка с подставленными значениями будет выглядеть так:
462539::myorder::::10.00::RUB::::e@e.ru::::::::::::::::21baff51c1a342f3ac059e61e0894583 |
Эту строку нужно закодировать в UTF–8 и посчитать от нее SHA256 хеш. Для строки выше получается такой хеш:
1c4e379396faee212c676d500ee12a21354d8f68b1acbc40b64065cd7dcd50fa |
Этот хеш передается в заголовке Sign.
Далее дан пример кода на C#, позволяющий вызвать функцию 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" } } |
Далее даны примеры кода для вызова этих методов на разных языках.
// Путь до сертификата, скачанного из личного кабинета. 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 его следует конвертировать из формата PFX в формат PEM. Можно использовать утилиту OpenSSL:
openssl pkcs12 -in cert_file.pfx -out cert_file.pem |
При выполнении команды OpenSSL запросит пароль. Необходимо указать пароль, заданный в личном кабинете перед скачиванием pfx файла.
<?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 необходимо пройти программу соответствия PCI DSS. В этом Вам помогут специализированные компании (список квалифицированных компаний можно посмотреть здесь).
Например, можно подтвердить соответствие PCI DSS, получить SAQ и пройти ASV сканирование, обратившись в компанию trustwave.com
Для этого потребуется купить аккаунт по ссылке (нажать на кнопку "get started"), либо обратиться в отдел продаж по почте InfoSales@Trustwave.com или по бесплатному телефону: 888-878-7817.