Платежи

Все суммы — целые числа в копейках. Валюта — только RUB.

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

POST https://pay.egnetwork.ru/api/v1/payments

Поле	Тип	Обяз.	Описание
`amount`	integer	да	Сумма в копейках, от `100` (1 ₽) до `1000000000` (10 млн ₽)
`order_id`	string	да	Ваш ID заказа, до 64 символов `[A-Za-z0-9._:-]`. Уникален в пределах сервиса и режима — это ключ идемпотентности
`description`	string	да	Что оплачивает пользователь, до 140 символов. Показывается на странице оплаты и в банке
`return_url`	string (URL)	нет	Куда вернуть пользователя после оплаты. `https`, хост должен быть в `allowed_return_hosts` сервиса (если список задан)
`webhook_url`	string (URL)	нет	Переопределить URL вебхука для этого платежа (только `https`). По умолчанию — URL из настроек сервиса
`methods`	`("sbp" \| "card")[]`	нет	Способы оплаты. По умолчанию `["sbp","card"]`. `["sbp"]` — только QR
`expires_in`	integer	нет	Сколько секунд платёж ждёт оплаты: `300`…`604800`. По умолчанию `3600`
`customer.email`	string	одно из двух	Email покупателя. На него банк отправит чек 54-ФЗ
`customer.phone`	string	одно из двух	Телефон покупателя `+79991234567`. На него банк отправит чек 54-ФЗ
`receipt`	object	нет	Чек 54-ФЗ, см. ниже
`metadata`	object	нет	До 20 пар `string → string` (ключ ≤ 40, значение ≤ 500 символов). Возвращается в объекте и вебхуках

Ответ: 201 Created с объектом платежа. Если платёж с этим order_id уже есть и сумма совпадает — 200 OK с существующим платежом (повтор безопасен).

const res = await fetch("https://pay.egnetwork.ru/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EGN_PAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 49900,
    order_id: `order-${order.id}`,
    description: "Подписка Pro на 1 месяц",
    return_url: "https://example.egnetwork.ru/billing/done",
    customer: { email: user.email },
    metadata: { user_id: String(user.id) },
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const payment = await res.json();
return Response.redirect(payment.payment_url, 302);

import os, requests

r = requests.post(
    "https://pay.egnetwork.ru/api/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['EGN_PAY_KEY']}"},
    json={
        "amount": 49900,
        "order_id": f"order-{order.id}",
        "description": "Подписка Pro на 1 месяц",
        "return_url": "https://example.egnetwork.ru/billing/done",
        "customer": {"email": user.email},
    },
    timeout=20,
)
r.raise_for_status()
payment_url = r.json()["payment_url"]

Идемпотентность

order_id гарантирует, что двойной клик или ретрай после таймаута не создаст второй платёж:

Ситуация	Ответ
`order_id` новый	`201`, новый платёж
`order_id` есть, сумма та же, платёж `pending`/`succeeded`/…	`200`, существующий платёж
`order_id` есть, сумма другая	`409 order_id_conflict`
`order_id` есть, платёж `failed`/`expired`/`canceled`	`409 order_closed` — создайте платёж с новым `order_id`, например `order-1042-2`

Получить платёж

GET https://pay.egnetwork.ru/api/v1/payments/{id}

Используйте как источник правды, если вебхук не дошёл, или для проверки при возврате пользователя на return_url.

Список платежей

GET https://pay.egnetwork.ru/api/v1/payments?order_id=&status=&limit=20&starting_after=

Параметр	Описание
`order_id`	Найти платёж по вашему ID заказа
`status`	Фильтр по статусу
`limit`	1…100, по умолчанию 20
`starting_after`	ID последнего платежа предыдущей страницы

{ "object": "list", "data": [ { "id": "pay_…" } ], "has_more": false }

Отменить платёж

POST https://pay.egnetwork.ru/api/v1/payments/{id}/cancel — только для pending. После отмены QR перестаёт работать, приходит вебхук payment.canceled.

Вернуть деньги

POST https://pay.egnetwork.ru/api/v1/payments/{id}/refund

{ "amount": 10000 }

amount необязателен — без него возвращается весь остаток. Можно делать несколько частичных возвратов. Статус станет partially_refunded или refunded, придёт вебхук с тем же именем. refunded_amount показывает сумму всех возвратов.

Статусы

Статус	Финальный	Значение
`pending`	нет	Ожидает оплаты
`succeeded`	—	Оплачен. Можно выдавать товар
`failed`	да	Банк отклонил оплату
`expired`	да	Истёк `expires_in`, оплаты не было
`canceled`	да	Отменён через API или админку
`partially_refunded`	нет	Оплачен, часть суммы возвращена
`refunded`	да	Вся сумма возвращена

pending ──▶ succeeded ──▶ partially_refunded ──▶ refunded
   │             └──────────────────────────────▶ refunded
   ├──▶ failed
   ├──▶ expired
   └──▶ canceled

Редкий случай: если банк подтвердит оплату уже после того, как платёж стал expired/failed, статус сменится на succeeded и придёт вебхук payment.succeeded. Деньги важнее таймеров — обработайте такой вебхук как обычную оплату.

Чеки 54-ФЗ

Если к терминалу подключена онлайн-касса, Т-Банк ждёт чек. Два варианта:

Автоматически. Если администратор выбрал систему налогообложения (админка → Терминал), EGN Pay сам сформирует чек из одной позиции: description, amount, предмет расчёта «услуга», способ «полный расчёт». Чек уходит на customer.email или customer.phone — поэтому одно из этих полей обязательно в каждом платеже. Без контакта запрос вернёт 422 validation_error.

Явно — передайте receipt:

{
  "amount": 59800,
  "order_id": "order-77",
  "description": "Заказ №77",
  "customer": { "email": "user@example.com" },
  "receipt": {
    "taxation": "usn_income",
    "items": [
      { "name": "Подписка Pro", "price": 49900, "quantity": 1, "tax": "none" },
      { "name": "Доп. слот", "price": 9900, "quantity": 1, "tax": "none", "payment_object": "service" }
    ]
  }
}

Поле	Описание
`taxation`	`osn`, `usn_income`, `usn_income_outcome`, `envd`, `esn`, `patent`
`email` / `phone`	Куда отправить чек. По умолчанию из `customer`
`items[].name`	Название, до 128 символов
`items[].price`	Цена за единицу, копейки
`items[].quantity`	Количество
`items[].amount`	Стоимость позиции. По умолчанию `price × quantity`
`items[].tax`	`none`, `vat0`, `vat5`, `vat7`, `vat10`, `vat20`, `vat22`, `vat105`, `vat107`, `vat110`, `vat120`, `vat122`
`items[].payment_method`	По умолчанию `full_payment`
`items[].payment_object`	По умолчанию `service`

Сумма items[].amount должна равняться amount, иначе 422 receipt_mismatch.

Объект платежа

{
  "id": "pay_8fK2mQ1xZbY7cV3nT0aR",
  "object": "payment",
  "livemode": true,
  "status": "succeeded",
  "amount": 49900,
  "refunded_amount": 0,
  "currency": "RUB",
  "description": "Подписка Pro на 1 месяц",
  "order_id": "order-1042",
  "methods": ["sbp", "card"],
  "customer": { "email": "user@example.com", "phone": null },
  "metadata": { "user_id": "u_123" },
  "payment_url": "https://pay.egnetwork.ru/p/pay_8fK2mQ1xZbY7cV3nT0aR",
  "return_url": "https://example.egnetwork.ru/billing/done",
  "expires_at": "2026-10-27T13:00:00.000Z",
  "paid_at": "2026-10-27T12:03:41.512Z",
  "created_at": "2026-10-27T12:00:00.000Z",
  "updated_at": "2026-10-27T12:03:41.512Z"
}

Markdown-версия этой страницы: /docs/payments.md