Як підключити Payora до сайту на PHP

Як підключити Payora до власного сайту на PHP

Якщо ваш сайт — це окрема PHP-розробка, усе доволі просто: створюєте платіж, відправляєте клієнта в Payora, а потім повертаєте результат у свою систему замовлень. Без WooCommerce. Без хаосу з плагінами.

Цей гайд показує, як підключити Payora до сайту на PHP без перетворення оформлення замовлення на науковий проєкт. Ви побачите, де саме PHP має запускати платіж, куди отримувати повернення, і де ваш застосунок повинен вирішувати, чи замовлення оплачено, очікує оплати або не вдалося. Саме так вибудовується надійна Payora PHP інтеграція, коли логіка продажів залишається під вашим контролем.

1. Підтвердіть схему інтеграції для сайту на PHP

Почніть з одного рішення: ви будуєте просте посилання для оплати, серверний платіжний запит чи повний платіжний процес із відстеженням замовлень? Це не одне й те саме. Односторінковий сайт для донатів може обійтися платіжним посиланням, тоді як магазин із 20 товарами зазвичай потребує серверного створення замовлення до того, як клієнт покине сайт.

Для власного сайту на PHP найчистіша схема часто така: спочатку створити замовлення локально, потім створити платіж Payora з PHP, далі перенаправити клієнта, а після цього обробити повернення та серверне підтвердження. Так у вас буде запис на вашому боці ще до того, як рухнуться гроші. І логіка кошика та рахунка залишиться у вашому застосунку, де їй і місце. Саме тому платіжна система Payora PHP добре підходить для проєктів, де важлива прозора серверна валідація.

Якщо оформлення замовлення дуже просте, вам може вистачити лише редиректу на платіжну сторінку Payora. Якщо потрібні позиції, примітки клієнта або ID замовлення, ваш PHP-код має передати ці дані ще до перенаправлення. Просто. Але не примітивно.

Практичний приклад допомагає. Діджитал-агенція, що продає пакет обслуговування з 3 кроків, може створити замовлення в PHP, додати email клієнта й відправити його в Payora з посиланням на рахунок. Хобі-проєкту, який продає один ліцензійний ключ, може вистачити лише платіжного посилання та сторінки повернення. Різниця не в обсязі коду, а в кількості стану, який потрібно зберегти.

2. Розплануйте точні сторінки, ендпоїнти та потік сесії

Перед тим як писати код, перелічіть сторінки. Вам потрібно щонайменше три: сторінка оформлення, сторінка повернення і серверний ендпоїнт для підтвердження платежу. Якщо не зробити таку карту, потім доведеться здогадуватися, який саме запит змінив замовлення. А здогадки коштують дорого.

Для потоку в браузері використовуйте звичайну PHP-сесію, але не покладайтеся лише на неї. Стан сесії може зникнути, якщо клієнт змінить пристрій, закриє вкладку або повернеться з Payora пізніше. Зберігайте ID замовлення також у базі даних, щоб ваш PHP-код міг знайти транзакцію навіть тоді, коли браузерна сесія вже зникла.

Типовий потік виглядає так:

• Сторінка оформлення збирає товар, email і кількість.
• PHP створює локальне замовлення зі статусом pending.
• PHP відправляє клієнта в Payora.
• Payora повертає браузер на ваш return URL.
• Ваш сервер перевіряє статус платежу перед тим, як позначити замовлення як оплачене.

Такий потік розділяє сторінку повернення в браузері та серверну істину. І це правильно. Вони мають бути окремими. Браузер може показати, що побачив клієнт; а ваш сервер має вирішувати, що означає замовлення.

Одна маленька звичка зекономить години пізніше: одразу після створення платежу збережіть платіжний референс Payora поруч із ID замовлення. Якщо почекати до завершення редиректу, мережна помилка або нетерпляче оновлення можуть лишити вас із замовленням без референса Payora. А тоді в продакшені доведеться грати детектива.

3. Підготуйте мінімальний шар для платіжних запитів у PHP

Не змішуйте платіжний код із шаблонами. Достатньо невеликого PHP-класу або хелпера. Один метод може формувати payload, інший — надсилати HTTP-запит, а третій — розбирати відповідь. Таке розділення важливе, бо платіжна логіка змінюється частіше, ніж верстка сторінки.

Наприклад, ваш хелпер може приймати масив із amount, currency, order_id і return_url, а потім додавати ваші облікові дані Payora з змінних середовища. Сторінка оформлення ніколи не повинна знати, де лежить API-токен. Вона має знати лише, яку кнопку натиснули. Саме так виглядає практична Payora PHP інтеграція без зайвих залежностей у фронтенді.

Ось форма логіки коду, не повна реалізація:

1. Зчитати замовлення з бази даних.
2. Сформувати масив запиту Payora.
3. Надіслати запит через cURL або подібний HTTP-клієнт.
4. Зберегти повернений платіжний референс Payora.
5. Перенаправити клієнта на платіжний URL Payora.

Зробіть цей хелпер нудним. Нудний код простіше тестувати. Нудний код рідше ламається, коли наступного місяця ви змінюєте ціну товару або додаєте другу форму оформлення.

Якщо у вашому застосунку вже є абстракція платежів, використовуйте її. Якщо ні — створіть один файл із чіткою назвою, наприклад PayoraClient.php. У цьому файлі мають бути облікові дані, виклики API та розбір відповіді. І нічого більше. Не HTML. Не CSS. Не повідомлення подяки.

4. Відправте клієнта в Payora з власного оформлення замовлення

Коли локальне замовлення вже існує, відправте платіжний запит Payora і перенаправте клієнта на сторінку оплати Payora. Передача має відбуватися лише після того, як сервер збереже замовлення, бо користувач може закрити вкладку в ту ж секунду, коли почнеться редирект.

Передавайте лише ті дані замовлення, які вам справді потрібні. Зазвичай це ID замовлення, сума, валюта та email клієнта. Можна також передавати метадані, наприклад назву товару або внутрішній ID акаунта, але не скидайте в запит усі поля з бази просто тому, що вони доступні. Зайві дані потім лише плутають сапорт, коли звіряють записи.

У власному оформленні замовлення часто використовують POST-форму з кнопкою «Оплатити зараз». Ця форма надсилає дані на ваш PHP-ендпоїнт, ендпоїнт створює платіж Payora, а потім повертає редирект. Клієнт ніколи не бачить відповідь API. Він бачить лише Payora.

Одна важлива пересторога: не довіряйте сумам із клієнтської сторони. Якщо на сторінці товар коштує $49, а браузер відправляє $39, ваш сервер має відхилити невідповідність. Платіжний запит треба створювати на основі серверної суми замовлення, а не значення, прихованого у формі. Це правило важливе завжди.

Якщо вам потрібен ширший погляд на схеми налаштування платежів, у гайді про як приймати криптоплатежі є корисний контекст без повторення PHP-потоку тут.

5. Отримайте й перевірте результат платежу у своєму застосунку

URL повернення в браузері корисний, але це не остаточна відповідь. Він може показати, що сторінку оплати відвідали, і може передати значення статусу, але ваш PHP-застосунок усе одно має вважати цей результат попереднім, доки сервер не підтвердить його. Pending — це ще не paid.

Сторінку повернення варто спроєктувати так, щоб вона обробляла три випадки: успіх, очікування й помилку. Якщо Payora показує success, виведіть сторінку подяки та повідомте користувачу, що замовлення зараз підтверджується. Якщо статус pending, скажіть саме це. Якщо оплата не вдалася, запропонуйте спробувати ще раз, не втрачаючи запис замовлення. Чіткі формулювання зменшують кількість звернень у сапорт.

Тут є корисне правило: сторінка повернення ніколи не повинна сама створювати оплачлене замовлення. Вона має лише показувати поточний стан і, можливо, давати посилання назад на сторінку замовлення. Оновлення в базі відбувається після перевірки, а не після редиректу в браузері. Саме ця різниця захищає від випадкового подвійного оновлення.

Залиште ендпоїнт повернення достатньо простим, щоб зрозуміти його з першого погляду. Якщо він отримує платіжний референс Payora, знайдіть його. Якщо референса немає, залогуйте запит і зупиніться. Якщо замовлення вже оплачене, покажіть дружнє повідомлення й нічого не змінюйте. Саме так ідемпотентні потоки залишаються спокійними навіть при повторних оновленнях.

Для команд, яким також потрібне порівняння з боку оформлення, стаття про як приймати криптоплатежі від клієнтів містить корисні нотатки щодо білінгу, особливо якщо ви продаєте послуги з регулярними рахунками або ручним схваленням.

6. Підтвердьте транзакцію на сервері, перш ніж позначати замовлення як оплачене

Це безпечніший крок. Ваш PHP-застосунок має звернутися до Payora з боку сервера й підтвердити статус транзакції перед тим, як ставити замовленню статус paid. Редиректи в браузері можуть брехати замовчуванням; серверні перевірки не хвилює, чи закрив клієнт вкладку, двічі оновив сторінку або використав другий пристрій.

Використайте збережений раніше платіжний референс Payora, а потім запитайте поточний стан транзакції. Порівняйте повернутий статус із тим, який потрібен для виконання замовлення. Якщо транзакція settled або confirmed, оновіть замовлення. Якщо pending, залиште замовлення в очікуванні. Якщо failed або canceled, не чіпайте замовлення.

До речі, саме тут багато власних PHP-сайтів і помиляються. Вони довіряють сторінці повернення, бо так швидше програмувати. Швидше — так. Безпечніше — ні. П’ятисекундна перевірка завжди краща за довгий ланцюжок листів у сапорті пізніше.

Якщо Payora надає підписаний callback або механізм серверного підтвердження, використовуйте його разом із перевіркою статусу. Так ви отримаєте дві перевірки: одну з потоку клієнта й одну з потоку сервера. Якщо вашій реалізації потрібна покрокова перевірка підпису, подивіться як тестувати криптоплатіж — там є дисципліна валідації, яка окупається ще до запуску.

Позначайте замовлення як оплачене лише тоді, коли сервер погодився. Не коли так сказав клієнт. Не коли так сказав браузер. Ваша база даних має відображати саме той стан оплати, який підтверджує Payora, бо саме на нього потім покладатимуться відділи виконання замовлень і бухгалтерія.

7. Збережіть запис платежу й обробляйте повторні надсилання

Зберігайте платіжний референс Payora, локальний ID замовлення, суму, валюту й фінальний статус у базі даних. Якщо можете, робіть це одним записом. Пізніше, коли клієнт напише: «Я оплатив двічі», вам знадобиться чистий запис, а не три напівзавершені оновлення.

Повторні надсилання трапляються з буденних причин. Клієнт двічі натиснув кнопку. Використали кнопку «Назад». Браузер повторив запит. Ваш PHP-код має виявити, що в замовлення вже є референс Payora, і відмовитися створювати другий платіж для того самого замовлення, якщо перший не провалився або не закінчився. У цьому й полягає суть ідемпотентності.

Добре працює просте правило: одне локальне замовлення — одна активна транзакція Payora. Якщо для того самого замовлення приходить другий запит, поки перший ще pending, покажіть існуюче посилання на оплату Payora замість створення нового. Якщо замовлення вже оплачене, нічого не робіть. Спокійно. І це мовчання — перевага.

Робіть назви колонок у базі конкретними. Наприклад, зберігайте payora_reference, payment_status, paid_at і last_checked_at. Ці поля допомагають сапорту, бухгалтерії й налагодженню. Якщо згодом знадобиться звірити платіж, ці чотири поля дадуть відповіді на більшість запитань без годинного перегляду логів.

Якщо ви будуєте потік рахунків для клієнтів, а не checkout магазину, стаття про криптоплатіжний шлюз для фрилансерів також може допомогти з тією ж логікою обліку, особливо там, де номер рахунка важливіший за кошик.

8. Протестуйте весь потік на staging-копії сайту

Перед запуском скопіюйте сайт на staging і протестуйте весь ланцюжок: створення замовлення, редирект у Payora, сторінку повернення, серверну перевірку та обробку подвійних кліків. Якщо ви тестуєте лише редирект, ви перевірили лише третину проблеми.

Виконайте щонайменше такі перевірки:

• Створіть нове замовлення й переконайтеся, що запит на оплату Payora сформовано.
• Оновіть сторінку повернення 2 рази й переконайтеся, що замовлення не змінилося знову.
• Надішліть форму оформлення двічі й перевірте, що існує лише 1 активна транзакція.
• Примусово отримайте pending або failed і підтвердіть, що замовлення залишається неоплаченим.
• Перевірте, що збережений референс Payora відповідає запису в базі даних.

Тестуйте на тій самій версії PHP і з тим самим серверним середовищем, яке плануєте використовувати в продакшені. Потік, що працює на локальному ноутбуці, може зламатися на бойовому сервері через суворіші SSL-налаштування або інші параметри cURL. Це не рідкість. Таке трапляється.

Остання практична перевірка: відкрийте замовлення в інкогніто-вікні, завершіть оплату, а потім відкрийте той самий URL повернення з другого браузера. Ваш застосунок не повинен робити друге оновлення платежу. Якщо робить — виправте це до запуску. Без винятків.

Для команд, які продають шляхи оформлення USDC разом з іншими методами оплати, нотатки в як приймати платежі в USDC допоможуть звірити очікування клієнтів ще до того, як ви відправите PHP-потік у продакшн.

Оце й останнє, що треба перевірити: те саме замовлення має пережити один редирект, одне оновлення сторінки й одне серверне підтвердження без розсинхронізації. Якщо так і є, ваше власне оформлення на PHP готове до першого живого платежу.