Laravel робить платежі впорядкованими, а це вже половина справи. Але для криптоплатежу все одно потрібні маршрути, контролери, записи в базі даних і чітка передача даних між вашим застосунком та провайдером. Якщо ви розбираєтеся, як налаштувати криптоплатежі в Laravel, почніть не з панелі провайдера, а зі структури, яка вже є у вашому проєкті. Саме так криптоплатежі на Laravel вбудовуються в уже наявний checkout без зайвого хаосу.
1. Перевірте структуру свого застосунку Laravel перед додаванням платежів
Подивіться, де у вашому застосунку має відбуватися оформлення замовлення. Для магазину це можуть бути routes/web.php, CheckoutController і Blade-представлення. У SaaS-продукту вже можуть бути middleware для авторизації, сторінки білінгу та налаштування акаунта. Сайт для пожертв може обійтися одним маршрутом і простою формою. Ця різниця має значення для інтеграція криптоплатежів Laravel, бо саме вона визначає, де має з’явитися платіжний крок.
Запишіть точний шлях від сторінки товару до сторінки оплати. Якщо сайт уже створює кошики, рахунки або підписки, ваш криптоплатіжний сценарій має вбудовуватися в цю логіку, а не створювати другий окремий шлях. Одного оформлення замовлення досить. Два — це вже хаос.
Також зверніть увагу на стек фронтенду. Blade — це просто. Livewire може залишити користувача на одній сторінці. Inertia часто переносить стан платежу в більш “застосунковий” досвід, а це означає, що оновлення статусу потрібно передавати через API-рівень, а не через звичайне серверне перенаправлення. Від цього залежить усе подальше.
Перевірте і модель авторизації. Якщо користувач має увійти в акаунт перед оплатою, запис платежу має бути прив’язаний до ID користувача. Якщо платити можуть гості, потрібен інший ідентифікатор — наприклад, email або токен замовлення. Без цього у базі буде платіж і загадка. Нікому не потрібні загадки о другій ночі.
2. Вирішіть, що саме має обробляти ваш checkout у Laravel
Спочатку визначте тип платежу. Разова покупка товару поводиться зовсім інакше, ніж форма для донатів або регулярний білінг. Для разового оформлення зазвичай достатньо створити одне замовлення й дочекатися підтвердження. Пожертви можуть взагалі не потребувати обліку запасів. Підписки ж потребують логіки поновлення, обробки скасувань і часто окремої state machine.
Сформулюйте правила чітко. Якщо користувач купує цифровий файл, застосунок має позначити замовлення як оплачене та відкрити завантаження. Якщо сайт виставляє рахунки, номер рахунку має потрапити в метадані платежу. Якщо ціна змінюється залежно від ролі користувача, бекенд має розрахувати суму ще до створення запиту на оплату, а не після. Інакше замовлення і платіж не зійдуться.
Потрібен посилальний ідентифікатор для конкретного користувача? Додайте його зараз. Для checkout із кошиком це може бути ID замовлення. Для підписки — ID клієнта та код тарифу. Для сервісного рахунку можуть знадобитися обидва. Саме тут платіжний потік або стає відстежуваним, або перетворюється на купу відірваних хешів і здогадок.
Для сайтів із підписками читайте також про криптоплатіжний шлюз для SaaS-підписок, якщо ваш Laravel-застосунок виставляє рахунки за графіком. У такому випадку додаються терміни поновлення, обробка невдалих платежів і зміни статусу, яких не потребує разовий checkout.
3. Оберіть підхід до інтеграції криптоплатежів, зручний для Laravel
Зазвичай є 3 шляхи: hosted checkout, створення платіжних сесій через API або потік, у якому все крутиться навколо webhook, а бекенд лишається під контролем. Hosted checkout — найпростіший варіант. Ваш застосунок створює платіжний запит і перенаправляє користувача до провайдера. Створення через API дає більше контролю над мітками, метаданими та точними сумами. Потік із webhook особливо важливий, коли фінальний стан має визначатися лише після підтвердження провайдера.
Обирайте підхід не лише за тим, що зручно на запуску, а й за тим, що ваша команда зможе підтримувати потім. Невеликий Laravel-проєкт може віддати перевагу hosted checkout, бо це менше коду і менше крайніх випадків. SaaS-продукт із внутрішніми правилами білінгу може захотіти контролю через API, бо застосунок має створювати пов’язані з клієнтами платіжні сесії, а не просто відправляти людину на загальну сторінку.
Тут є питання підтримки. Менше кастомного коду зазвичай означає менше багів. Більше контролю зазвичай означає більше логіки, яку треба тестувати. Обидва варіанти нормальні. Неправильний — той, що ігнорує вашу команду, worker-и черги та ваш час. Платіжна система, яку ніхто не може підтримувати, перетворюється на майбутній збій.
Якщо хочете порівняти налаштування провайдера з ширшою моделлю інтеграції, стаття про криптоплатіжний шлюз для SaaS допоможе побачити компроміс між зручністю та контролем для Laravel-застосунків, які продають програмне забезпечення, а не фізичні товари.
4. Налаштуйте платіжний потік і записи в базі даних на стороні Laravel
Сплануйте весь внутрішній шлях до написання коду. Типова послідовність така: створити замовлення, зберегти запис із статусом pending, запросити платіжну сесію у провайдера, записати його референс і чекати підтвердження. Це звучить просто, але порядок має значення. Якщо спочатку створити платіжну сесію, а потім замовлення, звірка даних швидко стане кошмаром.
У базі даних має бути щонайменше кілька полів: order_id, user_id, provider_payment_id, amount, currency, status, expires_at і часові мітки. Додайте paid_at, якщо це потрібно для звітів. Додайте failure_reason, якщо службі підтримки потрібен контекст. Чотири стани — типова практика: pending, paid, failed і expired. Залишайте їх явними. “Інше” — це не стан.
Використовуйте одну або дві таблиці залежно від обсягу. Невеликі застосунки часто тримають замовлення і платежі в окремих таблицях, пов’язаних зовнішнім ключем. Більші системи можуть додати таблицю журналу для аудиту. Така додаткова таблиця корисна, коли фінансовий відділ питає, чому платіж тричі змінив статус за одну годину. А це трапляється частіше, ніж люди визнають.
Для перевірки webhook і безпеки payload корисно тримати записи про платежі у відповідності до порад із кращих практик безпеки криптоплатіжних шлюзів. Чиста модель бази сама по собі не є безпекою, але вона дає щось реальне, що можна захистити перевірками безпеки.
5. Підключіть Laravel до API криптоплатіжного провайдера
Зберігайте API-облікові дані в .env, а не в контролері. Використовуйте щось на кшталт PAYMENT_PROVIDER_KEY і PAYMENT_PROVIDER_SECRET, а потім зв’яжіть їх у конфігураційному файлі, щоб решта застосунку читала значення через config(). Так ви розділите staging і production, а це важливо, коли в одному середовищі не мають створюватися реальні транзакції.
Створіть сервісний клас або action для виклику API. Сервісний клас у Laravel може зібрати payload запиту, надіслати його HTTP-клієнтом і повернути дані сесії в контролер. Це робить контролер легким. Легкі контролери простіше тестувати, і через пів року вони дратують набагато менше. Сервіс має отримувати замовлення, суму, валюту й callback-URL, а потім повертати ID провайдера та URL для перенаправлення.
Хороший підхід такий: контролер перевіряє запит, сервіс створює платіжну сесію, модель зберігає референс провайдера, а відповідь відправляє користувача на крок checkout. Якщо провайдеру потрібні додаткові метадані, передайте номер замовлення та користувацький референс у payload. Не ховайте ці дані в полі нотаток, якщо тільки провайдер не очікує їх саме там.
Для деталей налаштування й назв endpoint-ів документація для розробників API криптоплатіжного шлюзу — це правильне місце, щоб перевірити формати запитів перед тим, як писати клас для Laravel. Одне неправильне ім’я поля може коштувати вам половини дня.
6. Додайте обробку webhook для підтвердження платежу
Обробка webhook — це місце, де відбувається справжнє підтвердження. Створіть окремий маршрут, зазвичай поза CSRF-захистом, якщо провайдер не може надсилати CSRF-токен, і прив’яжіть його до контролера або job, який приймає події. Потім перевірте підпис за секретом провайдера, щоб випадкові POST-запити не могли позначити замовлення як оплачені. Це не опція.
Не оновлюйте замовлення лише на основі frontend-redirect. Користувачі закривають вкладки. Браузери падають. Мобільний інтернет обривається. Redirect може показати правильне повідомлення, але змінювати фінальний статус платежу має лише webhook. Якщо провайдер надсилає і “processing”, і “paid”, вважайте “paid” тим станом, який розблоковує замовлення. Швидке повідомлення після переходу — ще не доказ.
Тут важлива ідемпотентність. Один і той самий webhook може прийти двічі. Ваш обробник має перевірити, чи вже було оброблено цей ID платежу, перш ніж оновлювати замовлення. Якщо подія дубльована, поверніть відповідь 200 і зупиніться. Так ваш застосунок не відправить той самий цифровий файл двічі й не надішле два листи з квитанцією за один платіж.
Захист від повторного відтворення події — ще одна дрібниця з великими наслідками. Зберігайте ID події, timestamp або позначку підпису, якщо провайдер їх надає. Якщо webhook занадто старий або вже був, ігноруйте його. Платіжна система, яка приймає повторно відтворені події, сама просить про проблеми.
7. Оновіть фронтенд, щоб відображати статус платежу в Laravel
Сторінка checkout має чітко показувати поточний стан: pending, processing, paid або failed. Користувач, який щойно заплатив, не хоче бачити порожній екран. Він хоче знати, чи платіж пройшов. Показуйте статус простою мовою і прив’язуйте його до номера замовлення, а не до розмитого індикатора завантаження.
Якщо провайдер повертає користувача на ваш сайт, сторінка повернення може показувати тимчасовий статус, поки webhook завершить оновлення. Це нормально. Платіж може вже відображатися в системі провайдера, хоча у вашій базі ще не оновився. Якщо немає миттєвого перенаправлення, використовуйте polling або кнопку оновлення, яка звертається до Laravel-backend за останнім статусом. Таймінг залежить від вашого провайдера та швидкості черги.
Livewire спрощує оновлення статусу. Blade може робити це через невеликий JavaScript-полінг. Inertia може запитувати оновлений об’єкт платежу із сервера. Оберіть один варіант і дотримуйтеся його. Змішані підходи створюють два інтерфейси, які не погоджуються між собою, а для сторінки оформлення замовлення це виглядає погано.
Якщо ваш застосунок також продає через WordPress, є корисне порівняння в прийомі криптоплатежів у WordPress. Ідеї для фронтенду схожі, але Laravel дає вам набагато пряміший контроль над оновленням статусів і внутрішніми записами.
8. Тестуйте, логуйтесь і розгорніть криптоплатіжний потік Laravel
Спочатку протестуйте весь шлях локально: створення замовлення, відкриття платіжної сесії, отримання webhook, оновлення статусу і відображення сторінки з позначкою paid. Потім повторіть це для невдалого платежу та простроченого платежу. Два хороші тести кращі за одну ідеальну здогадку. Використовуйте sandbox-режим перед live-режимом і тримайте endpoint-и розділеними, щоб застосунок випадково не змішав їх.
Черги та job-и допомагають, якщо обробка webhook робить більше, ніж одне оновлення в базі. Надсилання квитанцій, оновлення підписок або сповіщення підтримки можуть виконуватися у фоновому режимі. Якщо job падає, логуйтесь. Якщо API-запит не вдається, записуйте розмір payload, код відповіді та ID замовлення. Не логуйтені секрети. Журнал — для діагностики, а не для подарунка зловмисникам.
Перед деплоєм у production перевірте такі речі: змінні середовища задані, webhook-URL доступний, перевірка підпису увімкнена, queue worker працює, якщо це потрібно, міграції бази даних застосовані, а тестові платежі на живому магазині вимкнені. Список короткий, але кожен пункт дорого коштує, якщо його пропустити. Один відсутній webhook-URL може зробити кожне оплачене замовлення виглядом “pending”.
Є ще одна корисна звичка на завершення: уважно стежте за першими 24 годинами. Дивіться на помилки webhook, дубльовані події та платіжні сесії, які так і не завершилися. Перевірте один реальний order від початку до кінця. Якщо це працює, криптоплатіжний потік Laravel виконує свою роботу, і ваш наступний крок — не переписування, а спостереження за тим, як перші реальні користувачі натискають “Оплатити”.
Коментарі