Руководство по настройке QryptoPay

QryptoPay — это self-hosted криптоэквайринг для автоматического приёма платежей в криптовалюте на вашем сайте. Модуль позволяет быстро интегрировать оплату: вы сможете автоматически формировать ссылки на оплату, отправлять их клиентам и принимать средства напрямую на свои личные криптокошельки.

Решение полностью разворачивается на вашем сервере, что обеспечивает полный контроль над средствами и повышенный уровень безопасности.

Что нужно, чтобы начать

QryptoPay является модулем панели управления BeAdmin. Для корректной работы сервиса потребуется:

• сервер с установленной панелью BeAdmin (см. руководство по установке);
• доменное имя, направленное на этот сервер (например, qpay.mysite.com).

⚠️ Важно

Доменное имя используется как адрес платёжной страницы, на которую будут перенаправляться клиенты для совершения оплаты. Эта страница работает на том же сервере, где установлен QryptoPay. Если доменное имя отсутствует, его можно добавить позже.

Шаг 1. Установка модуля

Для корректной работы QryptoPay необходимо установить следующие модули:

• DOCKER — обязателен, так как QryptoPay работает на основе docker-контейнеров;
• NGINX — может быть установлен позже, однако без него невозможно запустить платёжную страницу.

Для установки каждого модуля перейдите в соответствующий раздел бокового меню и нажмите кнопку Установить. Модули необходимо устанавливать последовательно, один за другим.

После успешной установки всех зависимостей вернитесь в модуль QryptoPay и запустите установку самого модуля.

Шаг 2. Создание магазина

После успешной установки QryptoPay создайте магазин. Для этого нажмите кнопку Создать и укажите любое удобное название (при необходимости его можно изменить позже).

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

После создания магазина вы сможете перейти к его дальнейшей настройке.

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

• два терминала: основной и тестовый — используются для настройки и проверки подключения к вашему проекту;
• раздел клиентов — предназначен для отслеживания плательщиков (данные зависят от выбранного терминала);
• раздел платежей — используется для просмотра и анализа платежей (данные зависят от выбранного терминала);
• раздел кошельков — служит для настройки способов оплаты и приёма платежей (доступен только для основного терминала).

ℹ️ Примечание

Тестовому терминалу для работы не требуются кошельки, поэтому их создание для него не предусмотрено.

Для полноценной работы с магазином необходимо подключить ваш проект к терминалу и добавить как минимум один кошелёк.

Шаг 3. Настройка интеграции

Ключевой элемент интеграции — терминал. У каждого терминала есть следующие параметры:

• ID — уникальный идентификатор;
• Пара токенов — публичный и приватный (используются для идентификации платежей);
• Вебхук — URL-адрес вашего проекта, на который QryptoPay отправляет уведомления о статусах платежей;
• Ключ для вебхука — используется для авторизации уведомлений на вебхуке.

⚠️ Важно

Приватный токен необходимо хранить в надёжном месте. Если он будет скомпрометирован, злоумышленники могут нарушить логику обработки ваших платежей. Поэтому после генерации QryptoPay не хранит приватный токен на своей стороне.

В случае утери или компрометации вы можете сгенерировать новую пару токенов — не забудьте обновить значения на стороне вашего проекта.

Ключ для вебхука менее критичен, но также рекомендуется не раскрывать его третьим лицам, чтобы исключить подделку уведомлений на вебхук.

Рекомендуем начинать подключение с тестового терминала — в отличие от основного, он позволяет проверить корректность интеграции без фактического перевода криптовалюты.

Сначала сгенерируйте пару токенов для тестового терминала и сохраните у себя приватный токен.

В настройках вашего проекта сохраните параметры терминала в переменных окружения. Например, файл .env может выглядеть так:

TERMINAL_ID: <ID терминала>
PRIVATE_TOKEN: <сгенерированный приватный токен>
WEBHOOK_KEY: <ключ для вебхука из настроек>
PAYMENT_URL: <домен платежной страницы>

Далее в проекте необходимо добавить метод генерации подписи запроса на оплату. Это функция, которая на основе приватного токена и ID терминала формирует уникальную подпись, которую можно безопасно передавать без дополнительного шифрования.

Пример реализации метода генерации подписи на псевдокоде:

function generate_token(private_key_b64, terminal_uuid) -> string
  # декодируем приватный ключ из base64/base64url в seed (сырые байты)
  seed := decode_base64_any(private_key_b64)

  # генерируем уникальный nonce (обычно uuid4)
  nonce := uuid_v4()

  # собираем payload (обязательные поля)
  payload := {
    ts: current_unix_time_seconds(),
    nonce: nonce,
    terminal_uuid: terminal_uuid
  }

  # сериализуем payload в детерминированное (каноничное) представление байт
  payload_bytes := canonical_encode(payload)

  # кодируем payload в transport-safe формат
  payload_part := base64url_no_padding(payload_bytes)

  # подписываем представление payload (в данной схеме подписывается именно payload_part)
  signature_bytes := sign(seed, bytes(payload_part, ASCII))

  # кодируем подпись
  signature_part := base64url_no_padding(signature_bytes)

  # итоговый формат токена: "<payload_b64u>.<sig_b64u>"
  return payload_part + "." + signature_part
end

⚠️ Важно

Для генерации public_token необходимо передавать 3 обязательных параметра: текущую временную метку, nonce (рекомендуется uuid4) и ID терминала.

Временная метка нужна для расчёта срока жизни ссылки (1 час). Nonce используется для безопасности и предотвращает создание нескольких платёжных намерений по одной ссылке (защита от спама). Без ID терминала QryptoPay не сможет обработать платёж.

Далее потребуется метод генерации ссылки на оплату. Ссылка имеет следующий формат и поддерживает параметры:

https://qpay.mysite.com/?      // домен вашей платежной страницы
    amount_usd=55.1&           // сумма к оплате в USD, в формате 00.00
    payment_mid=...&           // ID транзакции внутри вашего проекта
    public_token=...&          // подпись, созданная вашим методом генерации подписи
    back_to_store_link=...&    // ссылка на ваш сайт, чтобы клиент мог вернуться после оплаты (можно добавить параметры если нужно)
    customer.id=...&           // ID клиента из вашей системы (обязательно)
    customer.email=...&        // email клиента из вашей системы (опционально, для отображения в интерфейсе QryptoPay)
    metadata.any=any           // любые другие параметры, которые вы хотите передать в формате metadata.key=value

⚠️ Важно

Ссылка на оплату использует nonce и отрабатывает только один раз. Если клиент перешёл по ссылке, выбрал валюту и начал процесс оплаты (нажал кнопку Продолжить), изменить параметры платежа уже невозможно. В этом случае клиенту необходимо вернуться на ваш сайт и сформировать новую ссылку на оплату. Такое поведение реализовано в целях безопасности.

⚠️ Важно

Если у клиента изменился email, при очередном платеже QryptoPay найдёт клиента по ID и, в случае несовпадения email, перезапишет данные. Обновлённый email будет применён и к ранее созданным платежам.

Общий алгоритм генерации ссылки на оплату выглядит следующим образом:

• в вашем проекте создаётся платёжное намерение (например, транзакция);
• сумма к оплате конвертируется в USD ( QryptoPay принимает входящие суммы только в USD);
• формируется платёжная ссылка с необходимыми параметрами, которая передаётся клиенту для перехода.

После этого клиент совершает платёж на платёжной странице, а затем может вернуться в магазин. Уведомление об успешном или неуспешном платеже поступит на ваш проект с задержкой, так как транзакции в блокчейне должны дождаться подтверждений сети. Обычно это занимает от 5–10 секунд (Tron, USDT TRC-20) до 10–30 минут (Bitcoin).

На этом этапе вы можете сформировать ссылку на оплату, перейти по ней, выбрать валюту и нажать кнопку оплаты. Если всё настроено корректно, платёж отобразится в вашем магазине QryptoPay в тестовом терминале.

Шаг 4. Настройка вебхука

После того как клиент выполнит оплату, QryptoPay начнёт сканировать блокчейны в поисках соответствующей транзакции. Если оплата выполнена строго по инструкциям на платёжной странице, на вебхук будет отправлено уведомление об успешном платеже.

Уведомление приходит в формате объекта:

{
  "payment_result": payment_result, // результат платежа: success, mismatch, unexpected
  "amount_coins": str(coins),        // сумма в криптовалюте, формат 00.00
  "amount_fiat": str(amount_usd),    // сумма в USD, формат 00.00
  "fiat_code": "USD",                // фиатная валюта
  "coins_asset": "USDC",             // криптовалюта: BTC, ETH, USDT, USDC и т.д.
  "coins_chain": "ETH",              // сеть: BTC, ETH, TRX и т.д.
  "service_id": "qryptopay_pi_uuid",  // внутренний идентификатор платежа в QryptoPay
  "payment_mid": "string",           // ID транзакции в вашем проекте
  "metadata": { "key1": value1, "key2": value2 },
  "customer": {
    "id": "your_id",                 // ID клиента в вашей системе
    "email": "string"                // email клиента, null если не был передан
  }
}

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

⚠️ Важно

Если в QryptoPay уже сохранён email клиента, но в очередном платеже email не передан, на вебхук будет отправлен email из базы QryptoPay.

Далее на стороне вашего проекта требуется метод, который проверяет подпись входящих уведомлений. Вместе с объектом приходит заголовок TerminalPrivateKey: Token <base64url("uuid:token")> — он содержит токен подписи, который можно использовать для проверки валидности сообщения.

Пример реализации на псевдокоде:

function decode_terminal_credentials(header_value) -> (terminal_uuid, webhook_token)
  # извлекаем base64/base64url часть после префикса "Token "
  encoded_part := trim(substring_after(header_value, "Token "))

  # декодируем base64/base64url в UTF-8 строку
  decoded_string := utf8_decode(decode_base64_any(encoded_part))

  # ожидаемый формат строки: "uuid:token"
  parts := split(decoded_string, ":", limit = 2)

  terminal_uuid := parts[0]
  webhook_token := parts[1]

  return (terminal_uuid, webhook_token)
end

ID терминала и ключ для вебхука используются для проверки уведомлений о платеже, поступающих на вебхук.

Далее на стороне вашего проекта необходимо реализовать метод, который сможет корректно обработать входящее уведомление. Возможны три сценария:

• success — оплата прошла успешно. В этом случае рекомендуется сверить значение amount_fiat, полученное в уведомлении, с вашей внутренней суммой перед финализацией платежа;
• mismatch — клиент недоплатил или переплатил указанную сумму;
• unexpected — клиент перевёл средства на кошелёк без предварительного формирования платёжной ссылки.

Логику обработки каждого сценария вы можете определить самостоятельно. Например, в случае mismatch можно сравнить сумму из уведомления с ожидаемой суммой и, если оплата была неполной, уведомить клиента о необходимости доплаты. В случае unexpected возможен вариант автоматического пополнения баланса клиента с последующим уведомлением о платеже.

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

Если уведомление успешно получено на стороне вашего проекта, тестовую интеграцию можно считать завершённой.

Шаг 5. Настройка кошельков

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

Подробная инструкция по добавлению и настройке кошельков доступна по ссылке.

Шаг 6. Настройка основного терминала

После добавления кошельков вы можете перевести сайт на работу с основным терминалом. Для этого выполните следующие действия:

• сгенерируйте новую пару токенов для основного терминала;
• отредактируйте настройки терминала и укажите адрес вебхука;
• замените в файле .env вашего проекта значения ID, PRIVATE_TOKEN и WEBHOOK_KEY на данные из основного терминала.

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

Если все настройки выполнены корректно, платёж будет успешно зачислен в вашем проекте.