Создание платежа

POST /v1/payments - платёж и ссылка на оплату

POST/api/v1/payments

Описание

Создаёт платёж и возвращает ссылку на платёжную страницу. Сам запрос денег не списывает: оплата происходит, когда покупатель открывает payUrl и выбирает способ.

Авторизация - заголовок X-Api-Key (подробнее).

Параметры запроса

orderId

string, обязательный

Номер заказа в вашей системе, от 1 до 64 символов. Уникален в рамках магазина: повторный orderId - ошибка 409, платежи не задваиваются.

amountKopecks

integer, обязательный

Сумма в копейках, целое число. Минимум 100 (1 рубль), максимум 10 000 000 000 (100 миллионов рублей).

description

string, необязательный

Назначение платежа, до 255 символов. Показывается покупателю на платёжной странице.

string, необязательный

Email покупателя - на него банк может отправить подтверждение операции.

telegramId

integer или string, необязательный

Телеграм-ID покупателя (для ботов): вернётся в объекте платежа и в вебхуке - бот сразу знает, кому выдавать товар. Принимается числом или строкой цифр.

metadata

object, необязательный

Произвольные данные вашей системы (объект JSON, до 4 КБ). Провайдеру не передаются, возвращаются без изменений в объекте платежа и в теле вебхука. Удобно хранить id товара, тариф, id сообщения - без своей таблицы соответствий.

successUrl

string, необязательный

Куда вернуть покупателя после успешной оплаты. Переопределяет ссылку магазина; не задан - берётся ссылка магазина. Поддерживает https, t.me и tg:// - можно вернуть покупателя бота в нужный сценарий диалога.

failUrl

string, необязательный

Куда вернуть покупателя после неудачной оплаты. Правила те же, что у successUrl.

method

string, необязательный

SBP или CARD - зафиксировать способ оплаты заранее. Не задан - покупатель выберет сам. Способ должен быть включён вашему магазину, иначе 409.

Ответ

201 и объект платежа в статусе CREATED. Отправьте покупателя на payUrl - ссылка не сгорает, пока оплата не начата.

Если ответ не дошёл (обрыв сети), не создавайте платёж заново вслепую: сначала запросите его по своему orderId. Повторное создание с тем же orderId безопасно - придёт 409, дубля не будет.

orderId остаётся занят и после отмены платежа: для новой попытки оплаты того же заказа создайте платёж с новым orderId (например, с суффиксом попытки).

curl -X POST https://tabpay.org/api/v1/payments \
  -H "X-Api-Key: tp_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1001",
    "amountKopecks": 19900,
    "description": "Подписка на месяц"
  }'

Ответ 201

{
  "id": "6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "orderId": "order-1001",
  "status": "CREATED",
  "amountKopecks": 19900,
  "commissionKopecks": 1393,
  "description": "Подписка на месяц",
  "method": null,
  "telegramId": null,
  "metadata": { "productId": 42, "tariff": "month" },
  "successUrl": "https://t.me/your_bot?start=paid_order-1001",
  "failUrl": null,
  "payUrl": "https://tabpay.org/pay/6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "paidAt": null,
  "createdAt": "2026-07-11T10:20:30.000Z"
}

Ответ 409

{
  "statusCode": 409,
  "message": "Платёж с таким orderId уже существует",
  "error": "Conflict"
}