Merchant → UTERLAB

Merchant API

Подключение мерчанта к UTERLAB.COM API v1.

v1Скачать .md

Базовый URL

https://test.uterlab.com/api/v1

JSON API. Все защищённые запросы подписываются HMAC-SHA256.

Авторизация

X-API-KeyИдентификатор API-ключа

X-TimestampUnix timestamp, допустимое окно ±60 секунд

X-NonceУникальное значение для каждого запроса

X-SignatureHMAC-SHA256 подпись

API secret выдаётся в ЛК один раз и не должен передаваться третьим лицам.

Формирование подписи

Строка подписи формируется без лишних пробелов:

timestamp\nnonce\nMETHOD\n/path\nraw_body

X-Signature = HMAC-SHA256(signature_string, secret)

METHOD передаётся в верхнем регистре. Для GET без body последняя строка пустая.

Endpoints

Метод	Endpoint	Scope	Назначение
GET	`/balance`	`balance:read`	Баланс
GET	`/methods`	`methods:read`	Доступные методы приёма
GET	`/banks`	`banks:read`	Справочник банков
POST	`/orders`	`orders:create`	Создать заявку
GET	`/orders/{external_id}`	`orders:read`	Получить заявку
POST	`/orders/{external_id}/cancel`	`orders:cancel`	Отменить заявку
POST	`/orders/{external_id}/payment-received`	`orders:dispute`	Сообщить об оплате
POST	`/orders/{external_id}/check-payment`	`orders:dispute`	Повторная проверка оплаты
GET	`/payout-methods`	`payout-methods:read`	Методы выплат
POST	`/payouts`	`payouts:create`	Создать выплату
GET	`/payouts/{external_id}`	`payouts:read`	Статус выплаты
POST	`/payouts/{external_id}/cancel`	`payouts:cancel`	Отменить выплату

Создание заявки

POST /api/v1/orders

{
  "external_id": "ORDER-10001",
  "amount": "15000.00",
  "currency": "RUB",
  "method": "c2c",
  "bank_code": "sber"
}

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

{
  "success": true,
  "data": {
    "external_id": "ORDER-10001",
    "status": "active",
    "amount": "15000.0000",
    "rate": "95.42000000",
    "amount_usdt": "157.1997",
    "expires_at": "2026-10-14 21:30:00",
    "payment": {
      "bank_code": "sber",
      "bank_name": "СберБанк",
      "requisite": "2202201234567890",
      "holder_name": "Иван И."
    }
  }
}

Нет доступных реквизитов

HTTP 422
{
  "success": false,
  "message": "No available requisites",
  "data": {
    "external_id": "ORDER-10001",
    "status": "failed",
    "amount": "15000.0000",
    "currency": "RUB"
  }
}

Сообщить об оплате

POST /api/v1/orders/{external_id}/payment-received

Нужно отправить multipart/form-data с одним обязательным чеком.

comment=Клиент оплатил
receipt=@receipt.jpg

Количество1 файл

Размердо 2 MB

ФорматыJPG, JPEG, PNG, WEBP, PDF

Выплаты

POST /api/v1/payouts

{
  "external_id": "PAYOUT-10001",
  "amount": "10000.00",
  "currency": "RUB",
  "method": "card_rub",
  "bank_code": "sber",
  "requisite": "2202201234567890",
  "recipient_name": "Иван Иванов"
}

СБП

{
  "external_id": "PAYOUT-10002",
  "amount": "10000.00",
  "currency": "RUB",
  "method": "sbp_rub",
  "bank_name": "СберБанк",
  "requisite": "+79991234567",
  "recipient_name": "Иван Иванов"
}

Для СБП банк обязателен. Используйте bank_code из справочника или передайте bank_name.

Статусы

newЗаявка создана

activeВыданы реквизиты, ожидается оплата

completedЗавершена

cancelledОтменена

expiredИстёк TTL

disputeОплата проверяется

failedЗаявка не обслужена

Ошибки

401Ключ, подпись или timestamp неверны

403Нет scope, IP запрещён или доступ отключён

409Повтор nonce

422Ошибка данных или нет реквизитов

429Rate limit exceeded

{
  "success": false,
  "message": "Invalid signature"
}

Пример cURL

curl -X GET "https://test.uterlab.com/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1792000000" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Signature: YOUR_HMAC_SHA256_SIGNATURE"

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