Платёжные ссылки: руководство

Что такое ссылка

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

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

У ссылки есть своя валюта — та, в которой видит и платит покупатель. Каждый платёж фиксирует курс в момент создания. Текущие курсы — на странице «Курсы валют».

Создание ссылки в кабинете

В личном кабинете откройте раздел «Платёжные ссылки» и настройте ссылку. Доступны такие режимы:

• Сумма: фиксированная или вводимая клиентом, с минимумом и максимумом.
• Лимит оплат: без лимита, одна оплата или N оплат.
• Срок: 1, 7 или 30 дней, либо без срока.
• E-mail покупателя: не спрашивать, необязательно или обязательно.

У каждой ссылки есть свой адрес: https://qvard.com/l/<slug>. Клиент открывает его, выбирает токен и сеть, а дальше видит обычную страницу оплаты.

Ссылку можно скачать как QR-код в формате PNG — для печатных счетов, чеков и плакатов. Кнопка «Поделиться» даёт ссылку, которую можно отправить в любом канале.

Ссылка на каждого покупателя через API

Чтобы точно знать, кто платит, создайте платёж для каждого покупателя через API с вашего сервера и отправьте покупателю redirectUrl из ответа. Секретный ключ (qvard_sk_…) должен храниться только на сервере.

Пример запроса

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

В ответе приходит id платежа и redirectUrl вида https://my.qvard.com/pay/<uuid>. Отправьте покупателю именно redirectUrl. Значение id в запросе — ваш номер заказа.

Никогда не вставляйте секретный ключ (qvard_sk_…) в код, который выполняется в браузере, и в публичный репозиторий. Создавайте платежи только с сервера.

Ограниченная продажа и одноразовая ссылка

Одноразовая ссылка принимает одну оплату — это подходит для счёта. Ссылка с лимитом N оплат принимает N оплат и после этого останавливается — это подходит для ограниченного предложения, например 100 мест.

Статусы ссылки

• Активна: ссылка принимает оплаты.
• Отключена: вы выключили ссылку в кабинете. Она не принимает оплаты, пока вы её снова не включите.
• Истекла: срок (1, 7 или 30 дней) прошёл.
• Исчерпана: достигнут лимит оплат.

Вебхук для платежей из ссылки

Платежи, созданные из ссылки, используют тот же вебхук и тот же заголовок X-Qvard-Signature. В теле таких платежей есть два дополнительных необязательных поля: paymentLink — slug ссылки и customerEmail — e-mail, который ввёл клиент, если ссылка его запрашивала. У платежей не из ссылки этих полей нет.

Как проверить подпись вебхука

Чего ссылка не говорит

Многоразовая ссылка не показывает, кто заплатил. Вебхук сообщает о платеже, а не о покупателе.

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

Справочник API