API

API платежей: СБП и криптовалюта

Один проект может создавать рублёвые счета СБП и криптосчета GRAM/USDT в сети TON. Вы создаёте счёт одним запросом, получаете ссылку и QR-код, клиент оплачивает, а ваш сервер проверяет итоговый статус через API. Ниже весь путь интеграции.

Авторизация

Каждый запрос отправляется с заголовком X-API-Key и вашим секретным ключом. Ключ создаётся в кабинете в разделе «Мой аккаунт» и показывается один раз.

Базовый адрес: https://lunopay.cc
Формат данных: JSON. Обязателен заголовок User-Agent: sbp-api.
Сначала пройдите проверку аккаунта и технический аудит. После одобрения подключайте свои проекты без повторного аудита для каждого способа оплаты.
Новые входящие счета: комиссия LunoPay 0%. Вывод: 10% из суммы заявки

Создать платёж

POST /api/v1/payments/create_sbp

Отправьте сумму и номер заказа. В ответ придёт идентификатор платежа и сумма к оплате (без комиссии LunoPay для новых счетов). Платёжная ссылка и QR становятся доступны по методу статуса.

Поля запроса:

project_id : идентификатор вашего магазина
amount : сумма в рублях, от 0,01 до 1 000 ₽ включительно
order_id : номер заказа в вашей системе
telegram_user_id : необязательно, id плательщика
redirect_url : необязательно, сохраняемое поле; автоматическая доставка webhook не реализована

Новые счета СБП: максимум 1 000 ₽, пауза 15 секунд на аккаунт, общая для API и кабинета. Эти ограничения не меняют условия криптооплаты.

Создать крипто-счёт

POST /api/v1/payments/create_crypto

Счёт на оплату в сети TON. В ответе приходят адрес кошелька, сумма монет без комиссии LunoPay и ссылка ton:// для QR-кода.

Поля запроса:

project_id : ваш проект, тот же ID, что используется для СБП
amount : сумма в рублях; новые входящие без комиссии
currency : GRAM (по умолчанию) или USDT в сети TON
order_id : необязательно, номер заказа; иначе сгенерируем сами
description, redirect_url : необязательно

Курс валюты задаётся в кабинете, раздел «Крипта». Если курс не заполнен, метод вернёт 409 rate_missing, и счёт создан не будет.

Адреса платёжных страниц

Криптовалютные счета открываются по https://lunopay.cc/crypto/{transaction_id}, рублёвые по https://lunopay.cc/sbp/{transaction_id}. Используйте публичный ID из ответа API, а не внутренний номер записи. Валюта уже созданного счёта не меняется.

У СБП сначала подготавливаются реквизиты; у крипты готовность зависит от настроек, курса и допуска аккаунта. Отсчёт срока начинается с готовности реквизитов, не с нажатия на ссылку.

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

GET /api/v1/payments/{payment_id}

Возвращает текущий статус, а также payment_url (страница оплаты) и qr_url (QR-код), когда платёжная сессия сформирована. Опрашивайте метод, пока не получите payment_url.

Проверка оплаты вместо webhook

Автоматический исходящий webhook мерчанту сейчас не реализован. redirect_url не запускает отправку POST-запроса. Не выдавайте товар по переходу покупателя или его сообщению об оплате. Ваш сервер должен запросить статус, проверить принадлежность заказа и ожидаемые amount/total, затем обработать PAID однократно.

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

PENDING : ожидает оплаты, ссылка и QR готовы
WAITING_ADMIN_INPUT : платёж создан, сессия формируется
CHECKING : покупатель сообщил об оплате; поступление ещё проверяется
PAID : оплачен
CANCELLED : отменён

Ошибки

403 : проект не одобрен или не выполнены требования доступа
429 : лимит запросов или пауза между счетами СБП. Для invoice_cooldown дождитесь указанного в сообщении времени; для лимита запросов используйте Retry-After.
401 : неверный или отсутствующий X-API-Key
404 : платёж не найден
409 : платёж с таким order_id уже существует или не задан курс криптовалюты
422 : неверные поля запроса

Ошибки маршрутизации также возвращаются в JSON: 404 not_found, 405 method_not_allowed (с заголовком Allow). Непредвиденная ошибка: 500 internal_error; технические детали и секреты в ответ не включаются.

Примеры

Ключ, запрос и ответ. Больше ничего не требуется.

Создание счёта

curl https://lunopay.cc/api/v1/payments/create_sbp \
  -H "X-API-Key: $LUNOPAY_API_KEY" \
  -H "User-Agent: sbp-api" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "shop-1",
    "amount": 1000,
    "order_id": "ORDER-1337",
    "telegram_user_id": 7396843811,
    "redirect_url": "https://shop.example/hook"
  }'

Ответ

{
  "id": "luno_ab12cd34",
  "total": 1500.00,
  "status": "WAITING_ADMIN_INPUT"
}

Статус и ссылка на оплату

curl https://lunopay.cc/api/v1/payments/luno_ab12cd34 \
  -H "X-API-Key: $LUNOPAY_API_KEY" \
  -H "User-Agent: sbp-api"

# когда сессия готова
{
  "status": "PENDING",
  "payment_url": "https://lunopay.cc/sbp/luno_ab12cd34",
  "qr_url": "https://lunopay.cc/qr/luno_ab12cd34.png"
}

Python

import os
import requests

r = requests.post(
    "https://lunopay.cc/api/v1/payments/create_sbp",
    headers={"X-API-Key": os.environ["LUNOPAY_API_KEY"], "User-Agent": "sbp-api"},
    json={"project_id": "shop-1", "amount": 1000, "order_id": "ORDER-1337"},
)

print(r.json()["id"])

Sandbox: QR без реальной оплаты

Проверяйте создание счёта, показ QR и обработку статусов без банковских переводов. Открыть песочницу: выпустите отдельный ключ luno_test_.... Нужен вошедший пользователь с подтверждённой почтой и доступом аккаунта. Ключи показываются один раз, храните их только на своём сервере.

Никаких рублей на балансе. Sandbox хранит отдельные тестовые записи, не создаёт Payment, резерв, выплату и реферальное начисление. QR содержит текст LUNOPAY_SANDBOX:NOT_A_PAYMENT:sbx_..., а не ссылку СБП, банка или кошелька. PAID является симуляцией. В реальном API тестовые ключи не работают, боевые ключи в sandbox также не принимаются.

1. Создать тестовый счёт

curl -X POST "https://lunopay.cc/api/sandbox/v1/payments/create_sbp" \
  -H "X-API-Key: $LUNOPAY_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"demo-shop","order_id":"TEST-1","amount":100,"description":"Тест интеграции"}'

Поля: project_id и order_id до 120 символов, amount от 0,01 до 1000 с двумя знаками после запятой, необязательное description до 300 символов. Тестовый project_id не создаёт и не меняет боевой проект. Лимит суммы сохранён для совместимости с СБП. Боевой 15-секундный cooldown и производственные квоты не расходуются.

{
  "id": "sbx_example",
  "environment": "sandbox",
  "sandbox": true,
  "balance_effect": false,
  "status": "PENDING",
  "amount": 100,
  "fee": 0,
  "total": 100,
  "payment_url": "https://lunopay.cc/sandbox/pay/sbx_example",
  "qr_url": "https://lunopay.cc/sandbox/qr/sbx_example.png",
  "qr_payload": "LUNOPAY_SANDBOX:NOT_A_PAYMENT:sbx_example",
  "sbp_url": null
}

Сохраните настоящий id из ответа в переменную INVOICE_ID. URL выше являются примером. Новый счёт: HTTP 201; повтор с тем же order_id и теми же параметрами: HTTP 200 и тот же id. Другие параметры для того же order_id: HTTP 409.

2. Задать тестовый статус

curl -X POST "https://lunopay.cc/api/sandbox/v1/payments/$INVOICE_ID/simulate" \
  -H "X-API-Key: $LUNOPAY_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"PAID"}'

Статусы: PENDING, PAID, CANCELLED, EXPIRED. Только владелец может их задавать. Можно вернуть PENDING и повторить тест. То же действие доступно на странице счёта после входа владельца. Открытие QR ничего не меняет.

3. Проверить статус из вашего backend

curl "https://lunopay.cc/api/sandbox/v1/payments/$INVOICE_ID" \
  -H "X-API-Key: $LUNOPAY_SANDBOX_KEY"

Webhook не отправляется, используйте опрос API. Публичную страницу после смены статуса обновите. Тестовые статусы не истекают автоматически. Не проверяйте реальную оплату по sandbox-ответам: ожидайте environment=sandbox только в тестовом окружении.

Ограничения песочницы: 60 API-запросов в минуту на аккаунт, 120 на IP, до 1000 сохранённых тестовых счетов и 5 активных тестовых ключей. Лимиты отдельные от боевого API. HTTP 401: неверный ключ, 403: доступ аккаунта, 404: счёт отсутствует или принадлежит другому аккаунту, 409: конфликт заказа/квота, 422: неверные поля, 429: повторите после Retry-After. Очистка в песочнице удаляет только ваши тестовые счета, отзыв ключа не затрагивает боевые ключи.