Поймите логику платежа и требования
Если вы хотите узнать, как принимать криптовалютные платежи на сайте next.js, начинайте не с кода, а с логики процесса. Обычно криптовалютный checkout состоит из 4 частей: создать заказ, показать запрос на оплату, отслеживать блокчейн и помечать заказ как оплаченный только после проверки.
Звучит просто. На практике — редко.
«Принимать крипту» на сайте на Next.js не означает, что ваше приложение само хранит монеты. В большинстве случаев сайт создаёт для клиента платёжный запрос, клиент отправляет средства из кошелька, а платёжный сервис или ваш собственный backend подтверждает перевод. Хороший checkout также должен иметь таймаут, потому что курс, который был выгодным в 10:00, через 20 минут уже может быть неактуальным.
Ещё нужно понимать, какие сети и активы вы будете поддерживать. Магазин, который принимает USDT в Ethereum, Polygon и BNB Chain, решает совсем другую задачу, чем сайт, который принимает только BTC в одной сети. Выбор сети влияет на комиссии, время подтверждения и тип кошелька, который понадобится клиенту. Если выбрать неправильную сеть, платёж может уйти туда, где вы не сможете связать его с заказом.
Есть простой практический тест: сможет ли новый клиент завершить оплату меньше чем за 2 минуты? Если нет, процесс нужно дорабатывать. Один кошелёк, одна сумма, один понятный адрес, одна понятная страница статуса. Именно такой уровень ясности ожидают люди.
Выберите провайдера криптоплатежей или интеграцию с кошельком
Криптовалютный checkout можно построить тремя основными способами. Первый — hosted checkout от провайдера. Второй — прямая интеграция с кошельком, когда приложение работает с библиотекой кошелька. Третий — платёжный шлюз, который находится между пользователем и блокчейном. У каждого варианта своя стоимость внедрения, и правильный выбор зависит от того, что вам важнее: скорость, контроль или и то и другое.
Hosted checkout обычно быстрее всего запустить. Вы создаёте счёт, отправляете клиента на hosted-страницу, а провайдер сам отслеживает оплату. Прямая интеграция с кошельком может лучше вписываться в продукт, но обычно требует больше кода, больше крайних случаев и больше ответственности за подтверждение платежей. Шлюз находится посередине и часто оказывается самым практичным вариантом для коммерции, потому что он умеет создавать счета, отслеживать подтверждения и отдавать webhooks.
Перед выбором проверьте 5 вещей: поддерживаемые монеты, поддерживаемые сети, поддержку webhook’ов, срок действия счёта и то, сколько backend-кода от вас ожидает провайдер. Если вы сравниваете решения для магазина, полезно начать с гайда по переходу со Stripe, потому что там та же задача показана с точки зрения продавца. Фрилансеру, который выставляет счета клиентам, могут быть важнее инвойсы и платёжные ссылки, чем интернет-магазину, поэтому и подход для криптоплатёжного шлюза для фрилансеров тоже имеет значение.
И ещё один нюанс: если провайдер заявляет поддержку «всех основных активов», попросите точный список. «Все» — слишком расплывчато. «BTC, ETH, USDC в 3 сетях» — это уже решение, с которым можно работать.
Настройте проект Next.js для платежей
Начните с аккуратной структуры приложения. В проекте Next.js с app router держите платёжную логику в серверных маршрутах или server actions и не выносите секретные ключи на клиент. Простая схема может включать 1 страницу товара, 1 форму оформления заказа, 1 API-роут для создания счетов и 1 webhook-роут для событий оплаты.
Переменные окружения должны включать секретный ключ платёжного провайдера, секрет webhook’а и публичные API-значения, которые можно показывать в браузере. Не помещайте секретный ключ в client component. Такая ошибка может поставить под удар весь аккаунт, и это одна из немногих ошибок, которые быстро обходятся дорого.
Если провайдер предлагает SDK, устанавливайте его только на серверной стороне. Если он даёт обычные HTTP endpoints, это тоже подойдёт. Суть одна: браузер просит ваш backend Next.js создать платёжный запрос, а backend уже общается с провайдером. Браузер никогда не должен сам решать, что заказ оплачен.
Для команд, которые переходят с карточных платежей, структура не так уж сильно отличается от потока Stripe — только проверки другие. Если вам помогает такое сравнение, прочитайте как мигрировать со Stripe, прежде чем проектировать API-маршруты. Для прототипа достаточно одного API-роута; когда добавятся повторные попытки, возвраты и история статусов заказа, лучше подойдут 3 или 4.
Создайте интерфейс checkout в Next.js
Интерфейс checkout может быть карточкой товара, страницей корзины или простой кнопкой, которая запускает оплату. В client component Next.js кнопка обычно отправляет данные заказа на серверный маршрут, ждёт ответа и затем либо перенаправляет клиента, либо показывает инструкции для кошелька.
Держите форму короткой. Название товара, сумма, email и, возможно, заметка к заказу — этого часто достаточно. Если просить 9 полей, отток будет выше. Если просить 3, люди завершают оплату быстрее. Checkout, который занимает 30 секунд, воспринимается лучше, чем тот, который длится 3 минуты, даже если итоговый платёж одинаковый.
Для платёжной кнопки действие должно быть очевидным: «Оплатить криптовалютой». Не «Продолжить» и не «Перейти дальше». Такие формулировки скрывают, что будет следующим шагом. Когда пользователь нажимает кнопку, вызовите backend, получите платёжный запрос, а затем покажите адрес кошелька, QR-код и сумму в этом же окне.
Полезный приём — оставлять сводку заказа видимой, пока загружаются инструкции по оплате. Так клиент видит и конкретный товар, и точную сумму одновременно. Это уменьшает путаницу, когда сумма зафиксирована в USD, а оплата идёт волатильным активом.
Если вы строите крипто checkout next.js, особенно важно не усложнять интерфейс лишними шагами: чем короче путь от кнопки до адреса или инвойса, тем выше шанс, что пользователь завершит оплату.
Генерируйте адреса, инвойсы или платёжные ссылки
Каждый заказ должен соответствовать 1 уникальному платёжному запросу. Это может быть адрес кошелька, платёжная ссылка или объект invoice от вашего провайдера. Если использовать один и тот же адрес для всех клиентов, сверка платежей станет сложной, а поддержка получит лишнюю работу.
Для небольшого магазина можно генерировать новый адрес на каждый заказ и сохранять в базе адрес, ожидаемую сумму, актив и время истечения срока действия. В потоке с провайдером он может вместо этого возвращать invoice ID и hosted payment link. В любом случае привязывайте платёжный запрос к ID заказа ещё до того, как клиент его увидит.
Показывайте пользователю детали в понятном виде: актив, сеть, сумма и адрес назначения. QR-код полезен, но он не должен заменять текст. Некоторые кошельки плохо сканируют QR-коды; некоторые пользователи копируют адрес вручную. Один понятный адрес всё ещё остаётся запасным вариантом.
Если вам нужно поддерживать оплату по адресу для услуг или счетов, схемы похожи на те, что описаны в статье про криптоплатёжный шлюз для фрилансеров. Платёжная ссылка часто удобнее для разовых заказов; отдельная запись инвойса лучше подходит, когда нужны история платежей и напоминания.
Подтверждайте блокчейн-платежи и обновляйте статус заказа
Подтверждение оплаты — это место, где многие команды начинают халтурить. Не помечайте заказ как оплаченный, если в кошельке просто отображается pending-транзакция. Не доверяйте только браузеру. Ваш backend должен проверять транзакцию либо напрямую в сети, либо через подписанный webhook от платёжного провайдера.
Обычно процесс выглядит просто. Провайдер обнаруживает платёж, отправляет криптоплатежи next.js webhook в ваш маршрут Next.js, а сервер проверяет подпись перед изменением статуса заказа. Если вы реализуете это сами, нужно проверять transaction hash, адрес получателя, актив, сумму и количество подтверждений, требуемое вашей политикой. Платёж может выглядеть настоящим ещё до того, как станет окончательным.
Используйте модель заказа из 3 состояний: pending, confirmed, paid. Pending означает, что запрос создан. Confirmed — что сеть увидела платёж и он получил достаточно подтверждений. Paid — что ваше приложение уже обновило выдачу товара или доступ. Держите эти состояния раздельно, потому что сотруднику поддержки нужно понимать, ждёт ли клиент, подтверждён ли платёж или заказ уже выполнен.
Если webhooks входят в ваш стек, проверяйте их каждый раз. Статья о том, как проверить подписанные webhooks payora, полезна даже если вы не используете PHP, потому что принцип один и тот же: отклоняйте сообщения, которые не доказывают, что они пришли от провайдера. Одна такая проверка способна сразу остановить поддельные события об оплате.
Обрабатывайте крайние случаи, безопасность и тестирование
Криптовалютный checkout ломается чаще, чем карточный. Котировка может истечь. Клиент может отправить средства не в ту сеть. Кошелёк может недоплатить на небольшую сумму. Браузер может обновиться в середине процесса. На каждый такой случай нужен ответ, и каждый должен подсказывать пользователю 1 следующий шаг.
Истёкшие котировки не должны зависать в неопределённости. Если платёжная ссылка действует 15 минут, покажите этот таймер явно и создайте новый запрос, когда срок закончится. Переводы в неверной сети требуют отдельного пути поддержки, потому что деньги могут существовать, но не там, где ваше приложение их ожидает. Недоплаты можно принять, отклонить или отправить на ручную проверку, но политика должна быть определена до запуска, а не после первого обращения.
Безопасность — не опция. Храните секретные ключи только в переменных окружения на сервере. Проверяйте подписи webhook’ов. Сохраняйте минимально необходимый объём платёжных данных. Если логируете идентификаторы транзакций, маскируйте всё лишнее, что не нужно для отладки. Перед запуском на живой трафик тестируйте в testnet или в sandbox-инструментах провайдера. Если вам нужен практический чеклист, посмотрите как протестировать криптовалютный платёж, прежде чем подключать реальный кошелёк.
Не забывайте о дублирующихся событиях. Некоторые провайдеры повторно отправляют webhook’и, а блокчейн-события могут появляться в системе несколько раз, если быть неосторожным. Код обновления заказа должен быть idempotent, то есть одно и то же событие не должно дважды помечать один заказ как оплаченный. Одна такая защита экономит часы.
Запустите, отслеживайте и улучшайте checkout
Развёртывание на Vercel или похожем хостинге обычно хорошо подходит для Next.js, но платёжной части всё равно нужно уделить внимание. Убедитесь, что ваш webhook-эндпоинт доступен из интернета, переменные окружения заданы в production, а сборка не зависит от значений, которые существуют только локально. Платёжный маршрут, который работает на ноутбуке и ломается в продакшене, — классическая ошибка.
Логирование здесь очень важно. Логируйте создание инвойса, получение webhook’а, результаты проверки и изменения статуса. Деталей должно хватать, чтобы проследить один заказ от начала до конца, но не выводите секреты в логи. Если клиент говорит, что оплатил в 14:32, вы должны найти нужное событие за секунды, а не за часы.
Небольшие изменения в UX могут сильнее снизить трение, чем кажется. Покажите сумму дважды: один раз в сводке заказа и ещё раз на шаге оплаты. Оставьте кнопку оплаты видимой после загрузки инвойса. Добавьте кнопку копирования рядом с адресом. Ясно показывайте шаг подтверждения, потому что пользователи часто обновляют страницу, пока ждут. Обновление статуса за 5 секунд может ощущаться как 5 минут, если страница молчит.
Дальше настоящая работа — не первый платёж. А второй, третий и тот, что ломается на границе между кошельком, сетью и вашим backend на Next.js. Если ваша система чисто обрабатывает эти 3 случая, у вас есть checkout, которому клиенты смогут доверять.
Комментарии