Розберіться в платіжному процесі та вимогах
Якщо хочете дізнатися як приймати криптоплатежі на сайті Next.js, почніть не з коду, а з процесу. Зазвичай криптооплата складається з 4 частин: створити замовлення, показати платіжний запит, відстежити блокчейн і позначити замовлення як оплачене лише після перевірки; саме так будується ефективна криптоплатежі Next.js інтеграція.
Звучить просто. Насправді рідко буває так.
«Приймати крипту» на сайті Next.js не означає, що ваш застосунок сам зберігає монети. У більшості випадків сайт створює платіжний запит для клієнта, клієнт надсилає кошти з гаманця, а платіжний сервіс або ваш власний бекенд підтверджує переказ. Хороший чек-аут також потребує тайм-аута, бо курс, який був справедливим о 10:00, може стати неактуальним через 20 хвилин.
Вам також потрібно знати, які мережі та активи ви будете підтримувати. Магазин, що приймає USDT в Ethereum, Polygon і BNB Chain, робить не те саме, що сайт, який приймає лише BTC в одній мережі. Вибір мережі впливає на комісії, час підтвердження і тип гаманця, який потрібен клієнту. Якщо прийняти не ту мережу, платіж може потрапити туди, де ви не зможете зіставити його із замовленням.
Є одна практична перевірка: чи може новий клієнт завершити оформлення менш ніж за 2 хвилини? Якщо ні, процес треба допрацювати. Один гаманець, одна сума, одна зрозуміла адреса, одна зрозуміла сторінка статусу. Саме такої ясності люди й очікують.
Оберіть провайдера криптоплатежів або інтеграцію з гаманцем
Крипточекаут у Next.js можна побудувати трьома основними способами. По-перше, це hosted checkout від провайдера. По-друге, пряма інтеграція з гаманцем, коли ваш застосунок працює з бібліотекою гаманця. По-третє, платіжний шлюз між користувачем і блокчейном; у практичному сенсі це може бути саме платіжний шлюз для криптовалюти в Next.js. Кожен варіант має свою ціну впровадження, а правильне рішення залежить від того, що для вас важливіше: швидкість, контроль чи і те, й інше.
Hosted checkout зазвичай найшвидше запустити. Ви створюєте рахунок, перенаправляєте клієнта на сторінку провайдера, а він уже визначає надходження платежу. Пряма інтеграція з гаманцем може виглядати органічніше всередині вашого продукту, але зазвичай означає більше коду, більше крайніх випадків і більше відповідальності за підтвердження платежів. Шлюз знаходиться посередині й часто є практичним вибором для комерції, бо він може створювати рахунки, відстежувати підтвердження та надсилати вебхуки.
Перш ніж обирати, перевірте 5 речей: підтримувані монети, підтримувані мережі, підтримку вебхуків, термін дії рахунку та обсяг бекенд-коду, який провайдер очікує від вас. Якщо ви порівнюєте варіанти для магазину, корисно почати з матеріалу про crypto payment gateway for ecommerce, бо він розкладає це ж рішення з погляду продавця. Фрилансеру, який виставляє рахунки клієнтам, можуть бути важливіші рахунки та платіжні посилання, ніж вітринному магазину, саме тому аспект crypto payment gateway for freelancers теж має значення.
І ще одне: якщо провайдер заявляє про підтримку «всіх основних активів», попросіть точний список. «Усі» — це нечітко. «BTC, ETH, USDC у 3 мережах» — це вже рішення, з яким можна працювати.
Налаштуйте проєкт Next.js для платежів
Почніть із чистої структури застосунку. У проєкті з app router у Next.js розміщуйте платіжну логіку в серверних маршрутах або server actions, а секретні ключі не виносьте на клієнт. Проста структура може включати 1 сторінку товару, 1 форму оформлення, 1 API-маршрут для створення рахунків і 1 webhook-маршрут для подій платежів.
Ваші змінні середовища мають покривати секретний ключ платіжного провайдера, секрет вебхука та публічні значення API, які можна показувати в браузері. Не кладіть секретний ключ у клієнтський компонент. Така помилка може зламати весь акаунт, і це одна з тих небагатьох помилок, що швидко обходяться дорого.
Якщо провайдер пропонує SDK, встановлюйте його лише на серверному рівні. Якщо він дає звичайні HTTP-ендпоінти, це теж підходить. Суть одна: браузер звертається до вашого бекенду Next.js, щоб створити платіжний запит, а бекенд спілкується з провайдером. Браузер ніколи не повинен сам вирішувати, що замовлення вже оплачено.
Для команд, які переходять із карткових платежів, структура не надто відрізняється від Stripe-процесу, лише етапи перевірки інші. Якщо така аналогія допомагає, прочитайте як перейти зі stripe, перш ніж розкладати API-маршрути. Для прототипу достатньо одного API-маршруту; коли додасте повторні спроби, повернення коштів і історію статусів замовлення, краще мати 3 або 4 маршрути.
Створіть інтерфейс оформлення в Next.js
Інтерфейс оформлення може бути карткою товару, сторінкою кошика або просто кнопкою, що запускає платіж. У клієнтському компоненті Next.js кнопка зазвичай надсилає дані замовлення на серверний маршрут, чекає відповіді, а потім перенаправляє клієнта або показує інструкції для гаманця.
Тримайте форму короткою. Назва товару, сума, email і, можливо, примітка до замовлення — цього часто достатньо. Якщо попросити 9 полів, чекайте більшого відсіву. Якщо попросити 3, люди завершуватимуть швидше. Чекаут, який займає 30 секунд, відчувається краще, ніж той, що триває 3 хвилини, навіть якщо обидва завершуються тим самим платежем.
Для кнопки оплати дія користувача має бути очевидною: «Сплатити криптою». Не «Продовжити» і не «Далі». Такі підписи приховують ціну наступного кроку. Коли кнопку натиснуто, викличте бекенд, отримайте платіжний запит, а потім покажіть адресу гаманця, QR-код і суму в тому самому вікні.
Корисний підхід — залишати підсумок замовлення видимим, поки завантажуються інструкції з оплати. Так клієнт бачить точний товар і точну суму разом. Це зменшує плутанину, коли сума фіксована в USD, але оплата йде волатильним активом.
Генеруйте платіжні адреси, рахунки або платіжні посилання
Кожне замовлення має відповідати 1 унікальному платіжному запиту. Це може бути адреса гаманця, платіжне посилання або об’єкт рахунку від вашого провайдера. Використовувати одну й ту саму адресу для всіх клієнтів — це шлях до хаосу в звірці платежів і зайвої роботи для підтримки.
Для невеликого магазину ви можете створювати нову адресу для кожного замовлення та зберігати в базі адресу, очікувану суму, актив і час завершення дії. Для потоку через провайдера він може повертати ID рахунку та hosted payment link замість адреси. У будь-якому разі прив’яжіть платіжний запит до ID замовлення ще до того, як клієнт його побачить.
Показуйте клієнту дані в зрозумілому вигляді: актив, мережу, суму та адресу призначення. QR-код корисний, але він не повинен замінювати текст. Деякі гаманці сканують QR-коди неідеально; деякі користувачі копіюють і вставляють адресу вручну. Одна чітка адреса все одно залишається страховкою.
Якщо вам потрібно підтримувати білінг за адресою для послуг або інвойсів, підходи дуже схожі на ті, що описані в статті про crypto payment gateway for freelancers. Для разових замовлень часто зручніше платіжне посилання; окремий запис інвойсу краще підходить, коли потрібні історія платежів і нагадування.
Підтверджуйте блокчейн-платежі та оновлюйте статус замовлення
Підтвердження платежу — це місце, де багато команд припускаються помилок. Не позначайте замовлення як оплачене, якщо гаманець показує лише pending-трансфер. Не довіряйте лише браузеру. Ваш бекенд має перевіряти транзакцію безпосередньо в мережі або отримувати підписаний вебхук від платіжного провайдера.
Типовий процес простий. Провайдер виявляє платіж, надсилає вебхук на ваш маршрут Next.js, а ваш сервер перевіряє підпис, перш ніж змінювати статус замовлення. Якщо ви реалізуєте цей крок самостійно, потрібно перевіряти hash транзакції, адресу призначення, актив, суму і кількість підтверджень, яку вимагає ваша політика. Платіж може виглядати справжнім ще до того, як стане фінальним.
Використовуйте модель замовлення з 3 станами: pending, confirmed, paid. Pending означає, що запит існує. Confirmed означає, що мережа побачила платіж і він має достатньо підтверджень. Paid означає, що ваш застосунок уже запустив фулфілмент або доступ. Тримайте ці стани окремо, бо фахівцю підтримки важливо знати, чи клієнт чекає, уже верифікований, чи йому вже все доставлено.
Якщо вебхуки є частиною вашого стеку, перевіряйте їх щоразу. Стаття про як перевіряти підписані вебхуки payora корисна навіть якщо ви не використовуєте PHP, бо базова ідея та сама: відхиляйте повідомлення, які не доводять, що вони прийшли від провайдера. Одна ця перевірка може повністю зупинити фейкові події про оплату.
Обробляйте крайні випадки, безпеку та тестування
Крипточекаут ламається більше способами, ніж картковий. Курс може завершити дію. Клієнт може надіслати кошти не в ту мережу. Гаманець може недоплатити трохи. Браузер може оновитися посеред процесу. На кожен із цих випадків потрібна реакція, і кожен має вести користувача до 1 наступного кроку.
Прострочені курси не повинні зависати в невизначеності. Якщо платіжне посилання дійсне 15 хвилин, чітко покажіть цей таймер і створіть новий запит після завершення терміну. Перекази в неправильній мережі потребують шляху до підтримки, бо гроші можуть існувати, але не там, де їх очікує ваш застосунок. Недоплати можна прийняти, відхилити або позначити для перевірки, але ваша політика має бути написана до запуску, а не після першої скарги.
Безпека — не опція. Зберігайте секретні ключі в серверних змінних середовища. Перевіряйте підписи вебхуків. Зберігайте мінімум платіжних даних, який вам справді потрібен. Якщо логуватимете ID транзакцій, маскуйте все чутливе, що не потрібне для дебагу. Тестуйте в testnet або за допомогою sandbox-інструментів провайдера ще до реального трафіку. Якщо хочете практичний чекліст, подивіться як протестувати криптоплатіж, перш ніж підключати реальний гаманець.
Не забувайте про дублікати подій. Деякі провайдери повторно надсилають вебхуки, а мережі можуть показувати той самий платіж у вашій системі більше одного разу, якщо ви неуважні. Код оновлення замовлення має бути ідемпотентним, тобто одна й та сама подія не повинна двічі позначати одне й те саме замовлення як оплачене. Цей один захист економить години.
Запустіть, відстежуйте та покращуйте процес оформлення
Деплой на Vercel або подібному хості зазвичай добре підходить для Next.js, але платіжним частинам усе одно треба приділити увагу. Переконайтеся, що ваш webhook-ендпоінт доступний ззовні, змінні середовища налаштовані в production, а збірка не залежить від значень, які є лише локально. Платіжний маршрут, який працює на ноутбуці й падає в продакшені, — класична помилка.
Тут важливе логування. Логуйте створення рахунку, отримання вебхука, результати перевірки та зміни статусу. Використовуйте достатньо деталей, щоб простежити одне замовлення від початку до кінця, але не викидайте секрети в лог. Якщо клієнт каже, що оплатив о 14:32, ви повинні знайти відповідну подію за секунди, а не за години.
Невеликі зміни UX можуть зменшити тертя сильніше, ніж здається. Показуйте суму двічі: один раз у підсумку замовлення і ще раз на етапі оплати. Залишайте кнопку оплати видимою після завантаження інвойсу. Додайте кнопку копіювання поруч з адресою. Показуйте крок підтвердження просто й прямо, бо користувачі часто оновлюють сторінку, поки чекають. Оновлення статусу за 5 секунд може здаватися 5 хвилинами, якщо сторінка мовчить.
Далі справжня робота — не перший платіж. А другий, третій і той, що зламається на межі між гаманцем, блокчейном і вашим бекендом Next.js. Якщо ваша система може чисто обробити ці 3 сценарії, у вас є чекаут, якому клієнти можуть довіряти.
Коментарі