Всё для интеграции в одном месте

LunaPay — REST API для приёма платежей через единый слой провайдеров. Вся документация для разработчиков — на этой странице.

• Auth

  JWT · X-Api-Key · Idempotency-Key

• Платежи

  POST /payments

• Webhooks

  HMAC · timestamp · retry

• Ошибки

  { code, message, request_id }

1. 1

   Регистрация

   Зарегистрируйте мерчанта (POST /auth/register) или через веб. После одобрения администратором статус станет ACTIVE.

2. 2

   API-ключ

   В кабинете: Магазины → создайте магазин (API-ключ lpy_… выдаётся сразу). Полный ключ показывается один раз; дальше — перегенерация на странице магазина. Тестовый/боевой режим и способы оплаты (altyn_vale, sbp, crypto) настраиваются в карточке магазина.

3. 3

   Первый платёж

   POST /payments с Idempotency-Key, затем редирект покупателя на checkout_url. Метод можно не передавать — покупатель выберет на checkout; либо задать payment_method / ?method= в URL.

4. 4

   Уведомления

   Подключите webhook-endpoint и проверяйте подпись HMAC. Для надёжности используйте polling статуса.

Для серверных интеграций используйте API-ключ. JWT подходит для сессий кабинета.

• Merchant API key

  Заголовок X-Api-Key: lpy_…

• User JWT

  Authorization: Bearer <access> после /auth/login

• Idempotency-Key

  Обязателен при создании платежа — уникален на бизнес-операцию

Тестовый или боевой режим и список методов включаются в карточке магазина. Ключ один (lpy_…) — без отдельных test/live ключей. Админ может закрыть метод для всего мерчанта.

Создайте платёж, получите checkout_url и перенаправьте покупателя на hosted checkout. Доступные method_id: altyn_vale, sbp, crypto (если включены в магазине).

1. POST /payments с amount, currency, order_id, return_url; payment_method опционален (altyn_vale | sbp | crypto)
2. Передайте Idempotency-Key в заголовке и X-Api-Key магазина
3. Редирект на checkout_url; можно добавить ?method=sbp (или ?provider= для crypto)
4. Дождитесь payment.paid (webhook) или опросите статус

Ответ содержит id платежа и checkout_url. Cascade провайдеров стартует после выбора метода на checkout (или сразу, если метод уже задан и не crypto).

Примеры

curl -X POST 'https://t-ncid.ru/api/v1/payments' \
  -H 'X-Api-Key: lpy_…' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1500.00,
    "currency": "RUB",
    "payment_method": "sbp",
    "order_id": "ord_123",
    "return_url": "https://shop.example/done"
  }'

Платформа доставляет события на ваш endpoint с HMAC-подписью и защитой от replay.

1. Создайте endpoint в кабинете и сохраните секрет whsec_… (показывается один раз)
2. Сравните X-Tncid-Signature = t=<ts>,v1=<hmac> по строке ${timestamp}.${rawBody}
3. Отклоняйте запрос, если |now − ts| > 300 секунд
4. Обрабатывайте идемпотентно по payload.id или (payment_id, type)

Проверка подписи

HMAC-SHA256 от сырого тела запроса с секретом endpoint. При несовпадении отвечайте 401.

# X-Tncid-Signature: t=<unix>,v1=<hex>
# signed payload = "{t}.{rawBody}"
expected = HMAC_SHA256(whsec, f"{t}.{raw_body}")

События

Повторы: 1м, 5м, 15м, 1ч, 6ч → DEAD. Дубликаты не вызывают повторный переход статуса.

GET /payments/:id/status — не полагайтесь только на webhooks. Используйте polling для сверки и восстановления после сбоев доставки.

GET /api/v1/payments/:id/status

Все ошибки API возвращают единый JSON. Сохраняйте request_id для поддержки.

{
  "code": "VALIDATION_ERROR",
  "message": "amount must be positive",
  "request_id": "req_01H…"
}

Зарегистрируйтесь или войдите — ключи, магазины и webhooks настраиваются в кабинете.