Как подключить платёжные ссылки

Платёжная ссылка — это адрес, который вы отдаёте покупателю вместо того, чтобы создавать платёж на каждую покупку. Покупатель открывает ссылку, указывает сумму в заданных пределах и оплачивает. Результат приходит вам вебхуком.

Ссылка бывает двух видов:

одноразовая — одна транзакция на всю ссылку, подходит для счёта на конкретный заказ;

многоразовая — принимает новые платежи, пока активна, подходит для приёма оплат из профиля или чата.

Шаг 1. Подготовьте доступ

Понадобится идентификатор магазина и его API-ключ. Оба передаются заголовками X-MerchantId и X-Secret в каждом запросе. Ключ держите на сервере: покупателю и в браузер он попадать не должен.

Создание ссылок должно быть включено вашему магазину, а многоразовые ссылки включаются отдельно. Если запрос возвращает PaymentLink:LINK_UNAVAILABLE, подключение нужно уточнить у вашего менеджера.

Шаг 2. Укажите адрес для уведомлений

В личном кабинете откройте Настройки → Callback URLs и укажите публичный HTTPS-адрес, на который мы будем отправлять результат платежей. Отдельный адрес в запросе на создание ссылки не передаётся — используется общий адрес магазина.

Без этого шага ссылка будет работать, но о результате оплаты вы узнаете только опросом API.

Шаг 3. Создайте ссылку

Запрос выполняется с вашего сервера. Заголовок Idempotency-Key обязателен: он защищает от задвоения при повторной отправке.

Это одноразовая ссылка с фиксированным способом оплаты и фиксированной суммой: равные minAmount и maxAmount не дают покупателю изменить сумму.

Многоразовая ссылка с выбором способа на форме отличается двумя полями:

Доступны все четыре сочетания: в первом примере поставьте usageMode: 0 и уберите orderId — получится многоразовая с фиксированным способом; во втором поставьте usageMode: 1 — одноразовая с выбором способа.

Значения диапазона в примерах условные: действуют также лимиты выбранного способа оплаты.

Шаг 4. Передайте покупателю url

В ответе придёт объект ссылки. Покупателю передавайте именно поле url.

{
  "id": "11111111-2222-4333-8444-555555555555",
  "url": "https://pay.example.com/l/<PUBLIC_TOKEN>",
  "usageMode": 0,
  "paymentMode": 1,
  "paymentMethod": 2,
  "currency": "RUB",
  "minAmount": "1500",
  "maxAmount": "1500",
  "active": true,
  "revision": "1"
}

Ответ сокращён, домен и токен условные. Поле id — это идентификатор ссылки, а не платежа: по нему вы потом читаете состояние и отключаете ссылку. revision — версия состояния, она понадобится при отключении.

Сохраните id у себя рядом с заказом: он приходит в каждом уведомлении полем paymentLinkId.

Шаг 5. Обработайте уведомление

Когда покупатель оплатит, на ваш адрес придёт POST с результатом. Ключ дедупликации — поле id самого платежа, не paymentLinkId: у многоразовой ссылки платежей много, а идентификатор ссылки у них один и тот же.

Ответьте 200 OK и выполните бизнес-действие ровно один раз для этого платежа. Подробности, список статусов и правила повторов — на странице «Вебхуки по платёжным ссылкам».

Шаг 6. Проверьте результат и при необходимости отключите ссылку

Состояние ссылки читается по её идентификатору. Там же видно, израсходована ли одноразовая ссылка: поля consumedAt и consumedTransactionId. Важно: израсходована — это не то же самое, что оплачена. Статус оплаты смотрите по платежу.

Все платежи по ссылке доступны отдельным эндпоинтом — удобно для сверки, если уведомление не дошло.

Чтобы ссылка перестала принимать платежи, вызовите отключение и передайте текущую revision. Если версия устарела, придёт PaymentLink:LINK_STATE_CHANGED — перечитайте ссылку и повторите.

Частые ошибки

Код	Что проверить
`PaymentLink:INVALID_REQUEST`	Неизвестное поле в теле, неверный тип, `paymentMode` не передан. `usageMode` и `paymentMode` — числа, не строки.
`PaymentLink:INVALID_AMOUNT`	`minAmount` больше `maxAmount`, лишние знаки после точки, суммы переданы числом вместо строки.
`PaymentLink:METHOD_NOT_ALLOWED`	Способ не подключён магазину или недоступен для выбранного режима ссылки.
`PaymentLink:LINK_UNAVAILABLE`	Создание ссылок или многоразовые ссылки не включены магазину.
`PaymentLink:LINK_ALREADY_USED`	Одноразовая ссылка уже израсходована. Нужна новая.
`PaymentLink:IDEMPOTENCY_CONFLICT`	Тот же `Idempotency-Key` с другими параметрами. Для новой ссылки нужен новый ключ.
`PaymentLink:LINK_STATE_CHANGED`	Переданная `revision` устарела.

Сохраняйте code и traceId из ответа: с ними поддержка разберётся быстрее.

О чём легко забыть

Одноразовая ссылка расходуется в момент создания платежа, до успешной оплаты. Отмена или неуспех её не возвращают — нужна новая ссылка.

Часть способов оплаты для ссылок недоступна, и набор ограничений зависит от режима ссылки. Какие способы доступны вам — уточняйте у вашего менеджера.

orderId допустим только у одноразовой ссылки и не заменяет payload: в уведомлениях возвращается именно payload.

Переход покупателя на return или failedUrl оплату не подтверждает. Решение принимайте по уведомлению и данным API.

Как подключить платёжные ссылки

Шаг 1. Подготовьте доступ#

Шаг 2. Укажите адрес для уведомлений#

Шаг 3. Создайте ссылку#

Шаг 4. Передайте покупателю url#

Шаг 5. Обработайте уведомление#

Шаг 6. Проверьте результат и при необходимости отключите ссылку#

Частые ошибки#

О чём легко забыть#