Общие принципы протокола

Взаимодействие Агента (далее Партнер) и Системы (далее Алиф) построено на основе протокола HTTPS (RFC 2818: HTTP/1.1) в режиме “запрос-ответ”, где инициатором запроса всегда является Партнер, а отвечающей стороной – Алиф. Все запросы должны быть отправлены с методом POST.

При обработке запроса от Партнера, Алиф выполняет требуемую операцию, а затем ответом передает Партнеру данные и результат выполнения операции.

key и password - логин и пароль пользователя Партнера. Генерируются и передаются приватно Партнеру со стороны Алиф. В рамках данной документации используются следующие данные: key=”44444444”, password=”cztef62wrwcysyubbbdnhlk1rs2cztfsqgwww7j0”. Пароль перед использованием нужно хешировать алгоритмом HMAC-SHA256: password = hash_hmac(“sha256”, password, key) = hash_hmac(“sha256”, “cztef62wrwcysyubbbdnhlk1rs2cztfsqgwww7j0”, “44444444”) = “3a60036f4a425d879a3f4708c3a1a2b333ca361a1685a7d91d3a4b6183ae2457”

В запросах используется Аутентификационный токен (Token), который отправляется в заголовках запросов и является по сути подписью запроса. Этот Token будет использоваться во всех запросах как часть процесса аутентификации и состоит из хэшированной строки в результате применения алгоритма HMAC-SHA256. Параметрами алгоритма являются Строка и пароль пользователя Партнера.

Строка для генерации Token состоит из конкатенации определенных полей и отличается в разных запросах. В обяснении каждого запроса приводится формула конкатенации этой Строки.

Запрос Create

Заголовки

Token: генерируется по алгоритму SHA256 из конкатенации строк: key+orderid+price.fixed(2)+phone посредством пароля пользователя Партнера.

Параметры запроса

Параметр	Тип	Условие	Описание
key	string	Обязательно	Генерируется и передается приватно Партнеру со стороны Алиф
orderid	string	Обязательно	Уникальный номер заказа со стороны продавца
price	float	Обязательно	Сумма заказа (в сомони)
phone	string	Обязательно	Номер телефона плательщика
deadline	string	Обязательно	Дата просрочки инвойса в формате ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
paytype	string	Обязательно	Способ оплаты: terminal, alif.mobi
info	string	Обязательно	Информация об инвойсе, например: “Оплата за телефон”
callbackurl	string	Обязательно	URL, по которому Алиф ответит при оплате заказа
non_partial_payment	boolean	Обязательно	Флаг, по которому, разрешается (если FALSE) либо отказывается (если TRUE) частичная оплата инвойса.

Параметры ответа

Параметр	Тип	Условие	Описание
code	integer	Обязательно	Числовой код ответа. Смотрите в Таблице №1
message	string	Обязательно	Описание кода ответа
invoiceinfo	InvoiceInfo	Условно	Информация о созданном инвойсе. Обязательно, если “code”:200 либо “code”:203

InvoiceInfo

Параметр	Тип	Условие	Описание
invoiceid	integer	Обязательно	Уникальный номер инвойса
price	string	Обязательно	Сумма заказа (в сомони)
deadline	string	Обязательно	Дата просрочки инвойса в формате ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
paytype	string	Обязательно	Способ оплаты: terminal, alif.mobi
info	string	Обязательно	Информация об инвойсе, например: “Оплата за телефон”
recipient	string	Обязательно	Получатель отплаты инвойса - торговец

// Пример запроса
Метод: POST
Адрес: https://invoices.alif.tj/create
Token: 425b9b7c5d0b5c9c4055714a4e105eef809dcb8e61f8baaea7e6a95b91a29a01
Accept: application/json
Content-type: application/json; charset=utf-8

{
  "key":"44444444",
  "orderid":"130487",
  "price":5402.00,
  "phone":"992935141010",
  "deadline":"2022-08-22T12:21:35Z",
  "paytype":"terminal",
  "info":"Барои харидани ноутбуки Lenovo",
  "callbackurl": "https://domain.tj/path"
}

// Конкатенированная строка для генерации Token: "444444441304875402.00992935141010"

// Пример ответа

{
  "code": 200,
  "message": "Успешно",
  "invoiceinfo": {
    "invoiceid": 84361491,
    "price": "5402.00",
    "deadline": "2022-08-22T12:21:35Z",
    "paytype": "terminal",
    "info": "Барои харидани ноутбуки Lenovo",
    "recipient": "Имя мерчанта"
  }
}

Колбек

Параметры запроса

Параметр	Тип	Значение	Условие	Описание
orderId	string	alpha numeric	Обязательно	Номер заказа, по которому вы отправили запрос на проведение платежа
transactionId	string	alpha numeric	Обязательно	Уникалный ID транзакции, генерируется Алифом и передается Партнёру.
status	string	alpha	Обязательно	Статус платежа: “ok” или “failed”
token	string	hexadecimal	Обязательно	Аутентификационный токен для проверки валидности ответа. Генерируется Алифом по алгоритму SHA256 из конкатенации строк: orderId+status+transactionId посредством пароля пользователя Партнера.
amount	float	numeric	Обязательно	Сумма платежа (в сомони).
phone	string	phone	Обязательно	Номер телефон плательщика

Метод: POST
Адрес: callbackUrl
Accept: application/json
Content-type: application/json; charset=utf-8
Service-Name: Alifpay

{
  "orderId": "12345678",
  "transactionId": "92938922",
  "status": "ok",
  "token": "75fa87340a0c43a9a0efe9e1aa65f5cab7912e3001714827a5fd481f2d7e0416",
  "amount": 10,
  "phone": "+992931234455"
}

// Конкатенированная строка для генерации token ответа: "12345678ok92938922"

Запрос Status

При успешном ответе статус заказа отправится в поле message. Список статусов заказа можно увидеть в Таблице №2.

Заголовки

Token: генерируется по алгоритму SHA256 из конкатенации строк: key+invoiceid посредством пароля пользователя Партнера.

Параметры запроса

Параметр	Тип	Условие	Описание
key	string	Обязательно	Генерируется и передается приватно Партнеру со стороны Алиф
invoiceid	integer	Обязательно	Уникальный номер инвойса

Параметры ответа

Параметр	Тип	Условие	Описание
code	integer	Обязательно	Числовой код ответа. Смотрите в Таблице №1
message	string	Обязательно	Описание кода ответа

// Пример запроса
Метод: POST
Адрес: https://invoices.alif.tj/status
Token: ef6178aeba2f33b80f603a541e23e2823cd970b6db01cfa0d14eb188c57f11b1
Accept: application/json
Content-type: application/json; charset=utf-8

{
  "key":"44444444",
  "invoiceid": 84361491
}

// Конкатенированная строка для генерации Token: "4444444484361491"

// Пример ответа

{
  "code": 200,
  "message": "pending"
}

Запрос Cancel

Невозможно отменить оплаченные или частично оплаченные заказы. Список статусов заказов можно увидеть в Таблице №2.

Заголовки

Token: генерируется по алгоритму SHA256 из конкатенации строк: key+invoiceid посредством пароля пользователя Партнера.

Параметры запроса

Параметр	Тип	Условие	Описание
key	string	Обязательно	Генерируется и передается приватно Партнеру со стороны Алиф
invoiceid	integer	Обязательно	Уникальный номер инвойса

Параметры ответа

Параметр	Тип	Условие	Описание
code	integer	Обязательно	Числовой код ответа. Смотрите в Таблице №1
message	string	Обязательно	Описание кода ответа

// Пример запроса
Метод: POST
Адрес: https://invoices.alif.tj/cancel
Token: ef6178aeba2f33b80f603a541e23e2823cd970b6db01cfa0d14eb188c57f11b1
Accept: application/json
Content-type: application/json; charset=utf-8

{
  "key":"44444444",
  "invoiceid": 84361491
}

// Конкатенированная строка для генерации Token: "4444444484361491"

// Пример ответа

{
  "code": 200,
  "message": "Успешно"
}

Таблица №1. Коды ответов

Код	Описание	Фатальность	create	status	cancel
200	Успешно	Да	+	+	+
202	Частичная оплата	Да	-	-	-
203	Заказ создан, но не получилось отправить уведомление о заказе клиенту	Да	+	-	-
208	Повторная оплата	Да	-	-	-
400	Неверный запрос	Да	+	+	+
401	Неправильный ключ	Да	+	+	+
403	Неверный токен	Да	+	+	+
404	Заказ не существует	Да	-	+	+
406	Просроченный срок заказа	Да	+	-	-
409	Дублированный заказ	Да	+	-	-
410	Сумма не совпадает с суммой выставленного счета	Да	-	-	-
500	Сервис временно не работает. Попробуйте отправить запрос позже	Нет	+	+	+

Таблица №2. Статусы заказов

Статус	Описание
pending	в ожидании
expired	просрочено
paid	оплачено
partial	частично оплачено
canceled	отменено