FORMAT: 1A HOST: https://polls.apiblueprint.org/
Bing API
1. Основные принципы взаимодействия с сервисом Bing
Взаимодействие по API осуществляется с помощью POST запросов в кодировке UTF-8 на URL https://example.process.com.ua/<метод API> Сервис принимает json запросы, при отправке указывать заголовок "Content-Type: application/json". Все запросы к Bing подписываются секретным ключом партнера (выдается при подключении менеджером). Для каждого метода свой набор обязательных параметров, также могут передаваться дополнительные параметры, но в формировании подписи они не участвуют. Все ответы сервиса Bing содержат параметры: result, message, data Если result равен “ok”, то поле data содержит определенные для каждого запроса параметры. Если result равен “error”, запрос был обработан с ошибкой, значение data - null, поле message содержит описание ошибки.2. Ответ на API запрос
Приложение сервиса bing может вернуть 2 типа ответов, в контексте HTTP статуса ответа:| Код ответа | Описание |
|---|---|
| 200 | запрос обработан успешно; все возникшие ошибки обработаны корректно |
| 500 | возникло необработанное исключение |
| Параметр | Тип | Значение по ум. | Описание |
|---|---|---|---|
| result | str | «ok» | Результат обработки запроса, возможные занчения: «ok», «error». |
| data | optional (object) | null | Полезная нагрузка, которую предоставляет API запрос, отличительная для каждого запроса. |
| message | str | «ok» | Вспомагательное сообщение. |
3. Формирование подписи
Подпись формируется следующим образом: все обязательные параметры API запроса упорядочиваются в алфавитном порядке ключей, значения конкатенируются через знак двоеточие (“:”), в конце добавляется секретный ключ (без знака ":"), и от полученной строки генерируется md5 хеш и его HEX-представление передается в параметре запроса sign. Для каждого метода свой набор обязательных параметров, также могут передаваться дополнительные параметры, но в формировании подписи они не участвуют.Например, для партнера с секретным ключом «Secret_key», для запроса с параметрами:
request =
```json
{
“partner_id”: 1,
“account”: “123456789101112”,
“service”: 100,
“amount”: 1.00,
“partner_payment_id”: 123456
}
```
Строка подписи будет иметь вид: 123456789101112:1.00:1:123456:100 Secret_key После применения функции MD5: “sign”: “a93f0021cb2dd5dc1f8ea8a000f3879f”
4. Описание основных методов API
4.1 Метод проверки корректности аккаунта на провайдере, валидация.
Данный метод должен осуществляться перед каждым запросом на создания платежа. URL: `https://{Host}//validate` Method: POST Обязательные параметры запроса (участвуют при формировании подписи): account, partner_id, service Пример запроса: request =
```json
{
'account': '123456789101112',
'partner_id': 1,
'service': 100,
'sign': 'a93f0021cb2dd5dc1f8ea8a000f3879f’'
}
```
Описание параметров:
| Параметр | Описание параметра |
|---|---|
| account | aккаунт получателя средств в платежной системе, например номер карты |
| partner_id | id партнера в системе Bing, выдается при подключении |
| service | id сервиса (платежного направления) в системе Bing, выдается при подключении |
| sign | подпись |
В зависимости от требований провайдера, могут быть переданы дополнительные параметры. Дополнительные параметры для передачи по API сообщаются при подключении конкретного сервиса.
В случае успешной валидации, параметр data имеет следующие данные:
request = ```json { data={ validation_status : 1, validation_result : True, provider_info : { name : Test name }, service : 1 }Где,
validation_result - результат валидации (true или false). Если validation_result равен true, значит аккаунт существует, можно осуществлять его пополнение
validation_status - статус валидации, может иметь следующие значения:
1 – запрос выполнен успешно, необходимо анализировать результат валидации;
2 – сервис провайдера недоступен, результат валидации неизвестен
3 – ошибка при валидации, результат валидации неизвестен
provider_info - дополнительная информация от провайдера, например, ФИО получателя и его адрес.
service — опциональный параметр, сервис, по которому была произведена валидация. Может отличаться от переданного в запросе.
4.2 Метод проводки платежа
Запрос проведения платежа через сервис провайдера. Используется для выплат.
URL: https://{Host}/pay/
Method: POST
Обязательные параметры запроса (участвуют при формировании подписи): account, amount, partner_id, partner_payment_id, service
Где,
| Параметр | Описание |
|---|---|
| account | аккаунт в системе провайдера, например номер карты |
| amount* | сумма платежа, предполагаемого пополнения с точностью до сотых |
| partner_id | id партнера в системе Bing, выдается при подключении |
| service | id (алиас) сервиса в системе Bing, выдается при подключении |
| partner_payment_id | уникальный номер платежа в системе партнера |
| sign | подпись |
*Сервис может обрабатывать запросы с фиат и крипто валютой.
Пример запроса:
request =
{
account: '123456789101112';
service: 1;
sign: 'a93f0021cb2dd5dc1f8ea8a000f3879f’;
amount: 1.00;
partner_payment_id: 123456;
partner_id: 1
}
В ответе на запрос создания платежа поле data имеет следующий вид:
data=
{
status : 2,
provider_status : 1000,
provider_payment_id : 123456,
processed : 2016-05-19 15:28:04.416358,
provider_comission : None,
provider_data : null,
provider_processed : 2016-05-19 15:28:04.414973,
id : 123456,
}
Где
status - статус платежа, числовой код, возможные варианты:
| Статус | Код статуса | Значение статуса |
|---|---|---|
| Created | 0 | нефинальный |
| InProcess | 1 | нефинальный |
| Success | 2 | финальный,платеж проведен |
| Rejected | 3 | финальный,платеж отклонен |
| InternalError | 4 | нефинальный,ошибка при проводке |
| NetworkError | 6 | нефинальный,ошибка при проводке |
provider_status – код статуса платежа на стороне провайдера (если он поддерживает передачу этого параметра);
provider_payment_id – уникальный идентификатор платежа на стороне провайдера. (если он поддерживает передачу этого параметра);
processed — время финальной обработки (установки финального статуса) на стороне сервиса Bing;
provider_comission - комиссия за платеж в системе провайдера (если он поддерживает передачу этого параметра);
provider_data - дополнительная информация от провайдера в json формате;
provider_processed - время обработки платежа на стороне провайдере (если он поддерживает передачу этого параметра).
Внимание! При получении нефинального статуса платежа, необходимо делать запрос pay с теми же параметрами.
Рекомендованная частота отправки повторных запрос не чаще чем 1 запроса в 1 минуту (требования некоторых провайдеров)
4.3 Метод запроса баланса
Возвращает баланс партнера на стороне провайдера по доступным ему валютам.
URL: http://{Host}//provider_balance
Method: POST
Обязательные параметры запроса (участвуют при формировании подписи): provider_id, partner_id.
Пример запроса:
request=
{
provider_id : 1,
partner_id : 1,
sign : a93f0021cb2dd5dc1f8ea8a000f3879f,
}
Где,
provider_id - id провайдера, в системе Bing
partner_id - id партнера в системе Bing.
Пример ответа:
response=
{
message=Ok,
data=[{
currency=980,
balance=1.00,
}],
result=ok,
}
currency - валюта (может быть как фиат так и крипто валюта)
balance - сумма баланса на провайдере.
```