Документация API

Приём платежей по СБП: вы создаёте счёт, отправляете покупателя на страницу оплаты, получаете уведомление о зачислении. Три запроса и один обработчик.

https://api.shamanpayments.com

Авторизация

Каждый запрос — с заголовком X-API-Key. Ключ у каждой кассы свой.

X-API-Key: sp_live_ВАШ_КЛЮЧ

ВАШ_КЛЮЧ — не настоящий токен, а место под ваш: ключ выпускается в кабинете и выглядит как sp_live_… (бой) или sp_test_… (тест).

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

POST /v1/invoices

В примере — sp_test_…: так удобнее пробовать. На проде подставьте свой sp_live_… и проверьте, что касса в боевом режиме.

curl -X POST https://api.shamanpayments.com/v1/invoices \
  -H "X-API-Key: sp_test_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "order_id": "order-10241",
    "description": "Заказ №10241",
    "success_url": "https://shop.ru/success",
    "fail_url": "https://shop.ru/fail"
  }'

Ответ 201 Created

{
  "id": "inv_3F8KQ2M1N7XBZ0RTVCWD9E",
  "order_id": "order-10241",
  "status": "pending",
  "mode": "test",
  "amount": 150000,
  "charged_amount": 150000,
  "fee": 18000,
  "net": 132000,
  "currency": "RUB",
  "checkout_url": "https://pay.shamanpayments.com/i/xxxxxxxx",
  "qr_text": null,
  "expires_at": "2026-08-18T15:30:00+00:00",
  "open_until": "2026-08-18T15:30:00+00:00",
  "payment_expires_at": "2026-08-18T15:30:00+00:00",
  "ttl_source": "merchant",
  "paid_at": null
}

Отправьте покупателя на checkout_url — там уже есть QR, таймер и возврат в ваш магазин.

Сумма сверх лимита — это 422 с понятным текстом, а не отказ на стороне банка: счёт в таком случае не создаётся вовсе.

Статус счёта

GET /v1/invoices/{invoice_id}
GET /v1/orders/{order_id}
POST /v1/invoices/{invoice_id}/cancel

Второй метод пригодится, когда ответ на создание потерялся: вместо повторного создания спросите, что стало с заказом.

Вебхуки

Адрес обработчика задаётся на кассе. Там же при создании подписки один раз показывается секрет — им подписываются уведомления. Мы отправляем POST с JSON и ждём любой ответ 2xx. Не получили — повторим по расписанию 0, 1, 5, 30, 120, 360 минут.

{
  "id": "evt_3F8KQ2M1N7XBZ0RTVCWD9E",
  "event": "payment.succeeded",
  "created_at": "2026-08-18T15:04:11+00:00",
  "mode": "live",
  "data": {
    "invoice_id": "inv_3F8KQ2M1N7XBZ0RTVCWD9E",
    "order_id": "order-10241",
    "status": "paid",
    "amount": 150000,
    "charged_amount": 150000,
    "fee": 18000,
    "net": 132000,
    "currency": "RUB",
    "paid_at": "2026-08-18T15:04:10+00:00",
    "metadata": null
  }
}

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

Проверяйте её обязательно: без этого кто угодно, узнав ваш адрес, сможет прислать поддельное «оплачено».

X-ShamanPay-Signature: sha256=<hex>
X-ShamanPay-Timestamp: 1787060000
X-ShamanPay-Event: payment.succeeded
X-ShamanPay-Delivery: dlv_...

signature = HMAC_SHA256(secret, "{timestamp}.{сырое тело запроса}")

import hmac, hashlib

def verify(secret: str, signature: str, timestamp: str, raw_body: bytes) -> bool:
    payload = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Апелляции

Покупатель перевёл деньги, а счёт не закрылся — например, заплатил под конец окна оплаты или чек ещё проверяется. Приложите чек, выписку или видео перевода: мы передадим апелляцию шлюзу и закроем счёт, когда оплату признают. Подать можно в любом статусе счёта, кроме оплаченного. То же самое доступно в кабинете — кнопка «Подать апелляцию» в карточке операции.

POST /v1/invoices/{invoice_id}/appeals
GET  /v1/invoices/{invoice_id}/appeals
GET  /v1/appeals/{appeal_id}

Подача

Запрос — multipart/form-data. Повтор того же файла по той же попытке вернёт уже поданную апелляцию с кодом 200 вместо 201: ретрай при таймауте не создаёт вторую.

curl -X POST https://api.shamanpayments.com/v1/invoices/inv_3F8KQ2M1N7XBZ0RTVCWD9E/appeals \
  -H "X-API-Key: sp_live_ВАШ_КЛЮЧ" \
  -F "file=@receipt.pdf;type=application/pdf" \
  -F "amount=150000" \
  -F "comment=Списано в 20:58 со Сбера"

Ответ

{
  "id": "apl_3F8KQ2M1N7XBZ0RTVCWD9E",
  "invoice_id": "inv_3F8KQ2M1N7XBZ0RTVCWD9E",
  "order_id": "order-10241",
  "payment_id": "pay_3F8KQ2M1N7XBZ0RTVCWD9E",
  "status": "sent",
  "status_label": "На рассмотрении",
  "channel": "auto",
  "amount": 150000,
  "comment": "Списано в 20:58 со Сбера",
  "file_name": "receipt.pdf",
  "error": null,
  "resolution_note": null,
  "created_at": "2026-10-21T15:04:11+00:00",
  "resolved_at": null
}

channel: auto — передана шлюзу автоматически, обычно отвечает за минуты; support — через его поддержку, ответ — в течение часа днём, дольше по старым заявкам. Отдельного вебхука по апелляции нет: когда оплату признают, придёт обычный payment.succeeded по счёту. Статус апелляции можно спросить в любой момент.

Тестовый режим

Тестовый ключ доступен сразу после подключения, до проверки компании. Счета создаются как настоящие, на странице оплаты есть кнопка «Оплатить (тест)» — она проводит полный цикл вместе с вебхуком.

Ошибки

{"status": "failed", "error_message": "Минимальная сумма платежа — 10,00 ₽"}