Руководство разработчика: Интеграция с Paynet (Developer Portal)

Добро пожаловать на портал разработчиков Paynet! Наша платформа — это агрегатор поставщиков услуг и мерчантов, предоставляющий удобные способы приема платежей.

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

1. Выбор типа интеграции

Как выбрать? (Decision Tree)

Сравнение моделей

Что нужно от вас для каждой модели

✅ Универсальный биллинг — никакой разработки:

• ✅ Список полей для формы оплаты (например: телефон, ФИО, номер счёта)
• ✅ Telegram-аккаунт или логин Foyda для получения уведомлений
• ❌ API не требуется
• ❌ Сервер не требуется
• ❌ Разработчик не требуется

⚙️ UWS Коннектор — нужна реализация API:

• ✅ Реализовать JSON-RPC 2.0 методы на своём сервере
• ✅ URL web-сервиса, логин и пароль (HTTP Basic Auth)
• ✅ Список услуг и их serviceId (заполняется в анкете "Порядок технического взаимодействия")
• ✅ Открыть IP-доступ для серверов Paynet

[!NOTE] Что такое serviceId? serviceId — это статический внутренний идентификатор вашей услуги, который вы сами придумываете и передаете нам в документе "Порядок технического взаимодействия". Он НЕ является номером телефона или лицевым счетом клиента (эти данные передаются в массиве fields). Один партнер может предоставлять несколько услуг, и serviceId помогает Paynet понять, какую именно услугу оплачивает клиент.

⚠️ Это НЕ ваш вариант, если...

2. Архитектура и процессы (Sequence Diagrams)

[!IMPORTANT] Архитектурная парадигма (Однонаправленность) Интеграция UWS работает по модели Push/Pull, где Paynet всегда выступает клиентом, а ваш биллинг — сервером. Вы не делаете запросов в сторону API Paynet. Все взаимодействия (включая проверки и отмены) инициируются исключительно со стороны серверов Paynet на ваш Endpoint.

Интеграция по UWS (Универсальный коннектор)

Основной сценарий успешного платежа:

Сценарий 1: Network Timeout (Таймаут сети):

Сценарий 2: Отмена транзакции (CancelTransaction):

Универсальный биллинг

Paynet обрабатывает всю логику самостоятельно и только уведомляет мерчанта.

3. Требования к данным, Безопасность и Идемпотентность

3.1 Форматы данных и Валюта

[!WARNING] Ошибки в этих пунктах — самая частая причина отказов на этапе тестирования.

• Протокол: HTTP 1.1, метод POST, защита TLS v1.3 (HTTPS).
• Кодировка и Заголовки: Все запросы отправляются и принимаются в кодировке UTF-8. Обязательно использование Content-Type: application/json и Accept: application/json.
• Валюта (amount): Все финансовые операции передаются в тийинах (1 сум = 100 тийин, целое число). Например, 10 000 сум = 1000000.
• Формат Даты: Строго YYYY-MM-dd HH:mm:ss. Часовой пояс — GMT+5 (Узбекистан).

[!CAUTION] Единственное исключение из формата дат: параметр timestamp в запросе CheckTransaction приходит в формате EEE MMM dd HH:mm:ss z yyyy, например Mon Jun 16 06:12:41 UZT 2021. Этот формат зафиксирован исторически (по нему уже работает множество поставщиков) и изменению не подлежит — ваш парсер обязан его поддерживать. Все остальные даты, включая timestamp в CancelTransaction и все ответы вашего сервера, используют стандартный формат YYYY-MM-dd HH:mm:ss.

3.2 Авторизация и защита

• HTTP Basic Auth: Запросы от Paynet защищены базовой аутентификацией. При отсутствии или несовпадении пары логин/пароль, ваш сервер обязан возвращать HTTP 401 Unauthorized (а не 200 OK с ошибкой).
• Ротация паролей: Если на вашей стороне реализован необязательный метод ChangePassword, Paynet обязан сменить пароль при первом успешном соединении с вашим биллингом. Если метод не реализован, пароль передается отдельно по любым безопасным каналам.
• Белые списки IP: Доступ к вашему API должен быть открыт только для: 213.230.106.112/28 и 213.230.65.80/28.

3.3 Идемпотентность и Таймауты

Финансовые транзакции требуют строгой консистентности:

• Таймауты: Ваша система должна обрабатывать транзакцию не дольше 500 мс. Допускается обработка до 1 сек, но не более чем 30 минут в сутки. Если ответ не получен в течение 30 секунд, Paynet обрывает соединение по таймауту. При систематическом превышении этих лимитов Paynet вправе отключить поставщика от системы приема платежей до полного устранения причины.
• Идемпотентность (transactionId): Каждая транзакция от Paynet имеет уникальный transactionId. Биллинг партнера не должен допускать двойных списаний по одному и тому же transactionId: на дубликат возвращайте ошибку 201 — после нее Paynet вызовет CheckTransaction, чтобы узнать исходный результат. В случае сетевых сбоев Paynet может повторить запрос или вызвать метод CheckTransaction. В ответ на успешную операцию партнер возвращает свой внутренний номер providerTrnId.

4. Операционная деятельность: Сверка и SLA

• Ежедневная сверка: Расчеты проверяются каждый день. Paynet автоматически вызывает метод GetStatement для получения списка успешных платежей на вашей стороне и сверяет их со своей базой. Также на email партнера отправляется реестр принятых платежей.
• Технические работы (SLA): В случае плановых профилактических работ или обновления оборудования, партнер обязан уведомить техническую поддержку Paynet не позднее чем за 2 недели до начала работ. О непредвиденных сбоях необходимо сообщать немедленно; если сбой не устранен в течение одного рабочего дня, партнер обязан сообщить срок его устранения.

5. OpenAPI Спецификация для UWS

Спецификация доступна в файле OpenAPI (UWS).yaml. Она включает в себя описание всех JSON-RPC 2.0 методов: GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement, ChangePassword (необязательный), а также строгие JSON-схемы, коды ошибок и форматы.

6. Руководство по онбордингу и тестированию (UWS)

Для начала приема платежей через универсальный коннектор (UWS), выполните следующие шаги:

Шаг 1: Подготовка инфраструктуры

• Реализация API: Реализуйте обязательные методы (GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement) согласно спецификации.
• Поддержка протоколов: Обеспечьте поддержку HTTPS (TLS v1.3) и формата обмена данными JSON-RPC 2.0 (метод HTTP POST).
• Сетевые доступы (IP Whitelisting): Откройте доступ к вашему биллингу только для разрешенных IP-адресов Paynet.
• TAS-IX: Убедитесь, что ваше соединение с серверами Paynet осуществляется через сеть TAS-IX.

Шаг 2: Заполнение заявки (Анкеты)

Предоставьте менеджеру Paynet следующую информацию:

• URL web-сервиса: (например, https://api.yourdomain.uz/uws)
• Username и Password: Для HTTP Basic Authentication
• Список услуг: Перечень serviceId и их названий
• Email: Адрес для ежедневных реестров

Шаг 3: Тестирование и Тест-кейсы

Перед запуском необходимо отработать стандартные тест-кейсы:

1. Проверка абонента (GetInformation): Эмуляция успешного поиска абонента и эмуляция ошибки 302 (Клиент не найден).
2. Проведение платежа (PerformTransaction): Успешное пополнение баланса абонента.
3. Ограничения (PerformTransaction): Эмуляция ошибки 413 (Неверная сумма) или 101 (Квота исчерпана).
4. Отмена (CancelTransaction): Проведение тестового платежа и его полная отмена. Возврат средств (частичные возвраты технически не поддерживаются). Эмуляция ошибок 77 (клиент уже израсходовал средства), 306 (отчетный период закрыт) и 203 (транзакция не найдена).
5. Проверка статуса (CheckTransaction): Проверка статуса существующей транзакции (state 1) и несуществующей (state 3, успешный конверт — не ошибка). Обязательно проверьте парсинг timestamp в формате EEE MMM dd HH:mm:ss z yyyy.

Шаг 4: Запуск в Production (Go-Live)

После успешного прохождения всех тестов подписывается акт технической готовности, и ваши сервисы становятся доступны для оплаты миллионам пользователей Paynet!

7. Справочник кодов ошибок Paynet (Paynet Error Codes)

При возникновении бизнес-ошибки биллинг партнера возвращает JSON-RPC ответ с объектом error, содержащим code и message.

[!IMPORTANT] Все коды в этом разделе (201, 412, 413 и т.д.) — это коды ошибок Paynet уровня JSON-RPC, а не HTTP-статусы. Их часто путают с HTTP-кодами: на самом деле они возвращаются внутри объекта error в теле ответа, при этом сам HTTP-статус ответа остаётся 200 OK. Единственное исключение — аутентификация: при неверных логине/пароле возвращается HTTP 401 Unauthorized (см. примечание об ошибке 412 ниже).

Таблица маппинга бизнес-ошибок (Business Error Mapping)

Используйте эту таблицу, чтобы понять, какую ошибку возвращать в зависимости от вашего бизнес-кейса:

[!NOTE] Об ошибке 412 (Неверный логин или пароль): аутентификация выполняется исключительно на уровне HTTP — при неверных учетных данных возвращайте HTTP 401 Unauthorized, а не JSON-RPC ошибку. Код 412 — легаси из ранних версий протокола, в новых интеграциях не используется.

Полный справочник кодов ошибок Paynet

Ошибки протокола JSON-RPC:

[!NOTE] Код 0 («Проведено успешно») — значение статуса, оно никогда не возвращается внутри объекта error.

8. История версий

Портал и OpenAPI-спецификация соответствуют UWS v3.4 от 07.05.2025 с уточнениями core-команды Paynet: добавлен код ошибки 306 (допустимое время отмены истекло), зафиксировано требование TLS v1.3, поле status в ответе GetInformation подтверждено как обязательное.