XaznaPass

XaznaPass — приём оплаты по одноразовому коду, который пользователь показывает в приложении Xazna. Мерчант передаёт этот код в API, а Xazna списывает сумму с карты пользователя. Тело каждого запроса шифруется алгоритмом RSA и передаётся в поле data.

Основные требования

Данные мерчанта

После регистрации поставщик услуг получает следующие данные для подключения и отправки запросов к API:

#	Parameter	Data type	Description
1	merchantId	UUID	Торговый ID мерчанта, передаётся в открытом виде
2	secretKey	String	Ключ, которым шифруется тело запроса
3	username	String	Логин для basic-авторизации
4	password	String	Пароль для basic-авторизации

Ключ мерчанта

Параметр secretKey является конфиденциальным, и поставщик услуг несёт полную ответственность за его безопасность. Разглашение ключа может привести к утечке ваших данных.

Аутентификация и заголовки

Запросы отправляются с basic-авторизацией — заголовок Auth: Basic. Параметр timestamp — UNIX timestamp (10 цифр, секунды с начала эпохи).

#	Header	Value
1	Accept	application/json
2	Authorization	Basic — username и password, выданные при регистрации
3	Content-Type	application/json

Шифрование данных

• Во всех методах данные запроса шифруются с использованием алгоритма RSA.
• Данные (json) шифруются ранее предоставленным secretKey и отправляются в формате Base64.
• Размер шифруемых данных не должен превышать 350 байт.

Результат шифрования передаётся в поле data. Открытым текстом передаётся только merchantId — по нему Xazna выбирает ключ для расшифровки.

Формат ответа

Все методы возвращают один и тот же конверт: полезная нагрузка лежит в data, результат обработки — в code.

#	Parameter	Data type	Description
1	data	Object	Данные транзакции
2	errorMessage	String	Описание ошибки
3	code	Integer	Код обработки, см. справочник кодов
4	timestamp	Long	Временная метка

Поля data

#	Parameter	Data type	Description
1	merchantId	UUID	Торговый ID мерчанта
2	paymentId	UUID	Xazna транзакция ID
3	paymentStatus	String	Статус оплаты: SUCCESS, ERROR, PENDING, REVERSED
4	amount	Long	Сумма в тийинах. 100000 = 1000.00 сум
5	paymentTime	String	Время оплаты (yyyy-mm-dd hh:mm:ss)
6	message	String	Описание транзакции
7	cardType	String	Тип карты
8	cardNumber	String	Маскированный номер карты
9	phone	String	Номер телефона

Статусы платежа

Status	Description
SUCCESS	Платёж проведён
PENDING	Платёж в обработке — статус нужно перепроверить
ERROR	Платёж не прошёл, причина — в code и errorMessage
REVERSED	Платёж отменён

Оплата

Списывает сумму с пользователя по одноразовому коду otpData, который он показал в приложении.

POST {base_url}/api/v1/qr-pass/payment
Accept: application/json
Content-Type: application/json
Auth: Basic

{
  "merchantId": "string",
  "data": "your_hashing_data"
}

// your_hashing_data — значение, зашифрованное алгоритмом RSA

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

#	Parameter	Data type	Description
1	merchantId	UUID	Торговый ID мерчанта
2	data	String	Зашифрованное значение на основе алгоритма RSA

Шифруемые данные

{
  "otpData": "70704778812456456092",
  "amount": 100000, // 1000.00 сум
  "transactionId": "123"
}

#	Parameter	Data type	Description
1	otpData	String	Одноразовый код для оплаты
2	amount	Long	Сумма в тийинах. 100000 = 1000.00 сум
3	transactionId	String	Транзакция ID мерчанта

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

{
  "data": {
    "merchantId": "string",
    "paymentId": "string",
    "paymentStatus": "SUCCESS",
    "amount": 100000,
    "paymentTime": "2025-08-01 14:22:02",
    "cardType": "HUMO",
    "cardNumber": "****3445",
    "phone": "998911234567",
    "message": "Успешная транзакция"
  },
  "errorMessage": "",
  "code": 0,
  "timestamp": 1754040127141
}

Сохраняйте paymentId

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

Проверка статуса платежа по Xazna

Возвращает текущий статус платежа по идентификатору транзакции Xazna (paymentId).

POST {base_url}/api/v1/qr-pass/check/xazna
Accept: application/json
Content-Type: application/json
Auth: Basic

{
  "merchantId": "string",
  "data": "your_hashing_data"
}

// your_hashing_data — значение, зашифрованное алгоритмом RSA

Шифруемые данные

{
  "paymentId": "string"
}

#	Parameter	Data type	Description
1	paymentId	UUID	Xazna транзакция ID

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

{
  "data": {
    "merchantId": "string",
    "paymentId": "string",
    "paymentStatus": "PENDING",
    "amount": 100000,
    "paymentTime": "2025-08-01 14:22:02",
    "cardType": "HUMO",
    "cardNumber": "****3445",
    "phone": "998911234567",
    "message": "Транзакция в ожидании"
  },
  "errorMessage": "",
  "code": 0,
  "timestamp": 1754040127141
}

Проверка статуса платежа по мерчанту

То же самое, но поиск ведётся по идентификатору транзакции мерчанта — тому transactionId, который был передан при оплате.

POST {base_url}/api/v1/qr-pass/check/merchant
Accept: application/json
Content-Type: application/json
Auth: Basic

{
  "merchantId": "string",
  "data": "your_hashing_data"
}

// your_hashing_data — значение, зашифрованное алгоритмом RSA

Шифруемые данные

{
  "paymentId": "string"
}

#	Parameter	Data type	Description
1	paymentId	UUID	Транзакция ID мерчанта

Имя поля

В этом методе поле называется paymentId, но передаётся в нём идентификатор транзакции мерчанта, а не Xazna.

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

{
  "data": {
    "merchantId": "string",
    "paymentId": "string",
    "paymentStatus": "PENDING",
    "amount": 100000,
    "paymentTime": "2025-08-01 14:22:02",
    "cardType": "HUMO",
    "cardNumber": "****3445",
    "phone": "998911234567",
    "message": "Транзакция в ожидании"
  },
  "errorMessage": "",
  "code": 0,
  "timestamp": 1754040127141
}

Отмена платежа

Возвращает средства пользователю. После успешной отмены статус платежа становится REVERSED.

POST {base_url}/api/v1/qr-pass/reverse
Accept: application/json
Content-Type: application/json
Auth: Basic

{
  "merchantId": "string",
  "data": "your_hashing_data"
}

// your_hashing_data — значение, зашифрованное алгоритмом RSA

Шифруемые данные

{
  "paymentId": "string"
}

#	Parameter	Data type	Description
1	paymentId	UUID	Xazna транзакция ID

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

{
  "data": {
    "merchantId": "string",
    "paymentId": "string",
    "paymentStatus": "REVERSED",
    "amount": 100000,
    "paymentTime": "2025-08-01 14:22:02",
    "cardType": "HUMO",
    "cardNumber": "****3445",
    "phone": "998911234567",
    "message": "Транзакция отменена"
  },
  "errorMessage": "",
  "code": 0,
  "timestamp": 1754040127141
}

Привязка фискализированных данных

Привязывает ссылку на фискальный чек к уже проведённому платежу.

Адрес метода

В исходной документации XaznaPass (версия 1.0) URL этого метода не указан — уточните его у менеджера Xazna перед интеграцией. Формат тела запроса и ответа приведён ниже.

Accept: application/json
Content-Type: application/json
Auth: Basic

{
  "merchantId": "string",
  "data": "your_hashing_data"
}

// your_hashing_data — значение, зашифрованное алгоритмом RSA

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

#	Parameter	Data type	Description
1	merchantId	UUID	Торговый ID мерчанта
2	data	String	Зашифрованное значение на основе алгоритма RSA

Шифруемые данные

{
  "paymentId": "string",
  "qrUrl": ""
}

#	Parameter	Data type	Description
1	paymentId	UUID	Xazna транзакция ID
2	qrUrl	String	Ссылка на фискальный чек

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

{
  "data": {
    "message": "Успешно"
  },
  "errorMessage": "",
  "code": 0,
  "timestamp": 1769422251103
}

#	Parameter	Data type	Description
1	message	String	Описание результата
2	errorMessage	String	Описание ошибки
3	code	Integer	Код обработки, см. справочник кодов
4	timestamp	Long	Временная метка

Справочник кодов

Значение поля code в ответе:

#	Код	Сообщение
1	0	Успешная транзакция
2	-1	Срок действия QR-кода истёк
3	-2	Пользователь не найден
4	-3	Карта не найдена
5	-4	Сервис не найден
6	-5	Сервис неактивен
7	-6	Тип операции не найден
8	-7	Некорректная сумма
9	-8	Ошибка при проведении транзакции
10	-9	Операция не найдена
11	-10	Статус операции неактивен
12	-11	Ошибка при отмене
13	-12	Ошибка. Отсутствуют параметры
14	-13	Ошибка декодирования данных
15	-14	Ошибка подключения
16	999	Системная ошибка