Описание примера работы мультимедийного api. Что такое API? Простое объяснение для начинающих
Диктую По Буквам имеет простой REST API который позволяет:
Все функции API поддерживают метод JSONP : если запрос содержит параметр callback=functionName , JSON-ответ сервера будет завёрнут в вызов функции functionName .
Получение списка алфавитов
Чтобы получить список доступных алфавитов, отправьте GET-запрос следующего формата:
http://api.?format=json [&callback=functionName ]
Сервер вернёт JSON-массив с краткой информацией о доступных алфавитах. [ { "id" :"int-icao" , "language" :"Международные" , "name" : }, { "id" :"de-default" , "language" :"Немецкий" , "name" :"Немецкий фонетический алфавит" }, { "id" :"ru-avia" , "language" :"Русский" , "name" :"Русский авиационный радиоалфавит" } ]
Элементы массива имеют следующие поля: id Идентификатор алфавита, используемый для указания нужного алфавита в других функциях API. language Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные". name Название алфавита на русском языке.
Получение подробной информации об алфавите
Чтобы получить информацию о конкретном алфавите, нужно отправить GET-запрос со следующими параметрами:
http://api.?alphabet=int-icao &format=json [&callback=functionName ]
Параметры запроса имеют следующее назначение: alphabet Идентификатор алфавита. Список доступных алфавитов (и их ID) можно получить . format Желаемый формат ответа. Если format=json , результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.
"Международный фонетический алфавит ИКАО" , "description" :, "source" :{ "name" :"ICAO" , "url" : } } }Объект alphabet имеет следующие поля: id Идентификатор алфавита. language Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные". name Название алфавита на русском языке. description Описание алфавита, его история, варианты использования, другая полезная информация. source Источник информации об алфавите:
- name — название источника (имя человека, название книги или сайта).
- url — гиперссылка на источник (если существует).
Преобразование текста
Чтобы преобразовать по буквам текст, нужно отправить GET или POST запрос со следующими параметрами:
http://api.?text=some%20text &alphabet=int-icao &format=json [&callback=functionName ]
Параметры запроса имеют следующий смысл: text Текст для конверсии (URL-encoded). Максимальная длина текста — 200 символов, остальные будут проигнорированы. alphabet Идентификатор алфавита, который будет использован для преобразования. Список доступных алфавитов (и их ID) можно получить . format Желаемый формат ответа. Если format=json , результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.
Ниже приведён пример ответа сервера (отформатированный для наглядности):
{ "alphabet" :{ "id" :"int-icao" , "language" :"Международные" , "name" :"Международный фонетический алфавит" , "description" :"Фонетический алфавит международной авиационной организации, также известный как международный радиотелефонный алфавит..." , "source" :{ "name" :"ИКАО" , "url" :"http://www.icao.int/icao/en/trivia/alphabet.htm" } }, "spelling" :[ { "original" :"h" , "spelling" :"Hotel" , "format" :"text" , "isGeneric" :false , "midWord" :"for" }, { "original" :"i" , "spelling" :"India" , "format" :"text" , "isGeneric" :false , "midWord" :"for" }, { "original" :"!" , "spelling" :"exclamation mark" , "format" :"text" , "isGeneric" :true , "isPunct" :true } ] }Элементы массива spelling имеют следующие поля: original Один или несколько символов исходного текста (например, "h", "ae" или "sch"), в виде url-encoded строки. spelling Кодовое слово ассоциированное с исходным символом (url-encoded строка). Формат содержимого определяется полем format . format (необязательный) Формат поля spelling . Может принимать одно из следующих значений:
- "text" — Поле spelling содержит HTML или простой текст.
- "img" — Поле spelling содержит ссылку на изображение или само изображение (закодированное в data:URI).
Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. Разработчик Пётр Газаров рассказал об API простыми словами в своём блоге.
Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».
Всемирная паутина и удалённые серверы
WWW можно представить как огромную сеть связанных серверов, на которых и хранится каждая страница. Обычный ноутбук можно превратить в сервер, способный обслуживать целый сайт в сети, а локальные серверы разработчики используют для создания сайтов перед тем, как открыть их для широкого круга пользователей.
При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.
Каждый раз, когда пользователь посещает какую-либо страницу в сети, он взаимодействует с API удалённого сервера. API — это составляющая часть сервера, которая получает запросы и отправляет ответы.
API как способ обслуживания клиентов
Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных .
Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.
Применение API: цель — сервер сайта должен напрямую обращаться к серверу Google с запросом на создание события с указанными деталями, получать ответ Google, обрабатывать его, и передавать соответствующую информацию в браузер, например, сообщение с запросом на подтверждение пользователю.
В качестве альтернативы браузер может сделать запрос к API сервера Google, минуя сервер компании.
Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?
Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.
Если запрос к API делает сервер веб-сайта компании, то он и является клиентом (так же, как клиентом выступает браузер, когда пользователь открывает веб-сайт).
Пользовательблагодаря API получает возможность совершить действие, не покидая сайт компании.
Большинство современных сайтов используют по крайней мере несколько сторонних API. Многие задачи уже имеют готовые решения, предлагаемые сторонними разработчиками, будь то библиотека или услуга. Зачастую проще и надёжнее прибегнуть именно к уже готовому решению.
Многие разработчики разносят приложение на несколько серверов, которые взаимодействуют между собой при помощи API. Серверы, которые выполняют вспомогательную функцию по отношению к главному серверу приложения, называются микросервисами .
Таким образом, когда компания предлагает своим пользователям API, это просто означает, что она создала ряд специальных URL, которые в качестве ответа возвращают только данные.
Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:
Браузер отлично отображает JSON-ответ, который вполне можно вставлять в код. Из такого текста достаточно просто извлечь данные, чтобы использовать их по своему усмотрению.
Ещё несколько примеров API
Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:
- фрагмент программного обеспечения с определённой функцией,
- сервер целиком, приложение целиком или же просто отдельную часть приложения.
Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.
В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой, могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную , внутреннюю логику, которая скрыта от окружения и не является API.
API определяет функциональность, которую предоставляет программа (модуль, библиотека), при этом API позволяет абстрагироваться от того, как именно эта функциональность реализована.
Если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API - это множество «ручек», которые доступны пользователю данного ящика, которые он может вертеть и дёргать.
Программные компоненты взаимодействуют друг с другом посредством API. При этом обычно компоненты образуют иерархию - высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов.
По такому принципу построены протоколы передачи данных по . Стандартный протокол Internet (сетевая модель OSI) содержит 7 уровней (от физического уровня передачи пакетов бит до уровня протоколов приложений, подобных протоколам HTTP и IMAP). Каждый уровень пользуется функциональностью предыдущего уровня передачи данных и, в свою очередь, предоставляет нужную функциональность следующему уровню.
Важно заметить, что понятие протокола близко по смыслу к понятию API. И то и другое является абстракцией функциональности, только в первом случае речь идёт о передаче данных, а во втором - о построении компьютерных приложений.
API библиотеки функций и классов включает в себя описание сигнатур и семантики функций .
Application Programming Interface (API) программный интерфейс взаимодействия между системами, позволяющий:
- Получать доступ к бизнес-сервисам предприятия
- Обмениваться информацией между системами и приложениями
- Упростить взаимодействие между компаниями, партнерами, разработчиками и клиентами
Open API стратегия
API стратегия включает в себя:
- Разработку бизнес-продуктов на основе существующих API
- Предоставление внутренних сервисов разработчикам
- Модели монетизации API для построения мультиканального взаимодействия и повышения прибыли
Реализация концепции Open API помогает трансформировать бизнес, встраивать его в гибкую проектную экосистему игроков рынка, создавать условия для постоянной генерации новых идей и формирования дополнительной ценности при управлении массивами корпоративных данных.
Рынок интеграционных решений развивается в контексте эволюции API - от EDI и SOAP до Web 2.0 , с которого началась эра публичных API. Число таких интерфейсов в ближайшие 3 года может вырасти более чем в 50 раза и достичь 1 миллиона. Это связано с мультиканальностью: каналы взаимодействия с клиентами должны меняться вместе с ними. Непрерывный рост количества потребителей и объема данных привел к появлению экономики API, помогающей на основе открытых интерфейсов создавать инновационные бизнес-модели использования корпоративных активов и сервисов.
Сигнатура функции
Сигнатура функции - часть общего объявления функции, позволяющая средствам трансляции идентифицировать функцию среди других. В различных языках программирования существуют разные представления о сигнатуре функции, что также тесно связано с возможностями перегрузки функции в этих языках.
Иногда различают сигнатуру вызова и сигнатуру реализации функции. Сигнатура вызова обычно составляется по синтаксической конструкции вызова функции с учётом сигнатуры области видимости данной функции, имени функции, последовательности фактических типов аргументов в вызове и типе результата. В сигнатуре реализации обычно участвуют некоторые элементы из синтаксической конструкции объявления функции: спецификатор области видимости функции, её имя и последовательность формальных типов аргументов.
Например, в языке программирования Си++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет учаcтвовать и имя класса.
Также необходимо отметить, что в распоряжении программиста часто находится несколько различных API, позволяющих добиться одного и того же результата. При этом каждый API обычно реализован с использованием API программных компонент более низкого уровня абстракции.
Например: для того, чтобы увидеть в браузере строчку «Hello, world!» достаточно лишь создать HTML -документ с минимальным заголовком, и простейшим телом, содержащим данную строку. Что произойдёт, когда браузер откроет этот документ ? Программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл, и разберётся в его устройстве, повызывает через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать выбранным шрифтом Hello, world!», при этих операциях библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы с запросами вида «а положи-ка мне в буфер видеокарты вот это».
При этом практически на каждом из уровней реально существует несколько возможных альтернативных API. Например: мы могли бы писать исходный документ не на HTML , а на LaTeX, для отображения могли бы использовать любой браузер. Различные браузеры, вообще говоря, используют различные HTML-библиотеки, и, кроме того, всё это может быть (вообще говоря) собрано с использованием различных библиотек примитивов и на различных операционных системах.
Основными сложностями существующих многоуровневых систем API, таким образом, являются:
- Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
- Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.
Основные типы API
Внутренние API
- Доступ к API предоставляется только внутренним разработчикам
- Приложения нацелены на сотрудников предприятия
Бизнес-драйверы:
- Консистентность разработки
- Снижение затрат
- Повышение эффективности разработки
Партнерские API
- API доступны только ограниченному набору бизнес-партнеров
- Приложения предназначены для конечных потребителей и для бизнес-пользователей
Бизнес-драйверы:
- Автоматизация процесса разработки
- Развитие партнерских отношений
- Оптимизация процесса взаимодействия с партнерами
Публичные API
Доступ предоставляется любому внешнему разработчику Приложения нацелены на конечных пользователей
Бизнес-драйверы:
- Разработка новых сервисов
- Развитие экосистемы
- Мультиканальное взаимодействие
Наиболее известные API
API операционных систем
API графических интерфейсов
- Direct3D (часть DirectX)
- DirectDraw (часть DirectX)
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 банка-эмитента | Да | |
Загрузка...
