Введение

Alifpay предоставляет цифровым продуктам финансовые API-инструменты для работы с картами и принятия платежей онлайн. Примерами инструментов являются эквайринг, подсчёт транзакций и просмотр истории использования карт, холдирование средств, токенизация карт и p2p-переводы между картами.

Изучить методы

Для использования рекомендуется актуальная версия методов и структур API. С изменениями можно ознакомиться в этом обзоре.

Взаимодействие

Чтобы начать использовать API, необходимо получить авторизационный токен для песочницы и продуктивной среды, изучить основные элементы, функциональность и методы API.

Для упрощения интеграции во время разработки рекомендуется использовать песочницу API, где доступны тестовые карты для обработки различных сценариев (например, когда карта заблокирована или на ней недостаточно средств). Во время работы в песочнице действительные средства на картах не задействуются.


Получить API-токен

Адрес API

https://api.alifpay.uz

Авторизация

При подключении к системе, клиенту API выдается авторизационный токен, который используется для вызова приватных методов. Для авторизации запросов к API используется HTTP-заголовок Token, в котором необходимо передавать полученный токен в качестве значения.

Для запросов к продуктивной среде и к песочнице используются различные токены.

Пример запроса

Ниже приведён пример raw-запроса с использованием токена для авторизации (см. заголовок Token).

Raw-запрос

POST /watchAnime HTTP/1.1
Host: api.alifpay.uz
Token: Yml0Lmx5LzN4WW9XeWc=
...
Content-Type: application/json

{
  "msg": "secured request"
}

Запросы и ответы

API представляет собой HTTP-based RPC (remote procedure call) и имеет схожесть с JSON-RPC 2.0. Для вызова метода (процедуры) необходимо передать название метода в URI. Каждый HTTP-запрос должен иметь метод POST. Запросы принимаются с телом в JSON-формате. Все валидные ответы имееют HTTP-код ответа 200 - OK. При ошибке возвращается ответ со стандартным телом ошибки с кодом и сообщением.

Запрос

Ниже представлен пример вызова процедуры watchAnime.

POST
/watchAnime
{
  "name": "Naruto",
  "times": 10
}

Ответ

Ниже представлены примеры успешного и неуспешного ответов.

Успешный

{
  "msg": "watching"
}

Неуспешный

{
  "error": {
    "code": 1002,
    "message": "unauthorized"
  }
}

Ошибки

При взаимодействии с API могут возникать ошибки. Ошибки — валидные ответы API, которые следует учитывать при интеграции для автоматической обработки. К таким ошибках относятся, например, ошибки валидации, бизнес-ошибки и внутренние ошибки сервиса.

При таких ошибках в ответах API по-прежнему указывается статус-код 200 - OK.

Структура error

  • Name
    code
    Type
    integer
    Description

    Код ошибки, может быть использован для автоматической обработки.

  • Name
    message
    Type
    string
    Description

    Сообщение, человекочитаемое пояснение ошибки в конкретном случае.

Коды ошибок

Здесь представлен список кодов возможных ошибок при взаимодействии с API.

При ошибках авторизации и ошибках сетевого уровня возвращаются HTTP-коды отличные от 200 - OK. В остальных случаях следует полагаться на список кодов ошибок.

КодОписаниеПояснение и примерыВозможность повторной попытки
1001Неверное тело запросаНевалидный JSON, невалидный тип атрибутаНет
1002Неавторизованный запросНеверный токен мерчанта в заголовкеНет
1003Внутренняя ошибкаКарта не найдена, покупка не найденаЕсть
1004Не найденоНе найдена карта, покупка и другиеЕсть
1005Невалидные параметрыНеверная сумма, пустой параметрНет
1007ОтказаноОтказ на выполнение операцииНет
1100Неверный OTP-Нет
1101Истёк срок действия OTP-Нет
1102Неверные данные картыНеверный номер карты, несуществующая карта или номер карты не соответствует сроку действияНет
1103Истёк срок действия карты-Нет
1104Не подключено СМС-информирование для картыПодключается в банке (или банкомате) держателем карты, необходимо для отправки кодов подтверждения и информирования об операцияхЕсть
1105Дублирование-Нет
1106Количество попыток ввода OTP исчерпано-Нет
1107Карта заблокированаМожет быть заблокирована пользователем, либо на стороне банка, а также автоматически — в результате некоторых операцийЕсть
1108Недостаточно средств на картеНапример, при холдировании или любых других операциях, где нет доступа к статусу операцииЕсть, с другим идентификатором
1109Превышен лимитПревышен лимит отправки счёта по СМС на номер телефонаЕсть
1110Номер телефона не совпадает с номером телефона СМС-информированияУказанный при токенизации номер телефона не совпадает с номером телефона, для которого включено СМС-информирование по картеЕсть

Ответ при ошибке

{
  "error": {
    "code": 1001,
    "message": "bad request (invalid 'amount' parameter type)"
  }
}

Песочница

Песочница — это изолированная реплика API, которая не подключена к процессинговым центрам и не работает с настоящими картами. Во время использования песочницы не используются настоящие денежные средства. Рекомендуется использовать песочницу во время интеграции с API.

Карты

Для тестирования разных сценариев при токенизации и при снятии средств можно использовать приведённые ниже тестовые карты, которые доступны только в песочнице.

Номер картыОписание
1234111111111111Валидная карта
1234666666666666Недостаточно средств
1234777777777777Не подключено СМС-информирование
1234999999999999Заблокированная карта

В качестве срока действия тестовой карты используйте любую актуальную дату в формате MMYY, например 0626. Чтобы подтвердить "оплату" тестовой картой, используйте код 111111.

API токенизации

ПИНФЛ

Для тестирования сценариев, где задействован ПИНФЛ, можно использовать ПИНФЛ из списка ниже. Доступны только в песочнице.

ПИНФЛОписание
11111111111111Валидный ПИНФЛ

Вебхуки

Вебхук представляет собой запрос-уведомление об успешной операции (чаще всего об оплате) на URL, предоставленный клиентом API в инициирующем запросе.

Вебхук оплаты

При использовании API создания счёта или покупки на переданный клиентом API адрес (обычно поле webhook_url, например, при создании счёта) по окончании операции отправляется POST-запрос с информацией об оплате.

Обычно запросы отправляются в течении часа, пока не будет получен ответ со статусом 200 - OK. Если отправить вебхук так и не удалось, оплата будет отменена и средства вернутся клиенту.

Верификация запроса

Чтобы убедиться, что запрос действительно приходит от Alifpay, используется подпись. Для передачи подписи используется HTTP-заголовок Signature. Подпись — это HMACSHA256-хэш, ключом которого является выданный секретный ключ, а сообщением — тело самого запроса.

Для верификации сгенерируйте хэш и сравните его со значением из HTTP-заголовка Signature входящего вебхук-запроса.

Получение подписи

import hmac
import hashlib
import base64

SECRET_KEY = b'secretkey'

def sign(body):
  return base64.b64encode(hmac.new(SECRET_KEY, body, hashlib.sha256).digest())

webhook_body = b'{"type": "purchase", "payload": {}}'
print(webhook_body)

Проверка подписи

alifpay_signature = req.headers["Signature"]
webhook_body = req.body

if sign(body) == alifpay_signature:
  # успешно
else:
  # провалено