Payin API (приём платежей)
Эндпоинты приёма платежей — создание, получение, отмена, подтверждение, загрузка доказательств. Формат запросов, коды ошибок, TransactionPayload.
Payin API позволяет создавать платёжные транзакции, получать их данные, отменять, подтверждать и загружать доказательства оплаты (чеки). Все запросы требуют авторизации: заголовок x-public-token и подпись signature.
Базовый путь: /api/v1/payin
Спецификация API (Swagger)
Полная спецификация эндпоинтов, схем запросов/ответов и интерактивная документация доступны во вкладке API (OpenAPI). Там же можно посмотреть актуальные модели и попробовать запросы.
Общая логика
- Данные по транзакции отдаются из БД API (с кэшированием). Операции отмены, подтверждения и загрузки proof выполняются в Core; после этого API возвращает актуальные данные из БД.
- Успешные ответы имеют вид
{ "message": "OK", "data": <TransactionPayload> }. Форматdataодинаков для всех эндпоинтов (см. Формат данных транзакции).
Эндпоинты
GET /api/v1/payin/:transactionId — получение платежа
Возвращает данные по платежу по transactionId (чтение из БД).
| Параметр | Расположение | Тип | Обязательный | Описание |
|---|---|---|---|---|
transactionId | path | string | да | UUID транзакции |
Для подписи при GET передаётся тот же transactionId в query и signature — см. Авторизация (раздел про запросы по transactionId).
Ответ 200: { "message": "OK", "data": <TransactionPayload> }
Ошибки: 401 (авторизация), 403 (доступ к payin отключён), 404 (транзакция не найдена), 500.
POST /api/v1/payin — создание платежа
Создаёт платёж в Core и возвращает актуальные данные из БД. Тело запроса — application/json. Подпись считается по полям body (в т.ч. amount, clientId, gate и т.д.) — см. Авторизация.
Тело запроса:
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
amount | number | да | Сумма платежа |
clientId | number | да | ID клиента мерчанта |
gate | string | нет | ID шлюза |
paymentMethod | string | нет | Метод оплаты |
paymentId | string | нет | Внешний ID платежа (ваш) |
description | string | нет | Описание (до 500 символов) |
isTest | number | нет | 0 или 1 — тестовый платёж |
clientIp | string | нет | IP клиента |
clientEmail | string | нет | Email клиента |
clientName | string | нет | Имя клиента |
successUrl | string | нет | URL редиректа при успехе |
failureUrl | string | нет | URL редиректа при ошибке |
webhookUrl | string | нет | URL вебхука |
webhookMethod | string | нет | get или post |
language | string | нет | Код языка (до 16 символов) |
Полный список полей и типов — во вкладке API (OpenAPI).
Ответ 200: { "message": "OK", "data": <TransactionPayload> }
Ошибки: 400 (невалидное тело), 401, 403 (ERROR_ACCESS_PAYIN_DISABLED), 404 (транзакция не найдена после создания), 500 (в т.ч. ERROR_CORE_INVALID_RESPONSE при отсутствии transactionId в ответе Core).
DELETE /api/v1/payin/:transactionId — отмена платежа
Отменяет платёж в Core и возвращает актуальные данные из БД. Подпись — по payload с полем transactionId (то же, что в URL); для DELETE тело с transactionId и signature — см. Авторизация (раздел про запросы по transactionId).
| Параметр | Расположение | Тип | Обязательный |
|---|---|---|---|
transactionId | path | string | да |
Ответ 200: { "message": "OK", "data": <TransactionPayload> }
Ошибки: 401, 403, 404, 500. При ошибке Core возвращается его статус и тело.
PATCH /api/v1/payin/:transactionId — подтверждение платежа
Подтверждает платёж в Core (confirm) и возвращает актуальные данные из БД. Подпись — по transactionId (как в URL) и signature в body.
| Параметр | Расположение | Тип | Обязательный |
|---|---|---|---|
transactionId | path | string | да |
Ответ 200: { "message": "OK", "data": <TransactionPayload> }
Ошибки: 401, 403, 404, 500.
POST /api/v1/payin/:transactionId — загрузка доказательства оплаты (proof)
Загружает файл доказательства оплаты (чек) в Core. Тело — multipart/form-data, поле document (файл). Допустимые MIME: image/* (кроме image/gif), application/pdf. Максимальный размер файла — 10 МБ. Подпись — по transactionId (из URL) и signature в body.
| Параметр | Расположение | Тип | Обязательный |
|---|---|---|---|
transactionId | path | string | да |
Ответ 200: { "message": "OK", "data": <TransactionPayload> }
Ошибки: 400 (ERROR_INVALID_REQUEST при отсутствии файла, ERROR_INVALID_DOCUMENT_TYPE при недопустимом типе), 401, 403, 404, 500.
Формат данных транзакции (TransactionPayload)
Объект data в успешных ответах имеет следующую структуру. Точные типы и вложенные объекты см. во вкладке API.
| Поле | Тип | Описание |
|---|---|---|
createdAt | string | Дата создания (dd.mm.yyyy HH:mm:ss) |
updatedAt | string | Дата обновления |
expiresAt | string | Время истечения платежа |
merchantId | number | ID мерчанта |
externalId | string | Внешний ID платежа (если передан при создании) |
transactionId | string | UUID транзакции |
status | string | pending | success | failed | canceled | expired | processing | proof_requested |
amount | number | Сумма |
currency | string | Валюта |
exchangeRate | number | Курс |
description | string | Описание (опционально) |
isTest | boolean | Признак тестового платежа |
paymentPage | string | URL платёжной страницы |
paymentTelegramBot | string | Опционально. Ссылка на Telegram-бота с параметром tid (UUID транзакции), если платёж создан с указанием tgbotId. Формат: https://t.me/{username}?tid={transactionId} |
payment | object | cardName, bankName, cardNumber, phoneNumber, qrCode, accountNumber, ibanNumber (строки или null) |
client | object | id, email, name, ip, userAgent, country, city (строки или null; id — строка) |
Коды ошибок (message)
| message | HTTP | Описание |
|---|---|---|
| ERROR_PUBLIC_TOKEN_REQUIRED | 401 | Нет заголовка x-public-token |
| ERROR_SIGNATURE_REQUIRED | 401 | См. Авторизация |
| ERROR_SIGNATURE_INVALID | 401 | См. Авторизация |
| ERROR_PUBLIC_TOKEN_INVALID | 401 | См. Авторизация |
| ERROR_ACCESS_PAYIN_DISABLED | 403 | Доступ к payin отключён для мерчанта |
| ERROR_TRANSACTION_NOT_FOUND | 404 | Транзакция не найдена или нет доступа |
| ERROR_INVALID_REQUEST | 400 | Невалидный запрос (например нет файла в proof) |
| ERROR_INVALID_DOCUMENT_TYPE | 400 | Недопустимый тип файла для proof |
| ERROR_CORE_REQUEST_FAILED | 4xx/5xx | Ошибка ответа Core (тело может содержать детали) |
| ERROR_CORE_INVALID_RESPONSE | 500 | В ответе Core нет transactionId (create) |
| ERROR_SERVER_INTERNAL_ERROR | 500 | Внутренняя ошибка сервера |
Полный перечень эндпоинтов, схем и примеров запросов/ответов — во вкладке API (OpenAPI).