Документация для агентов

Введение

Данная документация является агентской документацией, которая предоставляется в случае договоренности между двумя сторонами и описывает методы и запросы в биллинговой системе Interhub.

Обзор

Все данные принимаются POST методом Ответ возвращается в формате JSON

Запросы

Обращение производится данными запросами calculate, check, pay, и check_status, deposit, merchant_list

Ниже будет описан каждый запрос:

calculate - метод, который должен выполниться до использования метода check. Используется для получения фиксированных суммах гифт карт и проверка возможности реальной транзакции.

check - метод, который должен выполниться до использования метода pay. Используется для получения дополнительной информации от системы и проверки возможности реальной транзакции.

pay - метод, который должен выполниться после того как метод (Response) вернет значение True. Данный метод используется для того, чтобы выполнилась реальная транзакция.

check_status - метод, который должен выполниться после pay. Используется для получения информации о транзакции в случае получения некорректного ответа. Возвращает значения True или False. Если ответ от сервиса не получен или получен нечеткий ответ (например: HTTP status 500), системе агента следует отправить check_status запрос для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут.

deposit - данный запрос производится для получения баланса агента

merchant_list - данный запрос возвращает список услуг которые были предоставлены агенту

trancsations_list - данный запрос возвращает список cписок успешных транзакций которые были выполнены агентом в нашей системе.

Postman collection

Авторизация

Авторизация происходит при помощи токена (token) - который мы вам предоставим в процессе интеграции

Коды ошибок

Здесь будут предоставлены коды ошибок в биллинговой системе

POST check_calculate

{{url}}/api/payment/check/calculate

url и token будут предоставлены в процессе интеграции.

Параметры запроса (request):

Параметр	Тип	Описание
account	string	Аккаунт или номер телефона
agent_transaction_id	string	Идентификатор транзакции на стороне агента - должен быть уникальным
service_id	integer	Уникальный идентификатор услуги

Параметры ответа (response):

Параметр	Тип	Описание
message	string	Ответа от биллинга
success	boolean	Информация о том, как был проведен ответ (false или true)
status	integer	Статус транзакции
account	string	Аккаунт или номер телефона
amount	long	Сумма платежа (валюта от договора)
transaction_id	string	Идентификатор транзакции
amount_in_currency	double	Валюта платежа
comission	integer	Комиссия
fixed_amount	BigDecimal	Фиксированная сумма гифт карты

Headers

Content-Type	application/json
token	{{token}}

Body raw (application/json)

{
    "service_id": 870,
    "account": "",
    "agent_transaction_id":test

}

Example RequestCheck

{
    "merchant_id": 870,
    "account": "3333",
    "agent_transaction_id":test

}

Example Response 200 OK

Body
{
    "message": "Success",
    "success": true,
    "status": 0,
    "account": "3333",
    "amount": 1.00,
    "transaction_id": 1616064023131,
    "amount_in_currency": 0.00,
    "comission": 0.00,
    "fixed_amount": 8.55
}

POST check

{{url}}/api/payment/check

url и token будут предоставлены в процессе интеграции.

Параметры запроса (request):

Параметр	Тип	Описание
account	string	Аккаунт или номер телефона
agent_transaction_id	string	Идентификатор транзакции на стороне агента - должен быть уникальным
amount	double	Сумма платежа (валюта указанная в договоре)
service_id	integer	Уникальный идентификатор услуги
params	object	Объект с параметрами метода. Если в данном методе нет параметров, поле можно пропустить

Параметры ответа (response):

Параметр	Тип	Описание
message	string	Ответа от биллинга
success	boolean	Информация о том, как был проведен ответ (false или true)
status	integer	Статус транзакции
account	string	Аккаунт или номер телефона
amount	long	Сумма платежа (валюта от договора)
id	string	Идентификатор транзакции
amount_in_currency	double	Валюта платежа
comission	integer	Комиссия

Headers

Content-Type	application/json
token	{{token}}

Body raw (application/json)

{
    "account" : "",
    "agent_transaction_id": "test",
    "amount": 20000,
    "service_id": 95, 
    "params": {}
}

Example RequestCheck

{
    "account" : "997774433",
    "agent_transaction_id": "test",
    "amount": 20000,
    "service_id": 95, 
    "params": {}
}

Example Response 200 OK

{
  "message": "Success",
  "success": true,
  "status": 0,
  "account": "997774433",
  "amount": 20000,
  "transaction_id": 1589273985135,
  "amount_in_currency": 20000,
  "comission": 0,
  "currency": "UZS"
}

POST pay

{{url}}/api/payment/pay

url и token будут предоставлены в процессе интеграции.

Параметры запроса (request):

Параметр	Тип	Описание
transaction_id	integer	Идентификатор транзакции

Параметры ответа (response):

Параметр	Тип	Описание
message	string	Ответ от сервера
success	string	информация о том, как был проведен ответ (false или true)
status	string	Статус транзакции

Headers

Content-Type	application/json
token	{{token}}

Body raw (application/json)

{
    "transaction_id": {{transaction_id}}
}

Example Request

{
    "transaction_id": 1576476477083
}

Example Response 200 OK

{
  "message": "Transaction is success",
  "success": true,
  "status": 0
}

POST check status

{{url}}/api/payment/check_status

url и token будут предоставлены в процессе интеграции.

Параметры запроса (request):

Параметр	Тип	Описание
transaction_id	integer	Идентификатор транзакции

Параметры ответа (response):

Параметр	Тип	Описание
message	string	Ответ от сервера
success	string	информация о том, как был проведен ответ (false или true)
status	integer	Статус транзакции

Headers

Content-Type	application/json
token	{{token}}

Body raw (application/json)

{
    "transaction_id": {{transaction_id}}
}

Example Request

curl --location --request POST '{{url}}/api/payment/check_status' \
--header 'Content-Type: application/json' \
--header 'token: ' \
--data-raw '{
    "transaction_id": {{transaction_id}}
}'

Example Response

{
    "message": "Transaction is success",
    "success": true,
    "status": 0
}

GET deposit

{{url}}/api/agent/deposit?currency=860

url и token будут предоставлены в процессе интеграции.

Значение параметра currency будет зависеть от валюты обращения.

Headers

Content-Type	application/json
token	{{token}}

Params

currency	860

Example Request

getBalance

curl --location --request GET '{{url}}/api/agent/deposit?currency=860' \
--header 'Content-Type: application/json' \
--header 'token: '

Example Response 200 OK

{
  "balance": 0,
  "currency": 860
}

GET merchant_list

{{url}}/api/agent/merchant/list

url и token будут предоставлены в процессе интеграции.

Параметры ответа (response):

Headers

Content-Type	application/json
token	{{token}}

Example Request getMerchants

curl --location --request GET '{{url}}/api/agent/merchant/list' \
--header 'Content-Type: application/json' \
--header 'token: {{token}}'

Example Response 200 OK

[
  {
    "name": "WebMoney (Y)",
    "id": 268,
    "min_amount": 1000,
    "max_amount": 5000000
  },
  {
    "name": "WebMoney (Z)",
    "id": 267,
    "min_amount": 1000,
    "max_amount": 5000000
   }
]

POST transactions_list

{{url}}/api/agent/transaction/list

url и token будут предоставлены в процессе интеграции.

Параметры запроса (request):

Параметр	Тип	Описание
from_date	integer	Начало даты
to_date	integer	Конец даты

Параметры ответа (response):

Параметр	Тип	Описание
message	string	Ответ от сервера
success	string	информация о том, как был проведен ответ (false или true)
status	string	Статус транзакции

Headers

Content-Type	application/json
token	{{token}}

Example Request getTransactions

curl --location --request GET '{{url}}/api/agent/transaction/list' \
--header 'Content-Type: application/json' \
--header 'token: {{token}}' \
--data-raw '{
    "from_date": "01.07.2020",
    "to_date": "01.07.2020"
}'

Example Response 200 OK

  "message": "Success",
  "success": true,
  "status": 0,
  "data": [
    {
      "client_account": "993803782",
      "transaction_id": 1593629995697,
      "agent_transaction_id": "test",
      "amount": 48758,
      "date": "02.07.2020 00:00:20",
      "merchant_id": 95,
      "merchant_name": "UzMobile_GSM"
    },
    {
      "client_account": "997791523",
      "transaction_id": 1593629995681,
      "agent_transaction_id": "test",
      "amount": 20896,
      "date": "02.07.2020 00:00:19",
      "merchant_id": 95,
      "merchant_name": "UzMobile_GSM"
    }
  ]
}

Примеры ошибок с описанием:

status = -100, message = "Unauthorized"
status = -101, message = "Paramaters are missing"
status = -102, message = "Paramaters are invalid"
status = -103, message = "Merchant not found"
status = -104, message = "You can not pay for this merchant"
status = -105, message = "Amount is less from minimum"
status = -106, message = "Amount is greater from maximum"
status = -107, message = "Transaction not found"
status = -108, message = "Transaction is not success"
status = -109, message = "Transaction is not valid"
status = -110, message = "Account not found"
status = -111, message = "Deposit is not enough"
status = -112, message = "Payment authorization error"
status = -113, message = "Identification is not valid"
status = -114, message = "Amount is not valid"
status = -115, message = "Method not allowed"
status = -116, message = "Deposit is not found"
status = -117, message = "Transaction is too old"
status = -118, message = "Transaction is duplicate"
status = -119, message = "Agent is not active at the moment"
status = -136, message = "Not enough gift cards"

status = -999, message = "Unknown error"