Платежи
Типичный сценарий
1.
POST /api/v1/integration/transactions — создать платёж.2.
3.
4.
GET /api/v1/integration/transactions/{uuid}GET /api/v1/integration/transactions/by-external-id/{externalId}Создание платежа
external_id.external_id должен быть уникален в рамках мерчанта: так вы сможете безопасно повторять create при сетевых сбоях и потом найти платёж без UUID Smerch.integrationCreateTransaction).Идентификатор плательщика
metadata.userId:{
"metadata": {
"userId": "customer-12345"
}
}metadata.userId.IP-адрес плательщика
metadata.clientIp. Smerch передаёт его платёжному провайдеру; без него провайдер видит только IP вашего сервера. Международному карточному эквайрингу нужен реальный IP плательщика, чтобы выдать прямую ссылку на оплату, — без него платёж может быть отклонён.{
"metadata": {
"clientIp": "203.0.113.24"
}
}Кассы Telegram Stars
metadata.userId Telegram ID покупателя в формате tg<числовой ID>:{
"metadata": {
"userId": "tg123456789"
}
}@name) и не ваш внутренний идентификатор.metadata.userId или в другом формате (123456789, TG123, @name) платёж отклоняется с HTTP 422.Payments for this Telegram user are blocked.Валюта и рублёвый рельс (СБП)
| Запрос | Что происходит |
|---|---|
currency=RUB, amount в копейках | Плательщик оплачивает рублёвую сумму, ledger отражает рублёвое списание. |
payment_method=crypto | Клиент оплачивает поддерживаемым криптоактивом в выбранной сети. Используйте payment_url или requisites из ответа. |
requisites.Платежи через СБП
payment_method=sbp, currency=RUB и сумму в копейках.payment_url для редиректа. Финальный статус подтверждайте webhook-ом.Crypto-платежи
payment_method=crypto. Если API возвращает payment_url, перенаправьте клиента на него. Если возвращается объект requisites, используйте адрес, сеть, сумму и срок действия из ответа API.Комиссия за счёт покупателя
gross_amount). Провайдеры удерживают свою комиссию со всей суммы счёта, включая эту надбавку, поэтому надбавка увеличивается на ставку провайдера, а итоговая сумма округляется вверх до целого рубля (доллара). Точная разбивка приходит в merchant_fee_customer_amount и merchant_fee_merchant_amount; сумма, которую получит мерчант (net_amount), от этого не меняется.Статусы
pending, paid, failed, expired, refunded, chargeback. Ориентируйтесь на финальные значения из webhook/GET.Промежуточные статусы нормальны: платёж может «висеть», пока провайдер не подтвердит оплату.
Список платежей
GET /api/v1/integration/transactions — cursor-пагинация. Фильтр status принимает только значения из таблицы выше. Используйте список для сверки и кабинета, не как замену webhook.Реквизиты «как есть» (H2H)
GET /api/v1/integration/transactions/{uuid}/h2hЕсли у метода есть redirect URL — часто достаточно редиректа, H2H не обязателен.
Рекуррентные платежи (СБП)
1. Создание мандата
POST /api/v1/integration/subscriptions принимает сумму в копейках, только currency=RUB и один из интервалов:403.sbp_recurring со своим тарифом (комиссия, распределение комиссии, hold), который администратор Smerch настраивает независимо от обычного СБП. Изменение тарифа обычного СБП не влияет на рекурренты. Каждый мандат сохраняет тариф на момент создания, поэтому последующие изменения применяются только к новым мандатам. Через POST /integration/transactions метод sbp_recurring недоступен — только через API подписок.interval | Допустимый interval_count | Пример |
|---|---|---|
day | 1–31 | каждые 7 дней |
week | 1–4 | каждые 2 недели |
month | 1–12 | каждый месяц |
year | 1–3 | каждый год |
{
"external_id": "membership-1001",
"amount": 50000,
"currency": "RUB",
"email": "customer@example.com",
"interval": "month",
"interval_count": 1,
"description": "Premium membership",
"metadata": { "customer_id": "customer-42" },
"callback_url": "https://merchant.example/webhooks/smerch"
}external_id должен быть стабильным и уникальным внутри мерчанта. Повтор запроса с тем же external_id и тем же телом вернёт тот же мандат; другое тело с уже занятым external_id вернёт 409 Conflict.email, если хотите сразу начать оформление согласия. Если не передать email, Smerch автоматически вернёт payform_url: наша форма соберёт email плательщика. collect_email_on_payform: true остаётся необязательным явным переключателем этого режима. Ссылка содержит случайный токен, действует 30 минут и не раскрывает секрет мерчанта. interval_count по умолчанию равен 1, а description можно не передавать.email передан, в ответе будет confirmation_url — откройте его плательщику, чтобы он подтвердил согласие в своём банке. Если email не передан (или collect_email_on_payform=true), отправьте плательщика на payform_url: форма запросит email и сама перенаправит его на подтверждение. Если all_providers_unavailable=true, confirmation_url будет null: сейчас оформить согласие нельзя, мандат останется pending_agreement — создайте новый мандат позже. Финальное согласие подтверждается только webhook-событием subscription.status_updated или последующим GET.2. Состояния мандата
| Статус | Значение |
|---|---|
creating | внутреннее создание ещё выполняется |
pending_agreement | ожидается подтверждение плательщика |
active | мандат активен, будущие списания разрешены |
past_due | очередное списание не прошло; проверьте транзакцию |
cancelled | будущие списания остановлены |
failed | мандат завершился ошибкой |
creation_unknown | провайдер мог принять запрос, но ответ потерян; не создавайте новый мандат с другим external_id, обратитесь в поддержку |
3. Списания и выдача товара
subscription_uuid связывает её с мандатом. Выдавайте товар только после transaction.status_updated со статусом paid; статус active у мандата не означает, что конкретное списание оплачено.X-Webhook-Id. Если webhook задержался, восстановите состояние через GET /integration/subscriptions/{uuid} и GET /integration/transactions; GET — средство сверки, а не замена webhook.4. Получение и отмена
external_id, вывести списком через GET /integration/subscriptions и идемпотентно отменить через POST /integration/subscriptions/{uuid}/cancel. Для scoped API-ключей нужны права subscriptions:read и/или subscriptions:write.Modified at 2026-10-20 12:21:30