Что такое API? Простое объяснение для начинающих. Введение
API предназначен для обеспечения взаимодействия производителей услуг с программно-техническим комплексом “Экспресс Платежи”. Конфиденциальность передаваемых данных обеспечивается протоколом TLS 1.0. Аутентификация производителя услуг осуществляется по уникальному API-ключу (токену). Целостность передаваемых данных (защита от MITM-атак) обеспечивается с помощью цифровой подписи алгоритмом HMAC-SHA1, который описан в стандарте RFC 2104 . Дополнительная защита выполняется путем разграничения доступа ip-адресам программного комплекса производителя услуг.
Взаимодействие производителей услуг с программно-техническим комплексом “Экспресс Платежи” осуществляется на клиент-серверной технологии RESTful. Производитель услуг выступает в роли клиента, отправляет HTTP-запросы на сервер API. Возможно использование методов GET, POST, DELETE в HTTP-запросе. Данные передаются в кодировке UTF-8. В ответ на HTTP-запрос сервер отправляет HTTP-ответ клиенту в JSON-формате.
Формат запроса
- {version} – версия API;
- token={token} – API-ключ (токен) доступа к серверу, который задается в личном кабинете;
- signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данное поле является опциональным.
Возможные коды валют:
- 974 – BYR;
- 933 – BYN;
Формат ответа
Любой ответ от сервера представлен в JSON-формате. В случае успешного выполнения запроса возвращается необходимый набор ключей и значений, предназначенный для конкретного ответа на запрос.
Пример ответа при успешном выполнении операции получения списка счетов: {"Items":[{ "InvoiceNo":7, "AccountNo":"70", "Status":1, "Created":"20150101120000", "Expiration":"20150201", "Amount":100000.0, "Currency":933 },{ "InvoiceNo":8, "AccountNo":"80", "Status":3, "Created":"20150201120000", "Expiration":"20150301", "Amount":110000.0, "Currency":933 } ]}
В случае выполнения операции с ошибкой возвращается JSON-узел Error, содержащий:
- Code – код ошибки выполнения операции;
- Msg – сообщение об ошибке;
- MsgCode – код сообщения об ошибке.
- 400 – некорректный запрос;
- 404 – ресурс не найден;
- 500 – внутренняя ошибка севера.
- 4000003 – Некорректный запрос
- 4040001 – Платеж не найден
- 4040002 – Счет на оплату не найден
- 5000000 – Внутренняя ошибка по умолчанию
Включение API
Для работы программного комплекса производителя услуг через API “Экспресс Платежи” необходимо в личном кабинете разрешить использование API.
Для этого необходимо в личном кабинете:
- Перейти на вкладку “Услуги”
- Разрешить использование API для услуги (см. рисунок).
Система ЕРИП
Просмотр списка счетов по параметрам
Метод возвращает список выставленных счетов. Если входные параметры не заданы, то метод возвращает выставленные счета на последние 30 дней.
Метод: GET
URL: https://api.?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
| Поле | Тип | Описание |
|---|---|---|
| InvoiceNo | Integer | Номер счета на оплату |
| AccountNo | String(30) | Номер лицевого счета |
| Status | Integer |
Статус счета на оплату:
|
| Created | String(14) | Дата выставления счета. Формат - yyyyMMddHHmmss |
| Expiration | String(12) | |
| Amount | Decimal(19,2) | Сумма счета на оплату |
| Currency | Integer | Код валюты |
| CardInvoiceNo | Integer | Номер счета по карте (не обязательное. Возвращается только в случае, если выполнялась оплата счета по карте.) |
Пример
Private const string NumberInvoice = "1"; public static void GetListInvoices() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, //Параметры фильтра являются опциональными, по умолчанию возврщает значения за последние 30 дней {"AccountNo", NumberInvoice}, {"From", "20000101" }, {"To", "21000101" }, {"Status", "1" } }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "get-list-invoices"); var url = AppSettings.ServiceUrl + "invoices?token=" + AppSettings.Token + "&signature=" + signature + "&From=20000101&To=21000101&AccountNo=" + NumberInvoice + "&Status=1"; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(url); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Просмотр списка счетов по параметрам function getListInvoices($token, $fromDate = "", $toDate = "", $status = "", $accountNo = "") { global $baseUrl; $url = $baseUrl . "invoices?token=" . $token . "&From=" . $fromDate . "&To=" . $toDate . "&AccountNo=" . $accountNo . "&Status=" . $status; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // //Параметры фильтра являются опциональными, по умолчанию возвращает значения за последние 30 дней // "AccountNo" => $accountNo, // "From" => $fromDate, // "To" => $toDate, // "Status" => $status //); // $signature = computeSignature($requestParams, "", "get-list-invoices"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } // Пример использования echo getListInvoices("a75b74cbcfe446509e8ee874f421bd64");
Выставление счета
Метод выставляет новый счет.
Метод: POST
URL: https://api.?token={Token}
Входные параметры
| Поле | Тип | Описание |
|---|---|---|
| Token | String(32) | API-ключ производителя услуг |
| AccountNo | String(30) | Номер лицевого счета |
| Amount | Decimal(19,2) |
Сумма счета на оплату. |
| Currency | Integer | Код валюты |
| Expiration | String(12) | Дата истечения срока действия выставления счета на оплату. Форматы – yyyyMMdd, yyyyMMddHHmm |
| Info | String(1024) | Назначение платежа |
| Surname | String(30) | Фамилия |
| FirstName | String(30) | Имя |
| Patronymic | String(30) | Отчество |
| City | String(30) | Город |
| Street | String(30) | Улица |
| House | String(18) | Дом |
| Building | String(10) | Корпус |
| Apartment | String(10) | Квартира |
| IsNameEditable | Integer |
При оплате разрешено изменять ФИО плательщика 0 – нет, 1 – да |
| IsAddressEditable | Integer |
При оплате разрешено изменять адрес плательщика 0 – нет, 1 – да |
| IsAmountEditable | Integer |
При оплате разрешено изменять сумму оплаты 0 – нет, 1 – да |
| EmailNotification | String(255) |
Адрес электронной почты, на который будет отправлено уведомление о выставлении счета |
| SmsPhone | String(13) |
Номер мобильного телефона, на который будет отправлено SMS-сообщение о выставлении счета |
Обязательные поля
При выставлении счетов с 1-го июля 2016 года необходимо передавать новый код валюты 933 (BYN). Выставление счетов со старым кодом валюты 974 (BYR) будет завершаться с ошибкой.
Выходные параметры
Пример
Public static void AddInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"AccountNo", "123456"}, {"Amount", "10,10"}, {"Currency", "933"}, {"Expiration", "20160505"}, {"Info", "info"}, {"Surname", "Ivanov"}, {"FirstName", "Ivan"}, {"Patronymic", "Ivanovich"}, {"City", "Minsk"}, {"Street", "Frunze"}, {"House", "20"}, {"Building", "2"}, {"Apartment", "10"}, {"IsNameEditable", "0"}, {"IsAddressEditable", "0"}, {"IsAmountEditable", "0"}, {"EmailNotification", "[email protected]"}, {"SmsPhone", "+375291234567"}, }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "add-invoice"); using (var client = new WebClient()) { var url = AppSettings.ServiceUrl + "invoices?token=" + AppSettings.Token + "&signature=" + signature; var response = client.UploadValues(url, new NameValueCollection { {"AccountNo", "123456"}, {"Amount", "10,10"}, {"Currency", "933"}, {"Expiration", "20160505"}, {"Info", "info"}, {"Surname", "Ivanov"}, {"FirstName", "Ivan"}, {"Patronymic", "Ivanovich"}, {"City", "Minsk"}, {"Street", "Frunze"}, {"House", "20"}, {"Building", "2"}, {"Apartment", "10"}, {"IsNameEditable", "0"}, {"IsAddressEditable", "0"}, {"IsAmountEditable", "0"}, {"EmailNotification", "[email protected]"}, {"SmsPhone", "+375291234567"}, }); var data = AppSettings.DefaultEncoding.GetString(response); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка POST запроса function sendRequestPOST($url, $params) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } //Выставление счета function addInvoice($token, $numberAccount, $amount, $currency, $expiration = "", $info = "", $surname = "", $firstName = "", $patronymic = "", $city = "", $street = "", $house="", $building = "", $apartment = "", $isNameEditable = "", $isAddressEditable = "", $isAmountEditable = "", $emailNotification = "", $smsPhone = "") { global $baseUrl; $url = $baseUrl . "invoices?token=" . $token; /* Использование цифровой подписи $requestParams = array("Token" => $token, "AccountNo" => $numberAccount, "Amount" => $amount, "Currency" => $currency, "Expiration" => $expiration, "Info" => $info, "Surname" => $surname, "FirstName" => $firstName, "Patronymic" => $patronymic, "City" => $city, "Street" => $street, "House" => $house, "Building" => $building, "Apartment" => $apartment, "IsNameEditable" => $isNameEditable, "IsAddressEditable" => $isAddressEditable, "IsAmountEditable" => $isAmountEditable, "EmailNotification" => $emailNotification, "SmsPhone" => $smsPhone); $signature = computeSignature($requestParams, "", "add-invoice"); $url .= "&signature=" . $signature; */ $requestParams = array("AccountNo" => $numberAccount, "Amount" => $amount, "Currency" => $currency, "Expiration" => $expiration, "Info" => $info, "Surname" => $surname, "FirstName" => $firstName, "Patronymic" => $patronymic, "City" => $city, "Street" => $street, "House" => $house, "Building" => $building, "Apartment" => $apartment, "IsNameEditable" => $isNameEditable, "IsAddressEditable" => $isAddressEditable, "IsAmountEditable" => $isAmountEditable, "EmailNotification" => $emailNotification, "SmsPhone" => $smsPhone); return sendRequestPOST($url, $requestParams); } // Пример использования echo addInvoice("a75b74cbcfe446509e8ee874f421bd64", 1, "10,10", 933);
Детальная информация о счете
Метод возвращает детальную информацию о существующем счете.
Метод: GET
URL:
Входные параметры
Обязательные поля
Выходные параметры
| Поле | Тип | Описание |
|---|---|---|
| AccountNo | String(30) | Номер лицевого счета |
| Status | Integer |
Статус счета на оплату:
|
| Created | String(14) | Дата/Время выставления счета. Формат - yyyyMMddHHmmss |
| Expiration | String(12) | Дата истечения срока действия выставления счета на оплату. Форматы – yyyyMMdd, yyyyMMddHHmm |
| Amount | Decimal(19,2) | Сумма счета на оплату |
| Currency | Integer | Код валюты |
| Info | String(1024) | Назначение платежа |
| Surname | String(30) | Фамилия |
| FirstName | String(30) | Имя |
| Patronymic | String(30) | Отчество |
| City | String(30) | Город |
| Street | String(30) | Улица |
| House | String(18) | Дом |
| Building | String(10) | Корпус |
| Apartment | String(10) | Квартира |
| IsNameEditable | Integer | При оплате разрешено изменять ФИО плательщика 0 – нет, 1 – да |
| IsAddressEditable | Integer | При оплате разрешено изменять адрес плательщика 0 – нет, 1 – да |
| IsAmountEditable | Integer | При оплате разрешено изменять сумму оплаты 0 – нет, 1 – да |
Пример
Private const string NumberInvoice = "1"; public static void GetDetailsInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"Id", NumberInvoice} }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "get-details-invoice"); using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(AppSettings.ServiceUrl + "invoices/" + NumberInvoice + "?token=" + AppSettings.Token + "&signature=" + signature); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Детальная информация о счете function getDetailsInvoice($numberInvoice, $token) { global $baseUrl; $url = $baseUrl . "invoices/" . $numberInvoice . "?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "Id" => $numberInvoice //); // $signature = computeSignature($requestParams, "", "get-details-invoice"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования getDetailsInvoice(1, "a75b74cbcfe446509e8ee874f421bd64");
Статус счета
Метод возвращает текущий статус счета.
Метод: GET
URL: https://api./{InvoiceNo}/status?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string NumberInvoice = "1"; public static void GetStatusInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"Id", NumberInvoice} }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "status-invoice"); var url = AppSettings.ServiceUrl + "invoices/" + NumberInvoice + "/status?token=" + AppSettings.Token + "&signature=" + signature; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(url); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Статус счета function getStatusInvoice($numberInvoice, $token) { global $baseUrl; $url = $baseUrl . "invoices/" . $numberInvoice . "/status?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "Id" => $numberInvoice //); // $signature = computeSignature($requestParams, "", "status-invoice"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования echo getStatusInvoice(1, "a75b74cbcfe446509e8ee874f421bd64");
Отменить счет
Метод отменят счет к оплате. Операция возможна только для счетов со статусом “Ожидает оплату”.
Метод: DELETE
URL: https://api./{InvoiceNo}?token={Token}
Входные параметры
Обязательные поля
Пример
Private const string NumberInvoice = "1"; public static void CancelInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"Id", NumberInvoice} }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "cancel-invoice"); var url = AppSettings.ServiceUrl + "invoices/" + NumberInvoice + "?token=" + AppSettings.Token + "&signature=" + signature; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.UploadString(url, "DELETE", string.Empty); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка DELETE запроса function sendRequestDELETE($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Отменить счет function cancelInvoice($numberInvoice, $token) { global $baseUrl; $url = $baseUrl . "invoices/" . $numberInvoice . "?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "Id" => $numberInvoice //); // $signature = computeSignature($requestParams, "", "cancel-invoice"); // $url .= "&signature=" . $signature; return sendRequestDELETE($url); } //Пример использования echo cancelInvoice(1, "a75b74cbcfe446509e8ee874f421bd64");
Получить список оплат
Метод возвращает список полученных оплат. Если входные параметры запроса не заданы, то метод возвращает список полученных оплат за последние 30 дней.
Метод: GET
URL: https://api.?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string NumberPayment = "1022"; public static void GetListPayments() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, // Параметры фильтра являются опциональными. По умолчанию возвращает значения за последние 30 дней {"AccountNo", NumberPayment}, {"From", "20000101" }, {"To", "21000101" } }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "get-list-payments"); var url = AppSettings.ServiceUrl + "payments?token=" + AppSettings.Token + "&signature=" + signature + "&From=20000101&To=21000101&AccountNo=" + NumberPayment; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(url); Console.WriteLine(data); } }
Private static $baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса private static function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Получить список оплат public static function getListPayments($token, $fromDate = "", $toDate = "", $numberPayment = "") { global $baseUrl; $url = $baseUrl . "payments?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // //Параметры фильтра являются опциональными, по умолчанию возвращает значения за последние 30 дней // "AccountNo" => $numberPayment, // "From" => $fromDate, // "To" => $toDate, //); // $signature = computeSignature($requestParams, "", "get-list-payments"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования echo getListPayments("a75b74cbcfe446509e8ee874f421bd64");
Детальная информация об оплате
Метод возвращает детальную информацию о полученной оплате
Метод: GET
URL: https://api./{PaymentNo}?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string NumberPayment = "1022"; public static void GetDetailsPayment() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"Id", NumberPayment} }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "get-details-payment"); using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(AppSettings.ServiceUrl + "payments/" + NumberPayment + "?token=" + AppSettings.Token + "&signature=" + signature); Console.WriteLine(data); } }
Private static $baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса private static function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Детальная информация об оплате function getDetailPayment($token, $numberPayment) { global $baseUrl; $url = $baseUrl . "payments/" . $numberPayment . "?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "Id" => $numberPayment //); // $signature = computeSignature($requestParams, "", "get-details-payment"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования echo getDetailPayment("a75b74cbcfe446509e8ee874f421bd64", 1);
Интернет-эквайринг
Выставление счета по карте
Метод выставляет новый счет для оплаты через банковскую карту.
Метод: POST
URL: https://api.?token={Token}
Входные параметры
| Поле | Тип | Описание |
|---|---|---|
| Token | String(32) | API-ключ производителя услуг |
| AccountNo | String(30) | Номер лицевого счета |
| Expiration | String(8) | Дата истечения срока действия выставленного счета на оплату. Формат - yyyyMMdd |
| Amount | Decimal(19,2) |
Сумма счета на оплату. Сумма счета должна быть не менее 1,00 BYN. Разделителем дробной и целой части является символ запятой |
| Currency | Integer | Код валюты |
| Info | String(1024) | Назначение платежа |
| ReturnUrl | String(512) | Адрес для перенаправления пользователя в случае успешной оплаты |
| FailUrl | String(512) | Адрес для перенаправления пользователя в случае неуспешной оплаты |
| Language | String(2) | Язык в кодировке ISO 639-1. Если не указан, будет использован язык по умолчанию |
| SessionTimeoutSecs | Integer | Продолжительность сессии в секундах. В случае если параметр не задан, будет использовано значение 1200 секунд (20 минут). Если в запросе присутствует параметр ExpirationDate, то значение параметра SessionTimeoutSecs не учитывается. |
| ExpirationDate | String(32) | Время жизни заказа. Формат yyyyMMddHHmmss. Если этот параметр не передаётся в запросе, то для определения времени жизни сессии используется SessionTimeoutSecs. |
Обязательные поля
Выходные параметры
Пример
Public static void AddCardInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"AccountNo", "123456"}, {"Expiration", "20161224"}, {"Amount", "10,10"}, {"Currency", "933"}, {"Info", "info"}, {"ReturnUrl", "https://example.com/success"}, {"FailUrl", "https://example.com/fail"}, {"Language", "ru"}, {"SessionTimeoutSecs", "2000"}, {"ExpirationDate", "20161224235001"}, }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "add-card-invoice"); using (var client = new WebClient()) { var url = AppSettings.ServiceUrl + "cardinvoices?token=" + AppSettings.Token + "&signature=" + signature; var response = client.UploadValues(url, new NameValueCollection { {"AccountNo", "123456"}, {"Expiration", "20161224"}, {"Amount", "10,10"}, {"Currency", "933"}, {"Info", "info"}, {"ReturnUrl", "https://example.com/success"}, {"FailUrl", "https://example.com/fail"}, {"Language", "ru"}, {"SessionTimeoutSecs", 2000}, {"ExpirationDate", "20161224235001"}, }); var data = AppSettings.DefaultEncoding.GetString(response); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка POST запроса function sendRequestPOST($url, $params) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } //Выставление счета по карте function addInvoiceByCard($token, $accountNo, $amount, $currency, $info, $returnUrl, $failUrl, $expiration="", $language="", $pageView="", $sessionTimeoutSecs="", $expirationDate="") { global $baseUrl; $url = $baseUrl . "cardinvoices?token=" . $token; /*$requestParams = array("Token" => $token, "AccountNo" => $accountNo, "Expiration" => $expiration, "Amount" => $amount, "Currency" => $currency, "Info" => $info, "ReturnUrl" => $returnUrl, "FailUrl" => $failUrl, "Language" => $language, "SessionTimeoutSecs" => $sessionTimeoutSecs, "ExpirationDate" => $expirationDate);*/ // Использование цифровой подписи // $signature = computeSignature($requestParams, "", "add-card-invoice"); // $url .= "&signature=" . $signature; $requestParams = array("AccountNo" => $accountNo, "Expiration" => $expiration, "Amount" => $amount, "Currency" => $currency, "Info" => $info, "ReturnUrl" => $returnUrl, "FailUrl" => $failUrl, "Language" => $language, "SessionTimeoutSecs" => $sessionTimeoutSecs, "ExpirationDate" => $expirationDate); return sendRequestPOST($url, $requestParams); } // Пример использования echo addInvoiceByCard("a75b74cbcfe446509e8ee874f421bd64", "123456", "10,10", 933, "info", "https://example.com/success", "https://example.com/fail","20161224", "ru", 2000, "20161224235001");
Форма оплаты
Метод инициирует оплату по банковской карте и возвращает адрес для формы ввода данных банковской карты. Для оплаты выставленного счета необходимо передать в метод InvoiceId, полученный при вызове метода “Выставление счета по карте”.
После ввода данных банковской карты и успешного проведения платежа пользователь будет перенаправлен на адрес ReturnUrl, указанный при выставлении счета по карте. В случае ошибки проведения платежа пользователь будет перенаправлен на адрес FailUrl.
Метод: GET
URL: https://api./{CardInvoiceNo}/payment?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string CardNumberInvoice = "100"; public static void PaymentCardInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"CardInvoiceNo", CardNumberInvoice}, }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "card-invoice-form"); var url = AppSettings.ServiceUrl + "cardinvoices/" + CardNumberInvoice + "/payment?token="+AppSettings.Token+"&signature="+signature; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(url); Console.WriteLine(data); } }
Private static $baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса private static function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Форма оплаты function getPaymentForm($token, $cardNumberInvoice) { global $baseUrl; $url = $baseUrl . "cardinvoices/" . $cardNumberInvoice . "/payment?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "CardInvoiceNo" => $cardNumberInvoice //); // $signature = computeSignature($requestParams, "", "card-invoice-form"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования echo getPaymentForm("a75b74cbcfe446509e8ee874f421bd64","100");
Статус счета по карте
Метод возвращает статус счета по карте.
Метод: GET
URL: https://api./{CardInvoiceNo}/status?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string CardNumberInvoice = "1674"; public static void StatusCardInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"CardInvoiceNo", CardNumberInvoice}, {"Language", "ru"}, }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "status-card-invoice"); var url = AppSettings.ServiceUrl + "cardinvoices/" + CardNumberInvoice + "/status?token=" + AppSettings.Token + "&signature=" + signature + "&language=ru"; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var data = client.DownloadString(url); Console.WriteLine(data); } }
Private static $baseUrl = "https://api.express-pay.by/v1/"; // Отправка GET запроса private static function sendRequestGET($url) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Статус счета по карте function getStatusCardInvoice($token, $InvoiceId, $language="") { global $baseUrl; $url = $baseUrl . "cardinvoices/" . $InvoiceId . "/status?token=" . $token; // Использование цифровой подписи // $requestParams = array(// "Token" => $token, // "CardInvoiceNo" => $InvoiceId, // "Language" => "ru" //); // $signature = computeSignature($requestParams, "", "status-card-invoice"); // $url .= "&signature=" . $signature; return sendRequestGET($url); } //Пример использования echo getStatusCardInvoice("a75b74cbcfe446509e8ee874f421bd64", "1674");
Отмена счета по карте
Метод отменяет оплату счета по карте. Использование операции отмены возможно до 23:59:59 дня проведения операции (не позднее). Для разрешения использования данной операции в анкете реквизитов услуги ЕРИП в разделе "Предоставление возможности плательщику отменить платеж" необходимо выставить опцию "Разрешить до перечисления денежных средств банком".
Метод: POST
URL: https://api./{CardInvoiceNo}/reverse?token={Token}
Входные параметры
Обязательные поля
Выходные параметры
Пример
Private const string CardNumberInvoice = "1674"; public static void ReverseCardInvoice() { var requestParams = new Dictionary { {"Token", AppSettings.Token}, {"CardInvoiceNo", CardNumberInvoice} }; var signature = SignatureHelper.Compute(requestParams, string.Empty, "reverse-card-invoice"); var url = AppSettings.ServiceUrl + "cardinvoices/" + CardNumberInvoice + "/reverse?token=" + AppSettings.Token + "&signature=" + signature; using (var client = new WebClient()) { client.Encoding = AppSettings.DefaultEncoding; var response = client.UploadValues(url, new NameValueCollection()); var data = AppSettings.DefaultEncoding(response); Console.WriteLine(data); } }
$baseUrl = "https://api.express-pay.by/v1/"; // Отправка POST запроса function sendRequestPOST($url, $params) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); return $response; } // Отмена счета по карте function reverseCardInvoice($token, $invoiceId) { global $baseUrl; $url = $baseUrl . "cardinvoices/" . $invoiceId . "/reverse?token=" . $token; $requestParams = array("Token" => $token, "CardInvoiceNo" => $invoiceId); // Использование цифровой подписи // $signature = computeSignature($requestParams, "", "reverse-card-invoice"); // $url .= "&signature=" . $signature; return sendRequestPOST($url, $requestParams); } //Пример использования echo reverseCardInvoice("a75b74cbcfe446509e8ee874f421bd64", "1674");
Уведомления на сайт
Уведомления на сайт предназначены для вызова специального адреса сайта производителя услуг. При использовании такого способа получения уведомлений нет необходимости постоянно опрашивать поступившие платежи через . Такой способ получения уведомлений снижает нагрузку на серверы и увеличивает скорость доставки уведомлений о платежах.
Вызов адреса сайта происходит в момент совершения платежа в адрес производителя услуг или при изменении статуса счета на оплату. Вызываемый адрес сайта указывается в настройках личного кабинета.
Для этого необходимо выполнить следующие операции:
- Перейти в раздел настройки (пункт меню “Настройка”);
- Перейти на вкладку “Услуги”;
- В списке услуг для нужной услуги перейти на “Уведомления”;
- Установить опцию “Получать уведомления об оплате на URL”;
- Указать адрес вызова сайта производителя услуг в поле “URL для уведомлений” вида https://mydomain.by/express-pay/notification (см. рисунок).
Во всех запросах передаются обязательные параметры:
- Data – информация о платеже в JSON-формате (поступление нового платежа, отмена платежа, изменение статуса счета);
- Signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данный параметр передается в случае установки опции “Применять цифровую подпись”.
Сайт производителя услуг должен ответить HTTP-кодом 200 в случае успешной обработки запроса. Если сайт производителя услуг вернет код ответа отличный от 200 или истечет таймаут ожидания ответа, то будет выполнена повторная попытка доставки уведомления. Для обеспечения гарантированной доставки уведомления выполняется 3 дополнительных попытки доставки уведомлений. Первая попытка доставки выполняется через 3 минуты, вторая через 30 минут, третья через 90 минут.
В случае не успешных попыток доставки всех 4-х уведомлений по платежу на адрес электронной почты производителя услуг направляется письмо с отчетом об ошибочных доставках.
При включении опции “Применять цифровую подпись” будет формироваться цифровая подпись для передаваемых данных, которая позволяет контролировать целостность передаваемых данных (защита от MITM-атак). Цифровая подпись основана на алгоритме HMAC-SHA1, который описан в стандарте RFC 2104 .
Параметр “Таймаут ожидания ответа” устанавливает время, которое сервер “Экспресс Платежи” будет ожидать ответа от сайта производителя услуг. Если в течение данного времени сервер производителя услуг не вернет ответ с HTTP-кодом 200, то попытка доставки уведомления считается неудачной.
Параметры уведомления о платежах
| Поле | Тип | Описание |
|---|---|---|
| CmdType | Integer |
Тип уведомления:
|
| Status | Integer |
Статус счета на оплату:
|
| AccountNo | String(30) | Номер лицевого счета |
| InvoiceNo | String(30) | Номер измененного счета в системе “Экспресс Платежи” |
| PaymentNo | Integer | Номер платежа |
| Amount | Decimal(19,2) | Сумма оплаты (разделитель между целой и дробной частью ",") |
| Created | String(14) | Дата оплаты (Формат - yyyyMMddHHmmss) |
| Service | String(258) | Название услуги |
| Payer | String(258) | ФИО плательщика |
| Address | String(258) | Адрес плательщика |
Пример передаваемых данных при получении нового платежа: { "CmdType":1, "PaymentNo":1082, "AccountNo":1024, "Amount":"20000", "Created":"20160217122109", "Service":"mydomain.by", "Payer":"", "Address":"" } Пример передаваемых данных при отмене платежа: { "CmdType":2, "PaymentNo":1082, "AccountNo":1024, "Amount":"20000", "Created":"20160217122203", "Service":"mydomain.by", "Payer":"", "Address":"" } Пример передаваемых данных при изменении статуса счета: { "CmdType":3, "Status":3, "AccountNo":"147221", "InvoiceNo":17645, "Amount":"16", "Created":"20161130125859", "Service":"10ballov.by", "Payer":"", "Address":"" }
При нажатии кнопки “Тестовое уведомление на URL” выполняется доставка тестового уведомления о платеже на адрес производителя услуг, по которому можно проверить прием платежа сайтом производителя услуг.
Пример исходного кода получения данных от сервера
Namespace EripNotify.Models { public class EripNotify { public string Data { get; set; } public string Signature { get; set; } } } namespace EripNotify.Controllers { public class EripNotifyController: ApiController { private static readonly Encoding HashEncoding = Encoding.UTF8; private string _secretWord = "secretWord"; private bool _useSignature = false; public IHttpActionResult Test(Models.EripNotify model) { if (_useSignature) { // Проверяем цифровую подпись if (model.Signature != ComputeSignature(model.Data, _secretWord)) { // NOTE: Добавить обработку ошибки // ... return InternalServerError(); } } // Преобразуем из JSON в Object var obj = JObject.Parse(model.Data); // NOTE: Выполняем действия с полученным объектом // ... return Ok(); } // Функция генерации и проверки цифровой подписи public string ComputeSignature(string json, string secretWord) { var hmac = string.IsNullOrWhiteSpace(secretWord) ? new HMACSHA1(HashEncoding.GetBytes(string.Empty)) : new HMACSHA1(HashEncoding.GetBytes(secretWord)); var hash = hmac.ComputeHash(HashEncoding.GetBytes(json)); var result = new StringBuilder(); foreach (var item in hash) result.Append(item.ToString("X2")); return result.ToString(); } } }
// Секретное слово указывается в настройках личного кабинета $secretWord = "secretWord"; // Использование цифровой подписи указывается в настройках личного кабинета $isUseSignature = true; // Обработка POST запроса if ($_SERVER["REQUEST_METHOD"] === "POST") { $data = $_POST["Data"]; $signature = $_POST["Signature"]; // Проверяем использование цифровой подписи if($isUseSignature) { // Проверяем цифровую подпись if($signature == computeSignature($data, $secretWord)) { // Преобразуем из JSON в Object $data = json_decode($data); // NOTE: Добавить обработку данных о полученном платеже // ... echo "success"; } else { echo "fail signature"; } } else { // Без использования цифровой подписи // Преобразуем из JSON в Object $data = json_decode($data); // NOTE: Добавить обработку данных о полученном платеже // ... echo "success"; } } // Функция генерации и проверки цифровой подписи function computeSignature($json, $secretWord) { $hash = NULL; if (empty(trim($secretWord))) $hash = strtoupper(hash_hmac("sha1", $json, "")); else $hash = strtoupper(hash_hmac("sha1", $json, $secretWord)); return $hash; }
Цифровая подпись
Формирование цифровой подписи для передаваемых данных обеспечивает целостность информации и гарантирует, что передаваемые данные не были изменены посторонними лицами в процессе передачи. Цифровая подпись данных осуществляется с помощью алгоритма HMAC-SHA1, который описан в стандарте RFC 2104 .
При использовании цифровой подписи для запросов на сервер необходимо объединить все параметры запроса в одну строку в строго определенном порядке. Для объединенной строки необходимо рассчитать цифровую подпись, которая указывается при запросе в параметре signature . Сервер при получении входящего запроса выполняет проверку цифровой подписи (параметра signature ) и параметров запроса.
Пример формирования строки запроса при использовании цифровой подписи для получения списка счетов: https://api.?token={Token}&signature={Hash} .
Для усиления безопасности возможно формирование цифровой подписи с помощью секретного слова, которое известно только серверу и клиенту. Чтобы задать секретное слово, необходимо выполнить следующие операции в личном кабинете:
- Перейти в раздел настройки (пункт меню “Настройка”);
- Перейти на вкладку “Услуги”
- В списке услуг для нужной услуги перейти к настройкам API;
- Укажите секретное слово и никому его не передавайте (см. рисунок).
В случае успешной проверки выполняется обработка запроса. Если параметры запроса не соответствуют цифровой подписи, то отсылается уведомление об ошибке и запрос не обрабатывается сервером.
Порядок следования параметров запросов следующий:
- Добавление счета "token", "accountno", "amount", "currency", "expiration", "info", "surname", "firstname", "patronymic", "city", "street", "house", "building", "apartment", "isnameeditable", "isaddresseditable", "isamounteditable"
- Детальная информация счета "token", "id"
- Отменить счет "token", "id"
- Статус счета "token", "id"
- Список счетов "token", "from", "to", "accountno", "status"
- Список платежей "token", "from", "to", "accountno"
- Детали по платежу "token", "id"
- Выставление счета по карте "token", "accountno", "expiration", "amount", "currency", "info", "returnurl", "failurl", "language", "sessiontimeoutsecs", "expirationdate"
- Форма оплаты "token", "CardInvoiceNo"
- Статус счета по карте "token", "CardInvoiceNo", "language"
- Отмена счета по карте "token", "CardInvoiceNo"
Примечание: Разделителем целой и дробной части в сумме (параметр amount) является запятая.
Namespace ExPay.Api { public static class AppSettings { public const string ServiceUrl = "https://api.express-pay.by/v1/"; public const string Token = "a75b74cbcfe446509e8ee874f421bd63"; // API-ключ public static readonly Encoding DefaultEncoding = Encoding.UTF8; } public static class SignatureHelper { private static readonly Encoding HashEncoding = Encoding.UTF8; // Порядок следования полей при вычислении цифровой подписи. // Внимание! Для корректной работы порядок изменять нельзя private static readonly Dictionary Mapping = new Dictionary { { "add-invoice", new { "token", "accountno", "amount", "currency", "expiration", "info", "surname", "firstname", "patronymic", "city", "street", "house", "building", "apartment", "isnameeditable", "isaddresseditable", "isamounteditable" } }, { "get-details-invoice", new { "token", "id" } }, { "cancel-invoice", new { "token", "id" } }, { "status-invoice", new { "token", "id" } }, { "get-list-invoices", new { "token", "from", "to", "accountno", "status" } }, { "get-list-payments", new { "token", "from", "to", "accountno" } }, { "get-details-payment", new { "token", "id" } }, { "add-card-invoice", new { "token", "accountno", "expiration", "amount", "currency", "info", "returnurl", "failurl", "language", "pageview", "sessiontimeoutsecs", "expirationdate" } }, { "card-invoice-form", new { "token", "CardInvoiceNo" } }, { "status-card-invoice", new { "token", "CardInvoiceNo", "language" } }, { "reverse-card-invoice", new { "token", "CardInvoiceNo" } } }; public static string Compute(Dictionary requestParams, string secretWord, string action) { var normalizedParams = requestParams .ToDictionary(k => k.Key.ToLower(), v => v.Value); var cmdFields = Mapping; var builder = new StringBuilder(); foreach (var cmdField in cmdFields) { if (normalizedParams.ContainsKey(cmdField)) builder.Append(normalizedParams); } HMACSHA1 hmac; if (string.IsNullOrWhiteSpace(secretWord)) { // В алгоритме всегда должно быть задан ключ шифрования. Если используется конструктор по умолчанию, то ключ генерируется автоматически, // что нам не подходит hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty)); } else { hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord)); } var hash = hmac.ComputeHash(HashEncoding.GetBytes(builder.ToString())); var result = new StringBuilder(); foreach (var item in hash) { result.Append(item.ToString("X2")); } return result.ToString(); } } }
// Формирование цифровой подписи function computeSignature($requestParams, $secretWord, $method) { $normalizedParams = array_change_key_case($requestParams, CASE_LOWER); $mapping = array("add-invoice" => array("token", "accountno", "amount", "currency", "expiration", "info", "surname", "firstname", "patronymic", "city", "street", "house", "building", "apartment", "isnameeditable", "isaddresseditable", "isamounteditable"), "get-details-invoice" => array("token", "id"), "cancel-invoice" => array("token", "id"), "status-invoice" => array("token", "id"), "get-list-invoices" => array("token", "from", "to", "accountno", "status"), "get-list-payments" => array("token", "from", "to", "accountno"), "get-details-payment" => array("token", "id"), "add-card-invoice" => array("token", "accountno", "expiration", "amount", "currency", "info", "returnurl", "failurl", "language", "pageview", "sessiontimeoutsecs", "expirationdate"), "card-invoice-form" => array("token", "CardInvoiceNo"), "status-card-invoice" => array("token", "CardInvoiceNo", "language"), "reverse-card-invoice" => array("token", "CardInvoiceNo")); $apiMethod = $mapping[$method]; $result = ""; foreach ($apiMethod as $item){ $result .= $normalizedParams[$item]; } $hash = strtoupper(hash_hmac("sha1", $result, $secretWord)); return $hash; }
Тестовый стенд
При тестировании API вместо адреса необходимо использовать адрес тестового стенда . В качестве тестовых данных используйте данные, приведенные ниже.
URL: https://sandbox-api.сайт/v1/
Тестовые API ключи (токены)
Система ЕРИП
Тестовые счета на оплату
| Номер услуги | API ключ | Номер счета на оплату | Номер лицевого счета | Дата выставления счета | Статус |
|---|---|---|---|---|---|
| 3 | 1 | 10 | 01-01-2015 12:00 | Ожидает оплаты | |
| 3 | 2 | 20 | 01-02-2015 12:00 | Оплачен | |
| 3 | 3 | 30 | 01-03-2015 12:00 | Оплачен частично | |
| 3 | 4 | 40 | 01-04-2015 12:00 | Ожидает оплаты | |
| 3 | 5 | 50 | 01-05-2015 12:00 | Оплачен частично | |
| 3 | 6 | 60 | 01-06-2015 12:00 | Отменен | |
| 2 | 7 | 70 | 01-01-2015 12:00 | Ожидает оплаты | |
| 2 | 8 | 80 | 01-02-2015 12:00 | Оплачен | |
| 2 | 9 | 90 | 01-03-2015 12:00 | Оплачен частично | |
| 2 | 10 | 100 | 01-04-2015 12:00 | Ожидает оплаты | |
| 2 | 11 | 110 | 01-05-2015 12:00 | Оплачен частично | |
| 2 | 12 | 120 | 01-06-2015 12:00 | Отменен |
Тестовые платежи
| Номер услуги | API ключ | Номер платежа | Номер лицевого счета | Дата платежа |
|---|---|---|---|---|
| 3 | 1 | 10 | 01-01-2015 12:00 | |
| 3 | 2 | 20 | 01-02-2015 12:00 | |
| 3 | 3 | 30 | 01-03-2015 12:00 | |
| 2 | 4 | 40 | 01-04-2015 12:00 | |
| 2 | 5 | 50 | 01-05-2015 12:00 | |
| 2 | 6 | 60 | 01-06-2015 12:00 |
Интернет-эквайринг
Тестовые счета на оплату банковской картой
| API ключ | Номер счета на оплату | Статус счета по банковской карте | Запрет сторнирования |
|---|---|---|---|
| 100 | Да | ||
| 101 | Да | ||
| 102 | Нет | ||
| 103 | Авторизация отменена | Нет | |
| 104 | Нет | ||
| 105 | Да | ||
| 106 | Авторизация отклонена | Да | |
| 100 | Счет зарегистрирован, но не оплачен | Да | |
| 101 | Предавторизованная сумма захолдирована (для двухстадийных платежей) | Да | |
| 102 | Проведена полная авторизация суммы счета | Нет | |
| 103 | Авторизация отменена | Нет | |
| 104 | По транзакции была проведена операция возврата | Нет | |
| 105 | Инициирована авторизация через ACS банка-эмитента | Да | |
