API-методы

Базовые адреса API Rahmat

Для тестового и промышленного контуров используются разные базовые адреса API.

Контур	Base URL	Назначение
Sandbox	`https://dev-mesh.multicard.uz`	Первичная интеграция и выполнение обязательных тест-кейсов
Production	`https://mesh.multicard.uz`	Приемочное тестирование и проведение промышленных операций

Полный URL метода формируется путем добавления пути метода к соответствующему Base URL.

Авторизация

По умолчанию все запросы (в обоих направлениях) подписываются через HTTP Basic Authentication:

Authorization: Basic <base64(username:password)>

Учётные данные выдаются при подключении партнёра индивидуально для sandbox и production.

Пример:

curl -u "$USERNAME:$PASSWORD" -H "Content-Type: application/json" \
     -X POST https://mesh.multicard.uz/payment/callback/payment-app/{app_name} \
     -d '{...}'

Ошибка аутентификации (401):

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid credentials" }
}

Требования:

Только HTTPS.

Разные пары username/password для sandbox и production.

В логах маскировать заголовок Authorization.

По согласованию сторон вместо Basic Auth может использоваться другой метод (API-Key, Bearer/JWT, mTLS и т.п.) — фиксируется в протоколе подключения партнёра.

API-взаимодействие

Для полноценной интеграции системы Rahmat и Партнера должны поддерживать следующие методы API.

Метод	Направление	Назначение	Обязательность
Проверка платежа в Rahmat	Партнер → Rahmat	Получение текущего статуса и параметров платежа	Для сценария прямой оплаты инвойса без открытия webView
Callback	Партнер → Rahmat	Передача результата платежа	Обязательно
Проверка платежа у Партнера (Status API)	Rahmat → Партнер	Уточнение статуса операции на стороне Партнера	Обязательно
Возврат платежа (Refund API)	Rahmat → Партнер	Возврат денежных средств	Обязательно
Сверка транзакций (Reconciliation API)	Rahmat → Партнер	Сверка транзакций за выбранный период	Обязательно
Передача фискальных данных (Fiscal Link API)	Rahmat → Партнер	Передача ссылки на электронный фискальный чек	Обязательно для фискализируемых платежей
Списание через QR или штрихкод партнера (ScanPay API)	Rahmat → Партнер	Списание денежных средств по QR- или штрихкоду из приложения Партнера	Только при поддержке ScanPay

Общие требования

Все запросы должны выполняться по протоколу HTTPS.

Формат запросов и ответов — JSON в кодировке UTF-8.

Для запросов с телом необходимо передавать заголовок:

Способ аутентификации и проверки подписи согласовывается с командой Rahmat Pay отдельно для каждого Партнера.

Денежные суммы передаются целым числом в тийинах:

100000 = 1 000,00 UZS

Рекомендуемый формат даты и времени — RFC 3339 с указанием часового пояса:

2025-01-31T18:30:00+05:00

Допускается формат:

YYYY-MM-DD HH:mm:ss

В этом случае используется часовой пояс Asia/Tashkent.

Все операции должны быть идемпотентными: повторный запрос с тем же идентификатором транзакции не должен приводить к повторному списанию или возврату денежных средств.

Точные URL методов Партнера, данные для авторизации и правила формирования подписи передаются по защищенному каналу.

Не допускается записывать в журналы полные номера банковских карт, токены оплаты, секретные ключи и другие чувствительные данные.

Callback

После успешного выполнения платежа Партнер должен отправить Callback в Rahmat.

Endpoint

Где {app_name} — код платежного приложения Партнера, согласованный с командой Rahmat Pay.

Тело запроса

{
  "amount": 100000,
  "rahmat_trans_id": 123456789,
  "partner_trans_id": "partner-987654321",
  "payment_time": "2025-01-31T18:30:00+05:00",
  "rrn": "123456789012",
  "phone": "998901234567",
  "pan": "860012******1234",
  "pinfl": "301019XXXXXXXX",
  "name": "IVAN IVANOV"
}

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

Параметр	Тип	Обязательность	Описание
`amount`	integer	Да	Фактически списанная сумма в тийинах
`rahmat_trans_id`	integer или string	Да	Идентификатор платежа в системе Rahmat
`partner_trans_id`	string	Да	Уникальный идентификатор транзакции Партнера
`payment_time`	string	Да	Дата и время выполнения платежа
`rrn`	string	Да	Уникальный номер операции на стороне Партнера или процессинга
`phone`	string	Да	Номер телефона Пользователя в международном формате без символа `+`
`pan`	string	Да	Маскированный номер банковской карты или другого источника средств
`pinfl`	string или null	По согласованию	ПИНФЛ Пользователя
`name`	string или null	По согласованию	Имя держателя источника средств

Параметры pinfl и name не должны передаваться, если их обработка не согласована с командой Rahmat Pay.

Успешный ответ

{
  "success": true,
  "data": {
    "fiscal_url": null
  }
}

Если фискальный чек уже сформирован, Rahmat может вернуть ссылку в поле fiscal_url:

{
  "success": true,
  "data": {
    "fiscal_url": "https://example.com/fiscal-receipt"
  }
}

Если чек будет сформирован позднее, значение fiscal_url может быть null. В таком случае ссылка передается отдельным запросом через Fiscal Link API.

Ответ с ошибкой

{
  "success": false,
  "error": {
    "code": "ERROR_EXPIRED",
    "message": "Время для оплаты истекло"
  }
}

Обработка ошибок и повторные запросы

При получении HTTP 2xx и success: true Callback считается успешно обработанным.

При получении HTTP 4xx Партнер должен проверить корректность запроса. Автоматический повтор выполняется только для ошибок, явно обозначенных Rahmat как временные.

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

Рекомендуемый первый повтор — через 60 секунд.

Максимальное количество автоматических попыток — 5, если иной порядок не согласован с командой Rahmat Pay.

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

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

Если Rahmat возвращает success: false после фактического списания средств, Партнер должен выполнить отмену или возврат в соответствии с согласованным процессом.

Передача фискальных данных (Fiscal Link API)

После фискализации платежа Rahmat передает Партнеру ссылку на электронный фискальный чек.

Партнер должен предоставить HTTPS endpoint для приема таких уведомлений.

Направление запроса

Rahmat → Партнер

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

{
  "partner_trans_id": "partner-987654321",
  "fiscal_url": "https://example.com/fiscal-receipt"
}

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

Параметр	Тип	Обязательность	Описание
`partner_trans_id`	string	Да	Идентификатор транзакции Партнера
`fiscal_url`	string	Да	HTTPS-ссылка на электронный фискальный чек

Успешный ответ

{
  "success": true
  ...
}

Не успешный ответ

{
  "success": false
  "error": {
    "code": "ERROR_CODE",
    "details": "Описание ошибки"
  }
}

Требования

Партнер должен связать фискальную ссылку с исходной транзакцией по partner_trans_id.

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

Срок передачи фискальной ссылки определяется согласованным SLA.

При получении HTTP 5xx, сетевой ошибке или превышении времени ожидания Rahmat повторяет запрос.

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

В случае успешного приема Партнер должен возвратить успешный ответ с кодом HTTP 200.

В случае ошибки Партнер должен возвратить ответ с кодом HTTP 4xx, в теле вернуть детали ошибки.

Возврат платежа (Refund API)

Метод используется Rahmat для выполнения полного возврата денежных средств по ранее успешной транзакции.

Партнер должен предоставить HTTPS endpoint для приема запросов на возврат.

Направление запроса

Rahmat → Партнер

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

{
  "partner_trans_id": "partner-987654321"
}

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

Параметр	Тип	Обязательность	Описание
`partner_trans_id`	string	Да	Идентификатор исходной транзакции Партнера

Успешный ответ

{
  "success": true
}

Ответ с ошибкой

{
  "success": false,
  "error": {
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Транзакция не найдена"
  }
}

Требования

Метод должен быть идемпотентным.

Повторный запрос для уже возвращенной транзакции должен возвращать успешный результат без повторного зачисления денежных средств.

Возврат должен выполняться только для успешно завершенной транзакции.

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

При получении HTTP 5xx, сетевой ошибке или превышении времени ожидания Rahmat повторяет запрос.

После успешного возврата Партнер должен возвращать статус refund в Status API.

Проверка платежа у Партнера (Status API)

Метод используется Rahmat для получения актуального состояния транзакции на стороне Партнера.

Партнер должен предоставить HTTPS endpoint для проверки статуса.

Направление запроса

Rahmat → Партнер

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

{
  "partner_trans_id": "partner-987654321"
}

По согласованию метод также может поддерживать поиск по rahmat_trans_id.

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

{
  "amount": 100000,
  "rahmat_trans_id": 123456789,
  "partner_trans_id": "partner-987654321",
  "payment_time": "2025-01-31T18:30:00+05:00",
  "rrn": "123456789012",
  "phone": "998901234567",
  "pan": "860012******1234",
  "pinfl": null,
  "name": null,
  "status": "success"
}

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

Параметр	Тип	Обязательность	Описание
`amount`	integer	Да	Фактически списанная сумма в тийинах
`rahmat_trans_id`	integer или string	Да	Идентификатор платежа в Rahmat
`partner_trans_id`	string	Да	Идентификатор транзакции Партнера
`payment_time`	string или null	Да	Дата и время выполнения платежа
`rrn`	string или null	Да	Уникальный номер операции
`phone`	string или null	Да	Номер телефона Пользователя
`pan`	string или null	Да	Маскированный номер источника средств
`pinfl`	string или null	По согласованию	ПИНФЛ Пользователя
`name`	string или null	По согласованию	Имя держателя источника средств
`status`	string	Да	Текущий статус операции на стороне Партнера

Допустимые статусы Партнера

Статус	Описание
`draft`	Транзакция создана, но обработка еще не началась
`pending`	Транзакция находится в обработке
`success`	Денежные средства успешно списаны
`refund`	По транзакции выполнен возврат
`error`	Транзакция завершена с ошибкой

Соответствие статусам Rahmat

Статус Партнера	Возможный статус Rahmat
`draft`	`draft`
`pending`	`progress` или `billing`
`success`	`success`
`refund`	`revert`
`error`	`error`

Проверка платежа в Rahmat

Партнер может получить актуальную информацию о платеже непосредственно из системы Rahmat.

Поиск платежа по параметру

В теле запроса необходимо передать ровно один параметр поиска.

По идентификатору Партнера

{
  "partner_trans_id": "partner-987654321"
}

По идентификатору Rahmat

{
  "rahmat_trans_id": "rahmat-284715091"
}

По UUID счета

{
  "invoice_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

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

{
  "success": true,
  "data": {
    "id": 588812313,
    "uuid": "44478783-212a-4f81-a643-3dd9f15c9cc3",
    "status": "success",
    "payment_amount": 212800000,
    "total_amount": 212800000,
    "payment_time": "2025-08-13T17:23:15+05:00",
    "qr_url": "https://l.rhmt.uz/DBJk",
    "ps": "partner_app",
    "ps_id": "partner-987654321",
    "receipt_url": "https://ofd.soliq.uz/epi?t=EP000000000000&r=1234567890&c=20250813172315&s=123456789012",
    "store": {
      "title": "TEST STORE",
      "tin": "123456789",
      "official_name": "TEST STORE LLC",
      "logo": "https://example.com/logo.png",
      "mcc": "5812"
    }
  }
}

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

Параметр	Тип	Описание
`id`	integer	Внутренний идентификатор платежа в Rahmat
`uuid`	string	UUID платежа
`status`	string	Текущий статус платежа
`payment_amount`	integer	Сумма платежа в тийинах
`total_amount`	integer	Итоговая сумма в тийинах
`payment_time`	string или null	Дата и время успешной оплаты
`qr_url`	string или null	Ссылка, связанная с QR-кодом платежа
`ps`	string	Код платежного приложения
`ps_id`	string или null	Идентификатор транзакции Партнера
`receipt_url`	string или null	Ссылка на электронный фискальный чек
`store`	object	Информация о точке продаж

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

Статус	Описание
`draft`	Платеж создан
`progress`	Пользователь перешел к оплате
`billing`	Ожидается подтверждение результата
`success`	Платеж успешно завершен
`cancelled`	Платеж отменен
`revert`	Выполнен возврат
`error`	Платеж завершен с ошибкой

Сверка транзакций (Reconciliation API)

Метод используется Rahmat для сверки транзакций с системой Партнера за заданный период.

Партнер должен предоставить HTTPS endpoint для получения отчета.

Направление запроса

Rahmat → Партнер

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

Интервал определяется следующим образом:

date_from <= payment_time < date_to

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

Параметр	Тип	Обязательность	Описание
`date_from`	string	Да	Начало периода включительно
`date_to`	string	Да	Конец периода исключительно

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

{
  "stat": {
    "count": 5,
    "amount": 900000
  },
  "transactions": [
    {
      "amount": 100000,
      "rahmat_trans_id": 123456789,
      "partner_trans_id": "partner-987654321",
      "payment_time": "2025-01-31T18:30:00+05:00",
      "rrn": "123456789012",
      "phone": "998901234567",
      "pan": "860012******1234",
      "pinfl": null,
      "name": null,
      "status": "success"
    }
  ]
}

Требования

stat.count должен соответствовать количеству элементов в transactions.

stat.amount должен содержать общую сумму транзакций в тийинах.

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

Правила включения возвратов и отмен согласовываются с командой Rahmat Pay.

Для больших диапазонов дат может использоваться пагинация. Ее параметры согласовываются отдельно.

Один и тот же запрос за неизменный период должен возвращать согласованный и воспроизводимый результат.

Списание через QR или штрихкод партнера (ScanPay API)

ScanPay используется для оплаты по QR- или штрихкоду, сформированному в приложении Партнера.

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

Общая последовательность

Приложение Партнера формирует QR- или штрихкод с платежным токеном.

Пользователь показывает код кассиру.

Кассир сканирует код.

Rahmat определяет платежное приложение по согласованному префиксу.

Rahmat отправляет запрос в ScanPay API Партнера.

Партнер выполняет списание.

Партнер возвращает результат операции.

При неопределенном результате Rahmat проверяет статус транзакции через Status API.

Направление запроса

Rahmat → Партнер

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

{
  "amount": 15000000,
  "rahmat_trans_id": "123456789",
  "token": 789985469540568,
  "store": {
    "title": "TEST STORE",
    "official_name": "TEST STORE LLC",
    "tin": "123456789",
    "mcc": "5812"
  }
}

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

Параметр	Тип	Обязательность	Описание
`amount`	integer	Да	Сумма списания в тийинах
`rahmat_trans_id`	integer или string	Да	Идентификатор платежа в Rahmat
`token`	integer или string	Да	Токен, полученный из QR- или штрихкода Партнера
`store.title`	string	Да	Отображаемое название точки продаж
`store.official_name`	string	Да	Юридическое наименование мерчанта
`store.tin`	string	Да	ИНН мерчанта
`store.mcc`	string	Да	MCC-код точки продаж

Пример успешного ответа

{
  "success": true,
  "data": {
    "amount": 15000000,
    "rahmat_trans_id": "123456789",
    "partner_trans_id": "partner-987654321",
    "payment_time": "2025-01-31T18:30:00+05:00",
    "rrn": "123456789012",
    "phone": "998901234567",
    "pan": "860012******1234",
    "pinfl": null,
    "name": null
  }
}

Пример отказа

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Недостаточно средств"
  }
}

Требования

Формат и длина токена согласовываются с командой Rahmat Pay.

Партнеру выделяется уникальный префикс токена. Длина префикса определяется отдельно.

Токен должен иметь ограниченный срок действия.

Токен должен быть одноразовым либо защищенным от повторного списания.

ScanPay-запрос должен обрабатываться идемпотентно по rahmat_trans_id.

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

Если результат операции неизвестен из-за тайм-аута или сетевой ошибки, Партнер не должен выполнять повторное списание без проверки исходной транзакции.

Для уточнения неопределенного результата Rahmat использует Status API.

Поля успешного ответа должны соответствовать полям, передаваемым Партнером в Callback.

Базовые адреса API Rahmat#

Авторизация#

API-взаимодействие#

Общие требования#

Callback#

Endpoint#

Тело запроса#

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

Успешный ответ#

Ответ с ошибкой#

Обработка ошибок и повторные запросы#

Передача фискальных данных (Fiscal Link API)#

Направление запроса#

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

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

Успешный ответ#

Не успешный ответ#

Требования#

Возврат платежа (Refund API)#

Направление запроса#

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

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

Успешный ответ#

Ответ с ошибкой#

Требования#

Проверка платежа у Партнера (Status API)#

Направление запроса#

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

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

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

Допустимые статусы Партнера#

Соответствие статусам Rahmat#

Проверка платежа в Rahmat#

Поиск платежа по параметру#

По идентификатору Партнера#

По идентификатору Rahmat#

По UUID счета#

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

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

Статусы платежа в Rahmat#

Сверка транзакций (Reconciliation API)#

Направление запроса#

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

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

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

Требования#

Списание через QR или штрихкод партнера (ScanPay API)#

Общая последовательность#

Направление запроса#

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

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

Пример успешного ответа#

Пример отказа#

Требования#

Базовые адреса API Rahmat

Авторизация

API-взаимодействие

Общие требования

Callback

Endpoint

Тело запроса

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

Успешный ответ

Ответ с ошибкой

Обработка ошибок и повторные запросы

Передача фискальных данных (Fiscal Link API)

Направление запроса

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

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

Успешный ответ

Не успешный ответ

Требования

Возврат платежа (Refund API)

Направление запроса

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

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

Успешный ответ

Ответ с ошибкой

Требования

Проверка платежа у Партнера (Status API)

Направление запроса

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

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

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

Допустимые статусы Партнера

Соответствие статусам Rahmat

Проверка платежа в Rahmat

Поиск платежа по параметру

По идентификатору Партнера

По идентификатору Rahmat

По UUID счета

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

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

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

Сверка транзакций (Reconciliation API)

Направление запроса

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

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

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

Требования

Списание через QR или штрихкод партнера (ScanPay API)

Общая последовательность

Направление запроса

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

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

Пример успешного ответа

Пример отказа

Требования